MCP Overview
How Matrix uses the Model Context Protocol for its tool surface: agent manifests, tool registration, the matrix:// URI scheme, stdio and http transports, bijection verification, and credential handling.
Matrix agents interact with 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 server advertises.
Off-chain tool dispatch goes through MCP by design. There is no custom filesystem, shell, or HTTP path. Everything an agent can do is an MCP tool resolved against its manifest.
How it fits together
The executor loads the agent manifest and the Manager spawns each declared MCP server (subprocess for stdio, client for http).
The manager checks that the tools each server actually advertises match the manifest's tools list exactly. Declared must equal discovered. Any drift is rejected at boot.
When a plan emits a matrix://tool/mcp/<alias>/<tool>@<version> URI, the registry resolves it against the manifest and dispatches the call to the correct server.
The capability gate checks the call against the skill's §TOOLS allowlist and the manifest's allowed_side_effects before any side effect executes.
The tool URI scheme
matrix://tool/mcp/<server-alias>/<tool-name>@<version>URIs must be version-pinned (@<semver> or @sha256:...). Bare-head URIs without a version are rejected at parse time.
Tool registration
Each MCP server in a manifest declares an exhaustive tools array. Every tool entry carries:
| Field | Purpose |
|---|---|
name | The tool's identifier, matching what the server advertises. |
description | Human-readable summary of what the tool does. |
side_effect_class | One of read, write, network, or shell. |
timeout_ms | Optional per-tool timeout override. |
A call only executes if its side_effect_class appears in both the manifest's allowed_side_effects and the calling skill's tool allowlist.
Transports
| Transport | When to use |
|---|---|
stdio | Local subprocess servers launched via npx, uvx, node, or python3. |
http | Streamable-HTTP remote servers (e.g., hosted APIs). |
Each transport has its own launch configuration. stdio servers require command and args; http servers require url and optional headers.
Credentials
Server credentials are $env:NAME references in the manifest's env or headers arrays, resolved from the executor's process environment at spawn time. Literal credentials in a manifest are forbidden, since manifests are content-addressed and may be shared or journaled.
"env": ["GITHUB_TOKEN=$env:GITHUB_TOKEN"]Agent discovery
Agents are defined as JSON files in the agents/ directory. Each manifest declares its agent DID (matrix://agent/<name>), its allowed_side_effects, and its full servers array. At boot, the executor reads the manifest, spawns each server, verifies the tool bijection, and makes the tools available to the planning layer.
The native_tools field in a manifest is the reserved slot for chain-level tools that bypass MCP entirely (e.g., precompile reads). These are resolved through a separate path and do not go through the MCP transport.