Agent Manifests

An agent manifest is a JSON file that describes what tools a Matrix agent has access to. The executor loads it at boot, spawns each declared MCP server, and verifies that the server's advertised tools match the manifest exactly. The canonical Go types live in executor/tool/manifest.go.

Manifest files

Schema

{
  "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"
        }
      ]
    }
  ],
  "native_tools": []
}

Field reference

The exhaustive-tools rule

The tools array in each server entry must list every tool the server advertises, no more, no less. At boot, the manager spawns the server, calls tools/list, and compares the result against the manifest. Any mismatch (a tool the server advertises but the manifest omits, or a tool the manifest declares but the server does not provide) causes a fatal boot error.

This bijection check prevents two failure modes:

• An agent calling a tool the manifest did not authorize.
• A stale manifest referencing tools that no longer exist on the server.

Side-effect classes

Every tool declares exactly one side_effect_class:

A tool call only executes if its class appears in the manifest's allowed_side_effects. An agent that only allows read and network will refuse any shell or write tool, even if the server provides it.

Locked design rules