Browse documentation

Technical documentation / Reference

MCP stdio and HTTP tools

Feature docs index · Repository README

Configure Model Context Protocol (MCP) servers so their tools appear beside magi-code's built-ins. You can diagnose setup without provider credentials.

Supported transports:

Configuration and approval

Server definitions use the Claude-style .mcp.json convention, not a universal MCP specification. magi-code loads CONFIG_DIR/.mcp.json, then cwd/.mcp.json; CONFIG_DIR is the resolved MC_HOME (default ~/.magi-code). It does not search parent directories. A project server replaces the entire global definition with the same name, not individual fields.

Example .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["${MCP_SERVER_DIR}/server.js"],
      "env": { "MCP_ROOT": "${MCP_ROOT:-/tmp/mcp-root}" }
    },
    "remote_search": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_REMOTE_SEARCH_TOKEN}",
        "X-Team": "platform"
      },
      "timeout": 30
    },
    "my_oauth_server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "client_id": "your-client-id",
        "scopes": ["read", "tools"],
        "authorization_server": "https://auth.example.com"
      }
    }
  }
}

All servers are disabled until approved. An enabled field in .mcp.json cannot grant approval. In Mission Control, /mcp shows each server's approval status and current redacted definition. Up/Down selects a server, PageUp/PageDown scrolls its definition, Enter approves or revokes it, and Esc closes. Changes apply on the next launch, not immediately or after /new.

Approvals live only in global settings.json at capabilities.mcp_approvals[canonical_source_path][name]. An approved entry contains {"version": 1, "digest": "<64 lowercase hex characters>"}. A revoked entry is false. Missing, malformed, unsupported-version, and unbound boolean approvals do not authorize execution. The view distinguishes never approved, revoked, definition changed, renewal required, and invalid approval states.

The digest is an HMAC-SHA-256 commitment to the parsed, unexpanded definition, canonical source path, and server name. Its random key lives separately in $MC_HOME/mcp-approval.key, with owner-only 0600 permissions on Unix. Do not share or commit this key. Losing or replacing it requires approval again. Approval records contain no definitions, credentials, or expanded environment values.

The definition covers transport, command, ordered arguments, environment names and values, URL, header names and values, timeout, and all OAuth settings. Object order and document whitespace do not matter. Parser defaults, including omitted type: stdio, empty collections, and the 30-second timeout, normalize consistently. String contents, argument order, URL paths/queries, and environment reference names or fallback expressions remain significant. The definition's enabled field is excluded.

An approval action carries the displayed source and fingerprint. Saving re-reads the definition and rejects a stale action instead of approving changed contents. Failed saves refresh the view without claiming success. Historical definitions are not stored, so the view reports invalidation without a field-by-field change history. Project settings cannot approve servers. A same-name replacement in another source requires its own approval.

Loading validates approval before expanding that same definition for launch. Newly loaded definitions must pass this check before startup or reconnection, including serve --stdio, which never prompts for MCP approval. Existing connections and already-started calls retain their snapshot until normal shutdown.

Changing an environment value behind an unchanged reference does not invalidate approval, even when that changes the effective command or endpoint. This binds configuration, not runtime identity: executable contents, PATH resolution, DNS, and remote behavior are not pinned. It is not a sandbox.

FieldBehavior
typestdio (also the default when omitted) or http.
command / args / envStdio only. Command is spawned directly. The child starts with PATH plus the Windows startup baseline, then receives the explicit env overlay.
urlHTTP only. HTTPS required except explicit loopback HTTP (localhost, 127.0.0.0/8, or [::1]). URL credentials and redirects are rejected.
headersHTTP only. Values support environment expansion. Static Authorization / Proxy-Authorization are mutually exclusive with oauth.
oauth.client_idOptional public client id. If omitted, dynamic client registration is used when advertised.
oauth.scopesOptional requested scopes.
oauth.authorization_serverOptional authorization-server override.
timeoutOptional seconds per request; defaults to 30, max 300.

Discovery parses every definition's structural fields, including server names, transport types, required fields, and JSON value types. Structural errors can block loading even for disabled servers. Only enabled entries expand environment references and validate runtime fields such as commands, URLs, headers, and timeouts. Missing environment variables in disabled entries do not block loading. Enabling through /mcp expands and validates the selected definition before saving approval; failure leaves the saved approval unchanged.

For enabled entries, ${VAR} and ${VAR:-default} expand once while loading command, each argument, environment values, URL, and header values. A missing variable without a default fails configuration loading. Defaults apply to unset variables; an empty variable stays empty. Expansion is not recursive or shell evaluation. Use environment references rather than storing secrets in .mcp.json.

Stdio servers that locate configuration or a daemon through the home directory must receive it explicitly, for example "env": { "HOME": "${HOME}" } for cua-driver mcp. Ambient HOME is not inherited.

HTTP timeout bounds each request. Cancellation is checked before and around an HTTP request, but an in-flight blocking POST/body cannot be interrupted; notifications/initialized uses the same path. Stdio and pending-response waits remain cancellation-responsive.

