@@ -16,7 +16,8 @@ runtime or browser launcher. See the [native development guide](docs/NATIVE_DESK
 and the [goals](docs/NATIVE_GOALS.md) and [model routing](docs/NATIVE_ROUTING.md)
 workflows, [managed background processes](docs/NATIVE_BACKGROUND.md), and
 [native slash commands and project skills](docs/NATIVE_WORKFLOWS.md),
-[reviewed lifecycle commands](docs/NATIVE_HOOKS.md), and a
+[reviewed lifecycle commands](docs/NATIVE_HOOKS.md),
+[approved MCP stdio tools](docs/NATIVE_MCP.md), and a
 [native CLI](docs/NATIVE_CLI.md) that shares the active desktop engine or runs
 headlessly with its own profile.
 Development AppImage and Debian
 
@@ -119,6 +119,26 @@ reads all settings, `config key` reads a dotted key, and `config key value`
 validates and saves JSON or text. Use the configured environment variable or
 desktop secret editor for credentials; never put secret values in shell history.
 
+For [native MCP stdio integrations](NATIVE_MCP.md), register a JSON/YAML
+definition, inspect its command and hash, and explicitly enable it for the
+selected project:
+
+```sh
+shadowcode mcp add /path/to/definition.json
+shadowcode --json mcp
+shadowcode mcp enable config:my-tools --hash HASH_FROM_CATALOG
+shadowcode mcp disable config:my-tools
+shadowcode mcp remove config:my-tools --hash HASH_FROM_CATALOG
+```
+
+Registration is inert. `mcp add --hash CURRENT_HASH` replaces an existing global
+definition. Project files have IDs such as `project:.shadowcode/mcp/my-tools.yaml`.
+Each agent call still uses the same exact-argument approval flow as the window;
+noninteractive tasks stop for approval instead of accepting it automatically.
+Disabling affects new tasks; cancel running and queued tasks to end their
+existing grants. Native HTTP connections and `mcp serve/register` are still
+being migrated.
+
 ## One engine per profile
 
 The AppImage runtime extracts each invocation into a private temporary directory.
 
@@ -47,6 +47,11 @@ Project [lifecycle commands](NATIVE_HOOKS.md) can be reviewed and enabled in
 Settings → Hooks or through the same native CLI. Their command gates and
 completion checks run inside the native task lifecycle without Python callbacks.
 
+[Native MCP stdio servers](NATIVE_MCP.md) can be registered and enabled in
+Settings → MCP. The agent discovers their tools lazily and requests approval for
+each exact call. Connections close before the task finishes. HTTP and the
+ShadowCode MCP server remain part of the ongoing migration.
+
 To work on the live interface, run `./ui/node_modules/.bin/tauri dev` from the
 repository root. The Tauri configuration starts Vite and builds the native app.
 Build hooks explicitly use the `ui` directory, including when the CLI is invoked
 
@@ -1,11 +1,75 @@
 # Native MCP migration — development
 
 MCP remains an open [native release gate](NATIVE_MIGRATION.md). The Rust stdio
-client foundation is implemented and tested. Application registration,
-workspace/content activation, agent approvals, Settings/CLI integration,
-Streamable HTTP, built-in SQLite compatibility, and the ShadowCode MCP server
-still need their native implementation and verification. The stdio module alone
-does not enable MCP tools in the application.
+client now connects to native Settings, CLI registration, project activation,
+and individually approved agent tool calls. Streamable HTTP, built-in SQLite
+compatibility, the ShadowCode MCP server, and broader interoperability/real-model
+verification are still being migrated. Existing URL definitions remain visible
+and inactive; this development build does not silently launch the Python client.
+
+## Enable external tools
+
+In **Settings → MCP**, register a server with its name and a JSON array containing
+the executable and literal arguments, then review and enable it for the current
+trusted project. Registration and catalog refresh do not execute the command.
+Four servers may be enabled per project. A grant records the project's canonical
+path, the definition ID, and its SHA-256 content hash.
+
+Project definitions are direct `.yaml`, `.yml`, or `.json` files in
+`.shadowcode/mcp/` or `.shadow/mcp/`. For example:
+
+```json
+{
+  "name": "my-tools",
+  "command": ["/absolute/path/to/mcp-server", "--stdio"],
+  "description": "Tools for this project",
+  "timeout_sec": 30,
+  "env_refs": { "API_TOKEN": "MY_TOOLS_API_KEY" }
+}
+```
+
+`env_refs` maps child environment variables to names in the protected application
+secret store or the application's environment. Referenced values resolve only
+when a connection starts. Legacy literal `env` entries remain supported, but
+catalogs show only their variable names. Configured environment values are
+redacted from returned tool metadata and results; stderr is not put in task
+history. Avoid placing credentials in executable arguments, URLs, descriptions,
+or task prompts. External servers run with the user's OS privileges; activation
+is not an OS sandbox or a guarantee of network confinement.
+
+The same controls are available without a display:
+
+```sh
+shadowcode mcp add /path/to/definition.json
+shadowcode --json mcp
+shadowcode mcp enable config:my-tools --hash HASH_FROM_CATALOG
+shadowcode mcp disable config:my-tools
+shadowcode mcp remove config:my-tools --hash HASH_FROM_CATALOG
+```
+
+Project IDs use `project:.shadowcode/mcp/my-tools.yaml`. Global IDs use
+`config:my-tools`. Replacing a global definition with `mcp add` requires its
+current `--hash`. Removing it also removes its project grants, so re-registering
+identical content does not reactivate it. Project overlays cannot grant access.
+Changed or missing project definitions must be reviewed or disabled before a
+new Build task uses them.
+
+Build tasks with enabled servers receive two compact tools: `mcp_tools` discovers
+servers, lists tool names in pages of 20, or reads one exact tool schema;
+`mcp_call` requests a call to a server/tool with an argument object. Initialization
+is lazy and uses the explicit launch grant. Every `mcp_call` requires a separate
+session-scoped approval, even if the peer marks its tool read-only. The server
+ID, tool name, and complete arguments appear in that approval. Plan, Review,
+and untrusted projects cannot start MCP processes.
+
+Running and queued tasks retain their configuration snapshot. Disabling a grant
+or replacing a global registration applies to new tasks; cancel existing tasks
+to stop their current connections. Project files are re-read and their hash
+checked before each external action, including after an approval wait.
+Definitions cannot replace their command while an earlier approval is pending.
+MCP actions invalidate earlier file observations and disable parallel native
+reads for that task. Changes made by an external server are not checkpointed by
+ShadowCode's file tools.
 
 ## Stdio client foundation
 
@@ -19,7 +83,7 @@ The omitted crate license is retained from that same commit in
 The low-level `Client::connect` API starts only the literal command supplied by
 its caller, in a canonical project directory. It does not discover or activate
 servers. Callers must obtain server activation and exact tool approval before
-using it; those application controls are the next integration step. A server's
+using it; the application runner supplies those controls. A server's
 tool annotations, descriptions or instructions cannot supply approval.
 
 The child receives basic path/home/locale/XDG environment variables and explicitly
@@ -51,6 +115,8 @@ Unsolicited sampling fails and elicitation is declined. Interactive or backgroun
 task continuations returned from a tool are rejected rather than automatically
 supplying inputs or starting an unattended polling loop. A failed call does not
 prove that the remote tool made no changes; the client never retries it silently.
+A closed connection cannot return its old catalog as if it were still live;
+start a new task to reconnect after a protocol failure.
 
 ## Ownership and cancellation
 
@@ -63,13 +129,17 @@ Processes that deliberately escape their group are outside this user-level
 cleanup boundary.
 
 `Client::close` waits for cleanup. Dropping a client or abandoning its connection
-future triggers cleanup asynchronously; application task integration must await
-close before reporting task completion or releasing its workspace reservation.
+future immediately signals its group to stop; the cleanup worker reaps it.
+The application task loop awaits all connections before reporting completion or
+releasing the workspace, including provider errors, step limits, cancellation,
+and shutdown. Connections are scoped to one task and reused within that task.
+Durable `mcp.connected` and `mcp.closed` events retain the definition ID/hash
+and cleanup outcome without environment values.
 
 ## Verification
 
 ```sh
-cargo test -p shadowcode-core --test mcp_stdio --locked
+cargo test -p shadowcode-core --test mcp_stdio --test mcp_application --locked
 ```
 
 Ten regressions exercise real subprocess pipes, current and legacy protocol
@@ -80,6 +150,17 @@ stubborn descendant cleanup, leader reaping, stderr floods, protocol floods, and
 refusal of unsolicited sampling/credential requests. The small Node peer is a
 test fixture; no Node or Python runtime is added to the application.
 
-These checks validate the client foundation. They do not stand in for the
-remaining application permission, UI, HTTP, server, interoperability and real
-local-model checks required for the full MCP migration.
+Eight application regressions cover inert/symlink-confined discovery, malformed
+definitions, hidden credentials, project trust and permissions, definition
+hashes, removal/re-registration, exact argument approval and denial, connection
+reuse, error-result preservation, bounded single-pass credential redaction,
+closed-catalog rejection, stale file observations, read-only tasks, and
+process cleanup before actual engine completion on every exit path. The native
+CLI and real-window probes also exercise their respective controls; the window
+probe drives a scripted model through discovery, approval, a real subprocess
+tool result, and cleanup.
+
+These checks do not stand in for the remaining HTTP, server, interoperability,
+and real local-model checks required for the full MCP migration. The standalone
+application does not bundle runtimes for third-party servers: install whatever
+an explicitly selected external command requires separately.
@@ -146,9 +146,11 @@ The remaining orchestration/integrations, full desktop interaction/stress
 coverage, and release packaging are still in progress. The native
 branch is not yet a replacement for the 0.19 release.
 
-The [native MCP transport foundation](NATIVE_MCP.md) now has a bounded Rust stdio
-client and subprocess regressions. MCP application activation, agent-tool
-integration, HTTP transport and server migration remain open requirements.
+The [native MCP client](NATIVE_MCP.md) has bounded Rust stdio transport,
+inert Settings/CLI registration, explicit project/content activation, lazy tool
+discovery, individually approved calls, and task-owned process cleanup.
+HTTP transport, built-in SQLite compatibility, server migration, and broader
+interoperability/real-model verification remain open requirements.
 
 AppImage extraction now uses a source-pinned runtime patch with private
 per-invocation directories, signal forwarding, and checked cleanup. A dedicated
 
@@ -6,7 +6,7 @@ remain in [NATIVE_MIGRATION.md](NATIVE_MIGRATION.md).
 
 ## Automated checks
 
-`cargo fmt --all --check`, Clippy with warnings denied, and all **117 native
+`cargo fmt --all --check`, Clippy with warnings denied, and all **136 native
 integration tests** pass on the development machine. The suite covers:
 
 - Config validation, private secrets, untrusted project overlays, profile locks,
@@ -71,6 +71,13 @@ integration tests** pass on the development machine. The suite covers:
   checks, queued manifest changes, compaction and
   provider failure. Output floods, timeouts, cancellation and engine shutdown
   assert that recorded parent/child processes actually stop.
+- MCP stdio negotiation, framing/catalog bounds, exact arguments, error results,
+  denied sampling/elicitation, inert registration, workspace/hash activation,
+  literal environment privacy, single-pass credential redaction, exact tool-call
+  approval and denial, stale definitions during approval, read-only exclusion,
+  connection reuse and closed-catalog rejection. Engine success, provider errors,
+  step limits, cancellation and shutdown all wait for process cleanup. The test
+  peer is Node-based test infrastructure, not a bundled application dependency.
 
 The host's distro `rustdoc` needs its LLVM library directory in the loader path
 for doc tests. The full suite was run with:
@@ -94,6 +101,12 @@ and disables it. There are nine scenario groups with 27 scripted model requests.
 Actual pseudo-terminal sessions cover approval, denial, and Ctrl-C while a
 prompt is waiting. Noninteractive requests never silently grant approval.
 
+The MCP update passes 11 CLI scenario groups with 30 scripted model requests.
+It adds inert server registration, hidden environment values, exact-hash
+activation, disable/removal, refusal without a terminal, and actual PTY approval
+of a displayed server/tool/argument object. A real MCP subprocess returns the
+expected result and its recorded process group is stopped before CLI exit.
+
 The probe also hosts `serve`, starts and stops background commands, reads their
 logs, runs a task alongside them, observes and cancels detached work, and approves
 a waiting task from another CLI. SIGINT/SIGTERM/SIGHUP, a closed stdout pipe, remote
@@ -122,7 +135,7 @@ sessions existed. A regression now covers real session listing and literal
 search. Visual inspection also found a cancellation transcript race and an open
 sidebar obscuring a resized compact window; the window test checks both.
 Axe WCAG 2 A/AA and 2.1 AA checks pass in light, dark, compact, Goals, Router,
-Background, Skills, and Hooks workspace views. The compact check caught the Review button losing its accessible name
+Background, Skills, Hooks, and MCP workspace views. The compact check caught the Review button losing its accessible name
 when its text was hidden; the control now retains an explicit label.
 The native test also creates a goal through the drawer, completes all three
 milestones, approves its verification command, checks the resulting file and
@@ -239,10 +252,27 @@ deterministic fork regression reproduces that failure in the old implementation;
 the shared guard still keeps the profile locked while owned background cleanup
 is running. A forked copy cannot unlock its parent's live guard.
 
+The profile-lock fix and runtime source changes passed the complete
+[CI run for 0f6de80](https://github.com/ShadowfetchLinux/ShadowCode/actions/runs/35522325919),
+including clean-runner compilation, both package formats, offline runtime source
+rebuild, runtime lifecycle stress, and the packaged CLI/window. The later MCP
+integration is recorded separately; this green run does not certify it.
+
 OS dialog interaction, notification delivery, broader stress/accessibility
 coverage, corresponding sources for remaining redistributed components,
 and the final installed release still need their release-gate checks.
 
+The MCP window update passes 17 scripted model requests and nine Axe views. It
+registers a server through Settings, confirms registration is inert, enables the
+reviewed definition, displays the exact call arguments, approves an actual MCP
+subprocess request, checks the redacted result reaches the model, waits for
+process cleanup, and disables/removes the registration. Visual review uses
+`artifacts/native/mcp.png`; the complete run is recorded in
+`artifacts/native/result.json`. The test exposed notifications covering Close
+and Send controls; dialogs now stay above transient messages and notification
+bodies no longer intercept clicks. The registration form collapses after adding
+a server so its reviewed command and controls stay in view.
+
 ## Real local models
 
 `scripts/probe-native-hooks.mjs` tests an installed Ollama model through the
 
@@ -85,6 +85,11 @@ pub enum Command {
         #[arg(long, requires = "enable")]
         hash: Option<String>,
     },
+    /// List inert MCP definitions, register one, or review a project activation.
+    Mcp {
+        #[command(subcommand)]
+        action: Option<Mcp>,
+    },
     /// List/search saved conversations, or rename/delete a unique ID prefix.
     Sessions {
         query: Option<String>,
@@ -157,6 +162,30 @@ pub enum Command {
     /// Run the shared engine without a window until Ctrl-C or SIGTERM.
     Serve,
 }
+#[derive(Debug, Subcommand)]
+pub enum Mcp {
+    /// Register a JSON/YAML definition; does not launch or enable it.
+    Add {
+        definition: PathBuf,
+        /// Current definition hash when replacing an existing registration.
+        #[arg(long)]
+        hash: Option<String>,
+    },
+    /// Allow this exact server definition to start for new Build tasks here.
+    Enable {
+        server: String,
+        #[arg(long)]
+        hash: String,
+    },
+    /// Revoke this project's activation for future tasks.
+    Disable { server: String },
+    /// Remove a global registration and its project activations.
+    Remove {
+        server: String,
+        #[arg(long)]
+        hash: String,
+    },
+}
 #[derive(Debug, Args)]
 pub struct Run {
     pub task: String,
 
@@ -21,7 +21,7 @@ use crate::{
 };
 use anyhow::{bail, ensure, Context, Result};
 pub use args::Options;
-use args::{Background, Command, Run, TaskOptions};
+use args::{Background, Command, Mcp, Run, TaskOptions};
 use backend::Backend;
 use clap::Parser;
 use serde_json::{json, Value};
@@ -358,6 +358,56 @@ async fn execute(backend: &Backend, workspace: &Path, options: &Options) -> Resu
                 backend.call("GET", "/api/hooks", Value::Null).await?
             }
         }
+        Command::Mcp { action } => match action {
+            None => backend.call("GET", "/api/mcp/servers", Value::Null).await?,
+            Some(Mcp::Add { definition, hash }) => {
+                use std::io::Read;
+                let file = std::fs::File::open(definition).context("Cannot open MCP definition")?;
+                ensure!(
+                    file.metadata()?.is_file(),
+                    "MCP definition must be a regular file"
+                );
+                let mut text = String::new();
+                file.take(32_001).read_to_string(&mut text)?;
+                ensure!(text.len() <= 32_000, "MCP definition exceeds 32 KB");
+                let definition: Value = serde_yaml_ng::from_str(&text)
+                    .map_err(|_| anyhow::anyhow!("Invalid MCP JSON/YAML definition"))?;
+                backend
+                    .call(
+                        "POST",
+                        "/api/mcp/servers",
+                        json!({"definition":definition,"hash":hash.as_deref().unwrap_or("")}),
+                    )
+                    .await?
+            }
+            Some(Mcp::Enable { server, hash }) => {
+                backend
+                    .call(
+                        "POST",
+                        "/api/mcp/activation",
+                        json!({"workspace":workspace,"server":server,"hash":hash,"enabled":true}),
+                    )
+                    .await?
+            }
+            Some(Mcp::Disable { server }) => {
+                backend
+                    .call(
+                        "POST",
+                        "/api/mcp/activation",
+                        json!({"workspace":workspace,"server":server,"enabled":false}),
+                    )
+                    .await?
+            }
+            Some(Mcp::Remove { server, hash }) => {
+                backend
+                    .call(
+                        "POST",
+                        "/api/mcp/servers/delete",
+                        json!({"server":server,"hash":hash}),
+                    )
+                    .await?
+            }
+        },
         Command::Status => {
             let mut status = backend
                 .call("GET", "/api/workspace/status", Value::Null)