# MCP extension The MCP extensions provide session-owned connections and expose discovered operations through Python. Configured servers and editor-provided servers have separate host routes but share the `mcp` binding. See [MCP extension](../src/albedo/harness/extensions/mcp/extension.gleam) and [Python binding](../priv/python/albedo_plugins/mcp.py). ## Configure servers The `mcp` settings section accepts `stdio` and `http` servers. Stdio requires `command` and accepts `args`, `cwd`, and `env`. HTTP requires `url` and accepts `headers` and `bearerTokenEnvVar`. Environment and header values can be literal strings or environment references. Servers default to enabled. `enabledTools` and `disabledTools` select tools. Startup and call timeouts default to 20,000 and 60,000 milliseconds. Both must be positive and at most 3,600,000 milliseconds. `retryMs` defaults to 30,000. See `server_decoder` and `config_section` in [extension.gleam](../src/albedo/harness/extensions/mcp/extension.gleam). The daemon's `mcp` settings group saves definitions in `extensions.json` and secrets in `creds.json`. It reaches the configured extension's checks through its `McpServersPlugin`, described in [plugins](plugins.md#mcp-settings-and-editor-probes). [`servers.gleam`](../src/albedo/harness/extensions/mcp/servers.gleam) owns `validate_settings`, server names, the URL rule, and the client transport. Validation never resolves environment references. A transport resolves them when it is built. [`secrets.gleam`](../src/albedo/harness/extensions/mcp/secrets.gleam) reads a server's `creds.json` entry. It refuses a `creds.json` that is not a regular file, is larger than 1 MiB, or grants group or other permissions. [`daemon/settings.gleam`](../src/albedo/daemon/settings.gleam) calls `validate` for each changed server and `check` when `validate_connection` is true. It calls `signed_out` when a patch sets `oauth` to null. These checks run while `mcp` is disabled. If no installed extension contributes the plugin, a patch that saves a server fails with `503 mcp_unavailable`. Removing a server still works. An HTTP server's OAuth sign-in comes from `sign_in.resolve`. Its `keep` callback writes the credential into the server's `creds.json` entry and keeps the registration of an earlier sign-in. Its exchange checks the `issuer` on the `oauth.Grant` it receives against the authorization server's issuer. See [sign-in](auth.md#sign-in). [`oauth.gleam`](../src/albedo/harness/extensions/mcp/oauth.gleam) owns discovery, client registration, the token exchange, and the token a request sends. A token response must name the `bearer` type, case-insensitively, or leave `token_type` out; any other value, including one that is not a string, refuses the token. Refreshes of one server are single-flight within the daemon. Record updates hold the settings lock through [`sdk/settings_documents`](../src/albedo/harness/sdk/settings_documents.gleam). ## Tools and lifecycle The configured extension prepares an owned managed contribution. It saves the last catalogue by server name and configuration fingerprint. An unavailable server produces a warning. The session can refresh when its catalogue changes. The host closes the connection when the contribution closes. Cold clients monitor both the preparer and runtime before opening their transport, through discovery and catalogue saving. Ownership transfers to a connector before preparation returns. See `prepare` and `initialise_catalogues` in [extension.gleam](../src/albedo/harness/extensions/mcp/extension.gleam). [`bundle.gleam`](../src/albedo/harness/extensions/mcp/bundle.gleam) owns the prepared bundle: preparation entrypoints, calls, adoption, close, and the settings and editor probes. Server names, descriptions, and results are untrusted data. A failed or interrupted call may have had effects, so inspect those effects before retrying. A server-reported error appears in `isError`. A host failure raises `McpError`. See [extension.gleam](../src/albedo/harness/extensions/mcp/extension.gleam) and [mcp.py](../priv/python/albedo_plugins/mcp.py). [`dispatch.gleam`](../src/albedo/harness/extensions/mcp/dispatch.gleam) builds each call's request and refuses a result larger than 4 MiB. `bundle.call` runs it in a worker that it kills 250 milliseconds after the operation's timeout. It then closes that server's client, because a request the server never answered leaves the connection in an unknown state. ## Catalogue policy and cache [`catalogue.gleam`](../src/albedo/harness/extensions/mcp/catalogue.gleam) owns filtering, advertised identifiers, operation schemas, summaries, and context and Python definition rendering. Operations and summaries stay typed inside the runtime. Schemas retain the server's native JSON-compatible values without a JSON text round trip. Keep feature policy here and follow the [shared contribution rules](contributing.md#write-gleam-and-keep-values-typed). Tool and resource list failures fail discovery. Resource templates and prompt lists are optional and become empty on failure. Discovery preserves server order and permits at most 256 selected tools per server. The joined catalogue permits at most 512 operations and rejects duplicate advertised identifiers. Descriptions and resource identifiers are bounded untrusted text. [`param_headers.gleam`](../src/albedo/harness/extensions/mcp/param_headers.gleam) validates `x-mcp-header` annotations and converts call arguments to header values. HTTP discovery warns and excludes a tool with invalid annotations. Stdio discovery retains that tool without mirrored headers. `catalogue.encode` and `catalogue.saved` write and read the existing version 2 external-term cache through [`albedo_bytes/term_codec`](../packages/albedo_bytes/src/albedo_bytes/term_codec.gleam). The cache holds atom-keyed maps, not Gleam records. Keep that saved shape compatible with existing catalogues. `saved` decodes safely, so it creates the cache's atoms first; add any new key to `cache_atoms`. `servers.fingerprint` keys each saved catalogue, so keep its term encoding stable as well. [`client.gleam`](../src/albedo/harness/extensions/mcp/client.gleam) owns each connection's process and its stdio port, which it opens, writes and reads through [`albedo_ports`](../packages/albedo_ports/src/albedo_ports.gleam). The extension keeps no Erlang. [`servers.gleam`](../src/albedo/harness/extensions/mcp/servers.gleam) resolves daemon variables, executables, and the launcher path. A stdio server's port unsets every daemon variable except a short safe list, then sets the server's own. See `exact_environment` in [`albedo_ports/subprocess`](../packages/albedo_ports/src/albedo_ports/subprocess.gleam). ## Preparation and connection ownership [`preparation.gleam`](../src/albedo/harness/extensions/mcp/preparation.gleam) owns cached versus cold discovery and bundle sequencing. A thrown cache save closes the newly discovered client and earlier cold clients. Catalogue validation precedes watcher and connector allocation. A failed connector handoff closes completed connectors and clients still awaiting transfer. [`connector.gleam`](../src/albedo/harness/extensions/mcp/connector.gleam) owns connection, dial, refresh, waiter, and lifetime decisions. The connector process in [`connection.gleam`](../src/albedo/harness/extensions/mcp/connection.gleam) owns monitors and attempts, with typed messages. Each dial attempt retains its client until client ownership transfer is acknowledged. The connector then acknowledges the attempt before answering waiters. Obsolete dial results close their own clients. A live connection remains usable during catalogue refresh. [`watcher.gleam`](../src/albedo/harness/extensions/mcp/watcher.gleam) owns reason accumulation, activity coalescing, and completion-relative probe backoff. The watcher process in the same module probes offline servers only on session activity, without an idle polling timer. Coalesced events retain the first callback, and refresh runs only when a turn has ended. Reasons remain pending until replacement. Readiness, adoption, and runtime publication are separate acknowledgments. Close uses bounded waits and can leave transport cleanup to owner-death handling after forced connector termination. Do not interpret connector death alone as confirmation that an external process has been reaped. Follow the [shared lifecycle rules](contributing.md#preserve-extension-lifecycle-boundaries). [`owned.gleam`](../src/albedo/harness/extensions/mcp/owned.gleam) starts the connectors and the watcher. Each monitors the preparer and the runtime before it initializes. Until the runtime adopts it, it answers only adoption and stop, and its business messages stay queued. Only the runtime may adopt, and a repeated adoption by the runtime succeeds. Adoption drops the preparer monitor; the runtime's death still ends the process. `bundle.adopt` adopts the connectors in order and then the watcher, stopping at the first refusal. `bundle.close` stops them all within one shared deadline and is idempotent. Owned processes trap exits, so a crashed dial or refresh worker settles its attempt, and killing a connector also ends its linked workers. `endpoint.Seams` names the discovery, client transfer, and connector start points that the [ownership tests](../test/harness/mcp_ownership_test.gleam) hold or fail. Production passes `endpoint.seams()`. Drive new lifecycle tests through the bundle's API and these seams, not through process internals. ## Editor servers over ACP `editor-mcp` obtains the editor's session overlay and uses `editor_mcp` routes. Its overlay and catalogues live in daemon memory. The editor cannot reuse a configured server name. See `editor_extension` and `prepare_editor` in [extension.gleam](../src/albedo/harness/extensions/mcp/extension.gleam), and [ACP](acp.md). The shared server configuration types live in [`sdk/editor_mcp`](../src/albedo/harness/sdk/editor_mcp.gleam). `prepare_editor` calls `Preparation.editor_overlay`, which the host binds to [`acp_overlay.resolve`](../src/albedo/daemon/acp_overlay.gleam). It authorizes the marker and captures catalogue lookup and save operations for that revision. The attachment owner rejects a save after the overlay changes. Keep this captured capability through preparation rather than looking up a newer overlay halfway through it. ## From Python `await mcp.tools()` lists operations, `await mcp.search(query)` ranks them, and `await mcp.describe(name)` returns a schema. `await mcp.call(name, arguments)` calls an advertised name or `server/tool`. The binding also mints `mcp..` methods from the catalogue at kernel boot. Operations added later or whose names cannot be minted remain reachable through `call`. See [mcp.py](../priv/python/albedo_plugins/mcp.py). ## Outbound routing The `mcp` [outbound route](network.md) applies to remote HTTP servers, discovery, and OAuth. A client resolves it when it starts and keeps it until it restarts. Stdio servers are not routed. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [ACP adapter](acp.md) - [Skills extension](skills.md)