MCP Overview
How Matrix uses the Model Context Protocol — DID-bound agent manifests, the matrix:// tool URI scheme, stdio/http transports, the exhaustive-tools bijection check, and credential refs.
Matrix agents reach the outside world exclusively through MCP (Model Context Protocol) tool servers. An agent's capabilities are defined by a DID-bound JSON manifest that declares which MCP servers it may spawn and exactly which tools each advertises.
Off-chain tools dispatch through MCP by design (locked decision Q4) — there is no custom fs/shell/http path. Everything an agent can do is an MCP tool resolved against its manifest.
How it fits together
executor/tool loads the agent manifest and the Manager spawns each declared MCP server (subprocess for stdio, client for http).
The manager checks that the tools the server actually advertises match the manifest's tools list exactly — declared must equal discovered. Drift is rejected at boot (Q21).
When a plan emits a matrix://tool/mcp/<alias>/<tool>@<version> URI, the registry resolves it against the manifest and dispatches the call.
The capability gate checks the call against the skill's §TOOLS allowlist and the manifest's allowed_side_effects before any side effect runs.
The tool URI scheme
matrix://tool/mcp/<server-alias>/<tool-name>@<version>URIs must be version-pinned (@<semver> or @sha256:…) — bare-head URIs raise ErrUnpinnedTool at parse time (Q17).
Transports
| Transport | When |
|---|---|
stdio | Local subprocess servers (npx, uvx, node, python3). |
http | Streamable-HTTP remote servers. |
SSE-only transport is deferred (Q15).
Credentials
Server credentials are $env:NAME references in the manifest's env or headers, resolved from the executor's process environment at spawn time. Literal credentials in a manifest are forbidden — manifests are content-addressed and may be shared or journaled into cortex.
"env": ["GITHUB_TOKEN=$env:GITHUB_TOKEN"]