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 and
Python binding.
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.
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.
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 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 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.
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.
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.
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 and
mcp.py.
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 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.
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
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.
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 owns each
connection's process and its stdio port, which it opens, writes and reads
through albedo_ports. The
extension keeps no Erlang.
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.
Preparation and connection ownership #
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 owns
connection, dial, refresh, waiter, and lifetime decisions. The connector process
in 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 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.
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 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, and
ACP.
The shared server configuration types live in
sdk/editor_mcp. prepare_editor
calls Preparation.editor_overlay, which the host binds to
acp_overlay.resolve. 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.<server>.<tool> methods from the catalogue at kernel boot. Operations
added later or whose names cannot be minted remain reachable through call. See
mcp.py.
Outbound routing #
The mcp outbound route 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.