Initialization requests MCP 2025-06-18 and accepts a negotiated response of 2025-06-18 or 2025-03-26. Other versions fail initialization. HTTP requests after initialization carry the negotiated version in MCP-Protocol-Version.

Calls to the same server can overlap, including calls from parallel subagents. Request IDs correlate replies; connection shutdown remains exclusive. Canceling or timing out an admitted request closes the shared connection and fails pending siblings, so later calls need a new connection. A call canceled before admission does not close it. In-flight blocking HTTP POSTs still run until completion or their timeout. OAuth token acquisition/refresh is serialized within the shared provider; tool POSTs are not.

HTTP security rules

OAuth HTTP authentication

OAuth is explicit and interactive:

magi-code mcp login my_oauth_server
magi-code mcp logout my_oauth_server
magi-code mcp list

Behavior:

Token storage:

Security and limits:

Tool names

Discovered MCP tools are namespaced as:

mcp__<server>__<tool>

Example: server filesystem tool read_file becomes mcp__filesystem__read_file. Qualified names must be exactly mcp__<server>__<tool> and no more than 64 bytes total (UTF-8; current safe components are ASCII). Both components must be non-empty and use only ASCII letters/digits/_/-; neither may contain __. Only server names cannot end with _; tool names may end with _. These restrictions keep the server/tool separator unambiguous.

Tool call arguments

Direct provider calls and Code Mode share the same MCP call schema: required nonblank intent plus required arguments object. intent explains why the tool is needed; arguments contains the server's inputs. Even tools with no inputs require arguments: {}.

tools.call("mcp__filesystem__read_file", {
  intent: "Read the project setup instructions",
  arguments: {path: "README.md"}
});

The harness validates intent before execution and forwards only arguments to the MCP server. Server-owned fields, including any intent field inside arguments, remain unchanged. The outer call rejects fields other than intent and arguments. Session history and hooks retain the full call. Built-ins use the same intent validation without the MCP argument wrapper; client-registered tools keep their declared schemas without an added intent requirement.

Server messages and live tool discovery

Servers may send requests while idle or during tool calls. ping receives an empty result; other methods receive -32601 Method not found. No roots, sampling, or elicitation capabilities are advertised. Replies preserve integer or string IDs (up to 256 bytes); unusable IDs are ignored. Each server is limited to 32 replies per one-second window. Stdio writes share the existing serialized writer; HTTP uses one blocking reply worker with at most 32 queued replies and the current session, protocol, and authentication headers.

Servers advertising capabilities.tools.listChanged: true can send notifications/tools/list_changed. Notifications coalesce until the next user turn. Before preparing that turn, the worker repeats paginated tools/list with the normal timeout, cancellation, naming, schema conversion, and route validation. Other servers keep their startup snapshot.

An invalid or failed refresh retains the previous snapshot and schedules one retry at the next user turn. Further attempts require another notification. /mcp shows the retained tool count and stale status. No refresh happens during provider requests or their continuations. Calls already dispatched may finish; later calls to removed names use the normal unknown-tool path.

Each run and its children retain a frozen catalog, even if another conversation refreshes the shared manager. Refreshed tools still pass through configured permissions, task ceilings, inspection restrictions, subagent profiles, and independent direct/Code Mode exclusions. Sorted tool-definition digests avoid replacing an unchanged snapshot; the final advertised definitions contribute to the prompt-cache key.

Approval covers the canonical source, server name, and unexpanded server definition—not discovered tools. Tool changes need no re-approval. Changing the server definition still requires approval renewal and restart.

Diagnostics

Diagnostics read the resolved configuration directory, global settings approvals, and both .mcp.json sources. They do not attach/create sessions or require provider auth.

magi-code mcp list

Prints configured servers, type, enabled/disabled state, OAuth auth status when configured, and connection result. Enabled servers are started long enough to run initialize and tools/list; failures are reported with phase diagnostics on stderr. HTTP servers are shown as http <sanitized-url>. The command exits 0 if the list command itself ran, even when individual servers fail.

magi-code mcp test remote_search

Starts only the selected server, runs initialize and tools/list, prints server name/version/protocol plus discovered tool names/descriptions, then shuts down. For HTTP servers, shutdown sends best-effort session DELETE when the server issued an MCP session id. It exits non-zero for missing, disabled, spawn/connect, initialize, or list failures.

Startup policy by interface

magi-code mcp list and magi-code mcp test diagnose servers without opening a conversation. List reports individual failures without blocking other servers. Mission Control requires every enabled MCP server to connect, initialize, and discover tools before running queued prompts. If startup fails, it restores the terminal, exits nonzero, and leaves the queue unrun.

Mission Control requests cancellation before cleanup. Critical/provider worker joins are bounded at 2 s each before detach/error, but an in-flight HTTP POST/body (including notifications/initialized) cannot observe cancellation. The 2 s critical join may detach the worker while it remains subject to that server's configured request timeout (30 s default, 300 s maximum). Terminal restoration happens first. Pre-request cancellation and stdio/pending-response paths remain responsive; detaching a non-cooperative worker does not guarantee that it will have no side effects.

Supported MCP surface

Supported now:

Not supported:


Back to feature docs · Back to repository README

Edit this page on GitHub ↗