---
title: MCP Overview
description: "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."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

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.

<Info>
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.
</Info>

## How it fits together

<Steps>
  <Step title="Boot">
    `executor/tool` loads the agent manifest and the `Manager` spawns each declared MCP server (subprocess for `stdio`, client for `http`).
  </Step>
  <Step title="Verify (the bijection)">
    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).
  </Step>
  <Step title="Resolve">
    When a plan emits a `matrix://tool/mcp/<alias>/<tool>@<version>` URI, the registry resolves it against the manifest and dispatches the call.
  </Step>
  <Step title="Gate">
    The capability gate checks the call against the skill's `§TOOLS` allowlist and the manifest's `allowed_side_effects` before any side effect runs.
  </Step>
</Steps>

## The tool URI scheme

```text
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.

```json
"env": ["GITHUB_TOKEN=$env:GITHUB_TOKEN"]
```

<Columns cols={2}>
  <Card title="Agent manifests" icon="file-code" href="/mcp/agent-manifests">
    The manifest schema, field by field.
  </Card>
  <Card title="Tool-server catalog" icon="plug" href="/mcp/tool-servers">
    The servers the default agent ships with.
  </Card>
</Columns>