---
title: Agent Manifests
description: "The JSON-on-disk agent manifest format — schema_version, agent DID, allowed_side_effects, the servers array with transport/command/args/env/package_digest/version/tools, and the locked design rules."
---

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

An **agent manifest** is a JSON-on-disk description of what tools a Matrix agent has access to. It is loaded by `executor/tool` at boot; the canonical Go types live in `executor/tool/manifest.go` (`AgentManifest`, `ServerEntry`, `ToolEntry`, `NativeToolEntry`).

## Files

| File | Purpose |
| --- | --- |
| `agents/default.json` | The per-user baseline agent for v1. Starting point for fork-and-customize. |
| `agents/neo.json` | Neo's conversational-agent manifest. |
| `agents/forge.json` | Forge agent manifest. |

## Schema

```json
{
  "schema_version": 1,
  "agent": "matrix://agent/default",
  "description": "…",
  "allowed_side_effects": ["read", "write", "network", "shell"],
  "servers": [
    {
      "alias": "fs",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "env": [],
      "package_digest": "sha256:0000…",
      "version": "2026.1.14",
      "tools": [
        {"name": "read_text_file", "description": "Read the contents of a text file", "side_effect_class": "read"},
        {"name": "write_file", "description": "Write content to a file", "side_effect_class": "write"}
      ]
    }
  ]
}
```

### Fields

| Field | Meaning |
| --- | --- |
| `schema_version` | Manifest schema version (currently `1`). |
| `agent` | The agent's `matrix://agent/<name>` DID. |
| `allowed_side_effects` | The side-effect classes this agent may perform (`read`, `write`, `network`, `shell`). |
| `servers[].alias` | Short name used in tool URIs (`matrix://tool/mcp/<alias>/…`). |
| `servers[].transport` | `stdio` or `http`. |
| `servers[].command` / `args` | How to spawn a `stdio` server. |
| `servers[].env` / `headers` | Credential refs (`$env:NAME`). |
| `servers[].version` | Server version (forms the tool URI pin). |
| `servers[].package_digest` | sha256 of the published package (`sha256:<64-hex>`). |
| `servers[].tools[]` | The **exhaustive** list of tools the server advertises, each with a `side_effect_class`. |

## Locked design rules

| # | Rule |
| --- | --- |
| Q15 | Transports = `stdio` + `http` (streamable HTTP); SSE-only deferred. |
| Q17 | Tool URI scheme: `matrix://tool/mcp/<server-alias>/<tool-name>@<version>`. |
| Q18 | Credentials via `$env:NAME` refs in `env`/`headers`; never journaled. |
| Q19 | `native_tools` is the placeholder slot for chain tools (v1.1). |
| Q21 | `tools` MUST exhaustively enumerate what the server advertises; the manager rejects drift at boot. |
| Q22 | `package_digest` MUST be the sha256 of the published package. |

<Warning>
The placeholder digests in `default.json` are zero-filled (`sha256:0000…`) for bootstrap testing only. Before any production or chain-anchoring deployment, install the pinned package, compute its real sha256, and replace the placeholder.
</Warning>

<Card title="Verify a manifest" icon="terminal" href="/api-reference/cli">
  `mcl-tools verify` checks the declared/discovered tool bijection.
</Card>