Operator Guide: AI Assistants & MCP

Audience: Federated and standalone registry operators Prerequisite: A running registry and an API key (see API Reference, Flow 4) Last Updated: 2026-08-02

---

1. Your Registry Speaks MCP Natively

Every TheProtocol registry ships its own Model Context Protocol server. There is nothing to install on the registry side: the endpoints below are part of the same image that serves your API, and an assistant connected to them can discover agents, move funds, manage staking, drive governance and (with an administrator's key) operate the registry itself.

This matters more here than on most platforms: the operator of a handed-over registry is often advised by an assistant, and several endpoints on your node exist specifically so that an assistant can orient itself without guessing.

Surface	Endpoint	Auth
MCP JSON-RPC (public tiers)	POST /mcp/rpc	API key (Bearer avreg_...)
MCP SSE transport	GET /mcp/sse	API key
MCP admin surface	POST /mcp/admin/rpc	an administrator's API key
Operator manual for assistants	GET /api/v1/downloads/CLAUDE.md	none (public)
Claude Code / Desktop stdio bridge	GET /api/v1/downloads/mcp-stdio-bridge.js	none (public)
Admin stdio bridge	GET /api/v1/downloads/mcp-stdio-bridge-admin.js	none (public)

The five-second orientation

curl <your-registry-url>/api/v1/downloads/CLAUDE.md returns a manual generated for your deployment: your URL, your registry's name and role, your unit of account and minting capability are already filled in. Paste it into any assistant (or point Claude Code at it) and the assistant knows how to log in, create agents and move funds on this registry without guessing a single value.

---

2. Mint the Key

MCP authenticates with a developer API key, minted once and shown once:

curl -X POST <your-registry-url>/api/v1/auth/api-keys \
  -H "Authorization: Bearer <developer-jwt>" \
  -H "Content-Type: application/json" \
  -d '"assistant bridge key"'

The response's plain_api_key (avreg_...) is the credential. Keys default to full scopes and a 365-day expiry; the request body also accepts {"key_name": ..., "scopes": [...], "expires_in_days": ...} when you want to narrow either. An ordinary developer's key reaches the public tiers; a key minted by an administrator account also opens /mcp/admin/rpc.

---

3. Connect Claude Code or Claude Desktop

Download the bridge from your own registry, then register it in .mcp.json:

curl -sO <your-registry-url>/api/v1/downloads/mcp-stdio-bridge.js

{
  "mcpServers": {
    "my-registry": {
      "command": "node",
      "args": ["/path/to/mcp-stdio-bridge.js"],
      "env": {
        "THEPROTOCOL_API_URL": "<your-registry-url>",
        "THEPROTOCOL_API_KEY": "avreg_..."
      }
    }
  }
}

The same file works for the admin surface: download mcp-stdio-bridge-admin.js instead (or set THEPROTOCOL_MCP_PATH=/mcp/admin/rpc) and supply an administrator's key. The bridge code is public on purpose -- it contains no secrets; authority comes entirely from the key you configure.

Restart the client after editing .mcp.json; the registry's tools appear under the server name you chose.

---

4. Keeping the Tool Catalog Small

The full catalog is large (hundreds of tools) and grows. Clients with limited context can ask the server for less:

• POST /mcp/rpc?mode=gateway (or header X-MCP-Mode: gateway) lists only a compact core plus listToolsets / searchTools / describeTools / invokeTool -- the assistant discovers and invokes everything else on demand.
• ?toolsets=wallet,discovery (or X-MCP-Toolsets) lists only the named buckets; enableToolset persists a per-credential selection for 24 hours.
• No parameter = the full catalog, unchanged.

Beyond tools, the server also publishes MCP resources (your signed registry card, JWKS, OpenAPI, live network stats) and prompts (guided flows for onboarding, funding, transfers). resources/list and prompts/list enumerate them.

---

5. What the Assistant Can and Cannot Do

Tools follow the same four auth tiers as the REST API: T1 public reads work with the key alone, T2 tools want an agent JWT (the getAgentToken tool mints one from client_id + client_secret), T3 tools act as the developer who owns the key, and the admin surface requires an administrator. An assistant holding your key can do what you can do -- treat the key like a password, scope it if you do not need everything, and revoke it from Settings when in doubt.

Two properties worth knowing as an operator:

• Tool calls can be audited. With MCP_AUDIT_LOGGING_ENABLED=true in your env file, every tools/call writes a security-audit row on your registry, making an assistant-driven action as traceable as a human one. The flag ships off; turn it on before handing keys to automation you do not fully control.
• Tool behavior is annotated. Every tool carries read-only / destructive / idempotent annotations, so well-behaved clients know which calls are safe to retry.

Hand it the manual

Your registry serves a written operating manual for exactly this purpose:

GET {REGISTRY_URL}/api/v1/downloads/CLAUDE.md

It is rendered per request with your registry's own live facts substituted in, so an assistant reading it gets your URLs and your posture rather than a generic example. It covers the three identity tiers and how to stop confusing them, creating agents, moving funds (including the org treasury rails), what minting will and will not do on your node, the regulatory-authorization rail, and how to read the error shapes. Point an assistant at it before asking it to operate anything.

Authorization will refuse an assistant, and that is correct

If agent authorization is enforcing on your registry (chapter 08), an assistant acting as one of your agents is bound by that agent's roles, spend policy and capability caveats — a 403 from those gates is a right answer, not a broken tool.

Two habits save a lot of confused debugging:

• Read the refusal rather than guessing. GET /api/v1/agents/{did}/authz/denials names what was refused and why. It is the fastest path from "the assistant says it cannot transfer" to the actual missing permission.
• Do not switch enforcement off to unblock automation. If a capability token is being refused repeatedly because the wrong holder is presenting it, repeated attempts will revoke that token and everything derived from it — which is the breaker doing its job. Fix the authority, not the gate.

---

6. Host Operations From an Assistant

The in-registry MCP server covers the platform. For the host -- container status, logs, restarts, backups, SPIRE enrollment -- the tp CLI has its own MCP mode:

tp mcp serve     # stdio MCP server exposing the CLI verbs as tools
tp mcp tools     # list what it would expose

Wire it into .mcp.json exactly like the bridge above (command tp, args ["mcp", "serve"]) and an assistant can run day-2 operations end to end. See the Host CLI chapter for the verb surface.

::: warn One key, one registry API keys are per-registry: a key minted on one registry cannot read another's tables. If you operate several nodes, mint a key on each and give the assistant one bridge entry per node. :::