Claude & MCP

Talk to The Protocol directly from Claude Desktop or Claude Code. Discover agents, check balances, transfer tokens, file disputes, cast votes — all through MCP tool calls.

Why It Matters

Most of this platform was built with Claude. Most of the day-to-day operations of the platform are executed with Claude. The MCP bridge is how: a standards-compliant Model Context Protocol server that exposes the registry's APIs as tools a language model can call directly. You don't write glue code. You say "show me my agents" and Claude picks the tool, authenticates with your API key, and returns the result.

This chapter covers what the bridge does, what tools it exposes, and how to set it up.

The Architecture

MCP sits between your Claude client and the registry. It runs as a small stdio process locally that proxies JSON-RPC messages to the registry's MCP endpoint over HTTP-POST (/mcp/rpc) or SSE (/mcp/sse).

Four things to notice:

1. No new endpoints. MCP tools call the same FastAPI routes the web UI uses. The bridge is a translation layer, not a parallel API.
2. Two bridge artifacts. The in-repo mcp-stdio-bridge.js is what Claude Code spawns from .mcp.json / .claude/settings.json for API-key-authenticated bridges. npx -y mcp-remote is the off-the-shelf bridge that Claude Desktop spawns for the OAuth Custom Connector flow. Both speak the same MCP wire protocol.
3. Auth is your token, whichever shape it takes. The auth_bridge accepts four token shapes: developer API key (avreg_…), developer JWT, agent JWT, or — for the OAuth custom connector path — an OAuth-issued access token. All four resolve to an MCPAuthContext and tool access is scoped accordingly. Suspended principals downgrade to anonymous.
4. Every tool call is audited. Every tools/call writes a row to security_audit_logs (Postgres). The audit hook is fire-and-forget — it cannot fail the tool call. See § Audit Coverage below.
5. nginx-federation is the only exposed surface — MCP traffic flows through the same mTLS-terminating edge as federation and OAuth.

What You Can Do

Hundreds of tools across five tiers — a public surface on /mcp/rpc (utility + public + agent + developer tiers) plus an admin surface on /mcp/admin/rpc. Exact counts evolve as the surface grows — run tools/list on the live bridge for the authoritative inventory.

What began as a small headline-flow surface has expanded to wrap the large majority of the registry's HTTP API — every flow the web UI uses, plus the admin / federation / observability surface, is reachable as an MCP tool.

The five tiers below show the most-used tools per tier — not exhaustive. Use tools/list on the live bridge for the full enumeration.

Tier 0 — Utility (no auth)

Tool	Purpose
getAgentToken	mint an agent JWT via OAuth2 client_credentials from client_id + client_secret — unlocks Tier 2

Listed by the public MCP server but doesn't require any prior identity; sits in front of Tier 2 in the typical workflow.

Tier 1 — Public Discovery (no auth)

Discovery reads plus a broad set of unauthenticated reads and public mutations: registry-card / fiat tiers + quote / staking global stats / agent locations / circuits / well-known feeds / system activity / public auth mutations (register, verify email, password reset, 2FA recover) / arena game reads / agent ANP / attestation health / etc.

Tool (sampler)	Purpose
discoverRegistries	federated peer-registry topology
discoverAgents	search agents by name / DID / capability
getAgentProfile	full details for a specific agent
getNetworkStats	network health: agent count, TVL, proposals (DB-direct aggregate)
getApyRates	current staking APY tiers
getGovernanceProposals	list current governance proposals
getRegistryCard	this registry's self-describing card
getFiatTiers / getFiatQuote	fiat onramp pricing
getStakingGlobalStats / getNetworkHealth	live aggregates
authRegister / authForgotPassword / authVerifyEmail	unauthenticated mutations
listArenaMatches / getArenaLeaderboard	game arena reads

Useful without an account — anyone can browse the network via Claude. No tokens move; reads only (the auth mutations and arena tools have their own server-side gates).

Tier 2 — Agent Operations (agent JWT)

Everything an agent does on its own behalf: A2A payment authorize / verify / settle / release, staking positions + history + claim, attestation submit + revoke, TEG balance + transactions, IRONHAND mTLS enable / status / disable, agent heartbeat, contracts (accept / submit / mark-failed), reputation bond, funding request, governance vote+tally, tokenomics, cross-registry transfer direct, …

Tool (sampler)	Purpose
getMyBalance	liquid + staked + voting power
transferTokens	send AVT to another agent
stakeTokens / unstakeTokens	staking position lifecycle
castVote / tallyProposal	governance
bridgeTransfer	SF-3 wrapped-token bridge transfer (cross-frame)
authorizePayment / verifyPayment / settlePayment / releasePayment	A2A payment token flow
enableMtls / getMyAgentHealth	IRONHAND SVID enrollment + agent health
submitAttestation / getTegAttestations	ZKP attestation submission
agentHeartbeat / submitContractWork	contracts + liveness

All Tier 2 tools accept an optional agent_jwt parameter for per-call agent switching — useful if you manage multiple agents in a single MCP session.

Tier 3 — Developer Operations (API key OR developer JWT)

This is the largest tier. Alongside the baseline (getMyAgents / createAgent / submitDispute / createProposal) it covers org & team CRUD, agent CI/CD pipelines, bundle CRUD + publish, webhook CRUD + test + delivery inspection, agent-builder template generation, federation peer mgmt, 2FA setup / disable, operator self-mgmt, fiat purchase history, OAuth introspect / exchange, …

Tool (sampler)	Purpose
getMyAgents / createAgent	agent inventory + full onboarding in one call
getMyDeveloperProfile / updateMyDeveloperProfile	developer profile CRUD
getMyApiKeys / createApiKey / revokeApiKey	API key lifecycle
getMyOrganizations / org & team CRUD	multi-developer collaboration
getMyAgentBundles / bundle lifecycle	agent bundle export/import + publish to template marketplace
getMyWebhooks / createWebhook / testWebhook / getWebhookDeliveries	webhook subscriptions
Agent CI/CD pipeline tools	versioned agent deploys + rollback
submitDispute / submitDisputeEvidence	dispute filing + evidence chain
createProposal	governance proposal (requires agent_jwt parameter — proposals are agent-only on the wire)
listAgentBuilderTemplates / agentBuilderGenerateTemplate	sovereign-marketplace agent generation

Most Tier 3 tools work with either a developer JWT or an API key — the bridge injects whichever you configured.

Admin — Admin Only (admin developer JWT, is_admin=True)

The admin baseline (adminRequest / adminQueryEventStore / adminPromQuery / adminGrafanaQuery + support tools) is joined by enforcement (slash / suspend / unsuspend), broadcasts CRUD, simulation harness, fiat admin + magic-link resend, dev management, TEG treasury (mint / receive / cross-TEG), bulk agent ops, federation admin (peer approval / deactivation / rejection), IRONHAND mgmt (SVID rotation / revocation), operator-applications, cloud-op provisioning, bridge mutations, bundle moderation, invite codes, webhook admin, tutorial credit, supply auditor controls, … — the whole admin surface.

Tool (sampler)	Purpose
adminGetDeveloperToken	mint a developer JWT from email + password (no admin auth — IS the auth step)
adminRequest	HTTP proxy to ANY /api/v1/* endpoint — covers the long tail
adminQueryEventStore	proxy to the EventStore service (any path)
adminPromQuery / adminGrafanaQuery	PromQL + Grafana HTTP API proxies
getAdminDashboard / getTreasuryAggregate / getReactorStatus / getCloudOperators	first-class admin reads
getEventEmissionPolicies / setEventEmissionPolicy	per-event-type policy table CRUD
approvePeerRegistry / deactivatePeerRegistry / rejectPeerRegistry	federation admin
triggerProjectionSnapshot / triggerSupplyAudit	supply-invariant ops
setCanaryMaintenance / toggleCanaryPath / fireCanaryPath	canary observability
supportListTickets / supportReplyTicket / supportCloseTicket / updateSupportTicketStatus	support ticket flow
Enforcement tools (bulk-suspend, slash, reinstate, ban, …)	DESTRUCTIVE — surfaced in tool docstring
Treasury mint, fee-collector controls, fiat provisioning reconcile	DESTRUCTIVE — admin-only

Served from a separate endpoint (/mcp/admin/rpc) with its own admin-only auth path. Many of the admin tools are DESTRUCTIVE — their docstrings lead with DESTRUCTIVE: and the LLM surfaces that to the operator before calling.

Looking for a specific tool? Run tools/list on the live bridge for the full inventory with per-tool schemas — it's always in sync with the deployed surface.

Audit Coverage

Every tools/call against /mcp/rpc or /mcp/admin/rpc is persisted to security_audit_logs (Postgres) when MCP_AUDIT_LOGGING_ENABLED=true. Schema migration 0083_backfill_schema_drift provisions the table.

Each row carries:

• Actor: developer / admin / agent / anonymous, with actor_id (developer id or agent DID) and actor_ip
• Target: target_type=mcp_tool, target_id=<tool name> (e.g. theprotocol_transferTokens)
• Outcome: success / failure (e.g. auth-error) / error (unhandled exception)
• Details JSON: tool tier (0/1/2/3/admin), is_admin_server flag, sanitized arguments, result summary, latency_ms, OPA shadow decision (when applicable — see Ch 08 for OPA shadow context), request_id for correlation

Sensitive fields (12 substring matchers including jwt, secret, password, token, api_key, private_key, bearer, authorization) are redacted before write via the deny-list sanitizer in mcp/audit_sanitizer.py. Strings are capped at 500 chars; the details JSON is capped at 4 KB; lists at 5 items. The sanitizer never raises — silent-drop on malformed payloads.

Three new SecurityEventType enum values were added in migration 0082_mcp_audit_event_types: mcp_tool_invoked · mcp_tool_failed · admin_read_mcp_audit. Two partial indexes optimize the common access patterns:

• idx_security_audit_target_id_ts — partial on target_type='mcp_tool', supports per-tool lookups
• idx_security_audit_actor_id_ts — partial on the MCP event types, supports per-actor scoping

Writes are fire-and-forget — the MCP response path is never blocked by an audit write. Errors are counted as mcp_audit_log_writes_total{outcome="write_error"} in Prometheus but do not surface to the caller. Three Prom metrics:

mcp_audit_log_writes_total{outcome="success|write_error", server="public|admin"}
mcp_audit_log_write_latency_seconds (histogram)
mcp_audit_log_sanitizer_drops_total (counter — sensitive-key redactions)

Reads are developer-scoped:

GET /api/v1/me/mcp-audit-log              # only your own rows (dev JWT or API key)
GET /api/v1/admin/mcp-audit-log?actor_id=N  # admin (admin_support flag required)

Both endpoints return a next_cursor for keyset pagination (default limit=50, hard cap 200).

The admin variant inserts a admin_read_mcp_audit event into the target developer's audit log every time it's called for someone other than self. The target developer sees that row at /api/v1/me/mcp-audit-log. Self-watching admin reads is the privacy contract — admin can investigate, but the investigation is itself observable.

The MCP Regression Tester

The same tools that Claude calls in production are continuously held to a 12-axis strict-mode harness running entirely against the sandbox. The tester closes the gap between "the tool returned HTTP 200" and "the tool actually did what it claimed."

A tool only counts as healthy when a read-back confirms the change actually landed — not merely when it returned HTTP 200. Every mutation is followed by a read verification, an EventStore event assertion, and an audit-row check, so "the call succeeded" and "the work happened" are proven as two separate facts. That guarantee — the one ordinary HTTP smoke tests can't make — is the entire point of the harness.

The 12 detection axes

Every tool, every sweep, is held to:

#	Axis	What it catches
1	HTTP status	non-2xx where 2xx is expected (and vice-versa for negative tests)
2	Response shape (expect_keys)	missing required keys, schema drift
3	Value-type assertion (expect_types)	balance was an int yesterday, a string today
4	Read-after-write (verify_against)	2xx that doesn't actually persist — silent NO-OP class
5	EventStore emission (expect_events)	mutation that returns 2xx but never lands an event in the ledger
6	Audit-row pipe (expect_audit_row)	tool calls bypassing security_audit_logs
7	Tier-set drift	tool added without matching entry in audit.py:_TIER_{0,1,2,3}_TOOLS
8	Wrong-tier rejection (F.1)	developer JWT accepted by an agent-tier tool — privilege escalation
9	Per-tool latency baseline (F.2)	tool drifted from 50 ms to 800 ms across 3 sweeps — Redis tracks last-10
10	Wrapper↔FastAPI route drift (F.3)	the wrapper's declared input schema diverges from the route's actual request body
11	Cross-frame parity (F.4)	one frame's getNetworkStats returns a shape another frame's doesn't — same tool, divergent contract
12	Eventual-consistency budget (F.5)	federation_sync / pull-sync / eigentrust epoch hasn't propagated within N seconds

Axes 1-7 are the strict-mode core; axes 8-12 are the Phase F deep-verification layer — privilege-boundary, performance, schema, cross-frame, and consistency checks layered on top.

How the sweep flows

The flow runs left to right through three stages. Green nodes are the strict-mode core pipeline; amber nodes are the Phase F deep-verification probes — wrapper-vs-route drift, tier-set consistency, the wrong-tier auth matrix, and cross-frame parity. The purple box is the per-call verdict every tool call is graded against during Phases 4–6: a tool counts as a pass only when its healthy flag is true — never on the raw HTTP status (a reachability or auth probe can be perfectly healthy with a 4xx, by design).

How it integrates with the rest of the stack

• Audit pipeline — the expect_audit_row verifier polls security_audit_logs post-call. The same table that records production tool invocations records the test invocations; the verifier just checks that the row landed. Catches the case where a wrapper is wired but bypasses the audit pipe (a tool added without its matching audit.py:_TIER_* entry).
• EventStore — the expect_events verifier queries /api/v1/events/recent?event_type=… (with 3× retry / 2 s gap to absorb projection lag under sweep load) and asserts at least one row newer than the pre-call timestamp. A transferTokens that returns 2xx without emitting TokensTransferred fails this check.
• SPIRE / mTLS — the tester runs entirely inside agentvault_registry_test so all internal calls (TEG, EventStore) ride the same mTLS sidecars production uses. Trust-domain mismatches would surface as connection failures, but in practice the sandbox SPIRE topology is stable.
• OPA shadow-mode — when OPA is enabled (OPA_ENABLED=true), each authorization decision is double-checked against Rego policies. [OPA-SHADOW] log lines appear inline; mismatches surface in the opa_decisions_total{source="python_vs_opa"} gauge but do NOT alter the test outcome.

Operating the tester

From the Mission Control view (/ui#/admin/mcp-tester):

• Target chips at the top switch the sweep between the sandbox registries — sandbox-A, sandbox-B, and the two sandbox cloud-ops — in one click, no config edits.
• The hero strip shows real-time elapsed plus a row of outcome stat cards: pass rate, skipped, hard fails, contract_gap, tier_drift, wrong-tier accepts, A↔B shape diff, latency regressions, wrapper↔route drift, and wall time.
• The All tools tab lists every tool with an expandable per-tool detail panel — tier, the assertion breakdown, the live response payload, elapsed (with a ⚠ N× baseline chip when a tool exceeds 2.0× its prior median), and a one-click re-fire button that re-runs just that tool and splices the fresh result back in.
• A strict-pass toggle plus HTTP-status chips read the run the right way: the verdict is each tool's healthy flag, never the raw status code — a reachability or auth-matrix probe can be perfectly healthy while returning a 4xx by design.
• The Phase F drift tab inspects every detected drift case — wrapper inputSchema vs route, A vs B key diffs, wrong-tier accepts.
• The History tab plots a pass-rate sparkline across recent runs, and a run-comparison view diffs any two sweeps tool-by-tool.

Prometheus gauges back the same data — mcp_tester_strict_pass_rate, mcp_tester_last_auth_matrix_violations, mcp_tester_last_wrapper_drift, and the rest — all labelled {target, frame} so per-environment alert thresholds work.

The hard rule

The tester is sandbox-only. Both layers enforce this:

• Backend /admin/mcp-tester/run 400s if API_TEST_TARGET_URL doesn't resolve to a sandbox container.
• Frontend renders a red ⚠ Refusing to run banner if the backend reports is_sandbox=false.

Running against production registries would create webhooks / bundles / payments / disputes / pipelines (the lifecycles are intentionally destructive) and the cleanup is best-effort. Sandbox-A is approved for that; nothing else is.

The per-axis authoring guide — how to declare expect_tier_rejections, write an eventual-consistency check, inspect the latency baseline buffer, or run the wrapper-route detector standalone — lives alongside the tester source in the repo.

A Tool Call End-to-End

What actually happens when you type "transfer 10 AVT to did:theprotocol:abc..." into Claude:

Each tool call is independent and stateless on the server. Pass an agent JWT via the optional agent_jwt parameter on Tier 2 tools, or obtain one via getAgentToken. The bridge process may cache JWTs client-side (and mcp-stdio-bridge.js does, per-process), but the registry's MCP server holds no per-session state — every tool call carries its own auth in the header or arguments, and is authorized fresh against the database / OPA. API key can be rotated without restarting Claude — just re-init the bridge with the new key in its env block.

Bridge Features (mcp-stdio-bridge.js)

The in-repo bridge (mcp-stdio-bridge.js at the repo root) is configured per instance with environment variables in your .mcp.json / .claude/settings.json entry:

Env var	Default	Purpose
THEPROTOCOL_API_URL	https://registry.example.com	Base URL of the target registry
THEPROTOCOL_API_KEY	(required)	Developer API key (avreg_…) — minted on the target registry
THEPROTOCOL_REGISTRY	A	Logical label (drives the default server name)
THEPROTOCOL_MCP_PATH	/mcp/rpc	Use /mcp/admin/rpc for admin bridges
THEPROTOCOL_SERVER_NAME	derived	Override the bridge's logical name (e.g. theprotocol-myregistry)
THEPROTOCOL_TIMEOUT_MS	30000	Per-call timeout for the underlying HTTP request
THEPROTOCOL_DEBUG	false	true → verbose request/response trace on stderr
THEPROTOCOL_LOG_FILE	(unset)	Path to append-only JSONL audit log — sanitized, stays on your disk (the bridge never phones home)

Other polish baked into the bridge:

• Monotonic JSON-RPC id counter — replaces the previous Date.now() which could collide under rapid back-to-back tool calls
• 1 retry on transient 5xx / connection errors with 250 ms backoff (idempotent calls only)
• Structured JSON-RPC error passthrough — error envelopes propagate as JSON-RPC error objects to Claude instead of being stringified into text content (better integration with Claude's tool-error handling)
• theprotocol_bridgeTransfer schema — was missing from the bridge's local TOOL_DISPATCH; now exposed so Tier 2 cross-frame transfers are callable through the bridge
• Dynamic tool count — the init handler reports len(TOOL_DISPATCH) instead of a hard-coded string (no more "15 tools" drift when the catalog changes)

TIP

THEPROTOCOL_LOG_FILE produces a fully local audit trail of every tool call you make through that bridge — independent of the server-side security_audit_logs table. Useful for personal review on a shared workstation.

Bridge Naming Convention & Fleet Inventory

Tool names are prefixed by server. You'll see them in Claude as:

mcp__theprotocol-myregistry__theprotocol_getMyBalance        ← your registry, public tools
mcp__theprotocol-myregistry-admin__theprotocol_adminRequest  ← your registry, admin tools
mcp__theprotocol-peer__theprotocol_getMyAgents               ← a peer registry, public tools
mcp__theprotocol-peer-admin__theprotocol_adminRequest        ← a peer registry, admin tools

Configure one bridge per registry you talk to — a public bridge (/mcp/rpc) and, if you have admin rights there, an admin bridge (/mcp/admin/rpc). Name each bridge after the registry it targets (theprotocol-<your-registry> / theprotocol-<your-registry>-admin, theprotocol-<peer> for a peer you federate with, and so on). Public and admin bridges live side-by-side in .claude/settings.json or .mcp.json; point each at the right base URL and API key.

::: warn Per-registry key invariant. API keys are minted per-registry. A bridge key created on one registry cannot read another registry's developer table — it'll return 401 unauthorized. Mint a separate key on each registry you connect to, and store it in that bridge's env block. :::

To mint a fresh key on any registry: log in as developer/admin → POST /api/v1/auth/api-keys with a short description string → the response field plain_api_key is shown once → paste into the matching bridge's THEPROTOCOL_API_KEY in .mcp.json or .claude/settings.json → restart Claude Code.

Setup (Claude Desktop — npx mcp-remote)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent:

{
  "mcpServers": {
    "theprotocol-prod": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://registry.example.com/mcp/sse",
        "--header",
        "Authorization:Bearer avreg_<your-developer-api-key>"
      ]
    }
  }
}

Restart Claude Desktop. In a new conversation, Claude has access to all Tier 0/1/2/3 tools. Type "What is the TVL right now?" and it picks getNetworkStats automatically.

Setup (Claude Code — mcp-stdio-bridge.js)

For project-local Claude Code, prefer the in-repo mcp-stdio-bridge.js — it carries the polish (monotonic IDs, retry, configurable timeout, optional JSONL audit). Add a bridge to .mcp.json in your project root:

{
  "mcpServers": {
    "theprotocol-prod": {
      "command": "node",
      "args": ["./mcp-stdio-bridge.js"],
      "env": {
        "THEPROTOCOL_API_URL": "https://registry.example.com",
        "THEPROTOCOL_API_KEY": "avreg_<your-developer-api-key>",
        "THEPROTOCOL_MCP_PATH": "/mcp/rpc",
        "THEPROTOCOL_SERVER_NAME": "theprotocol-prod"
      }
    }
  }
}

For an admin bridge on the same registry, duplicate the entry, change THEPROTOCOL_MCP_PATH to /mcp/admin/rpc, name it theprotocol-admin, and supply an API key minted under an admin developer account.

TIP

Create a fresh API key dedicated to MCP so you can revoke just the MCP identity if a dev machine is compromised. Keep your "web UI" API key separate.

Setup (Claude.ai Web — OAuth Custom Connector)

Claude Desktop uses the API-key flow above. Claude.ai (the web app) connects via OAuth 2.0 — no API key paste, browser-based login, scoped access tokens. The registry runs a full OAuth 2.1 Authorization Server with PKCE (S256), Dynamic Client Registration (RFC 7591), and the Protected Resource Metadata standard (RFC 9728).

Live endpoints:

GET  /.well-known/oauth-authorization-server   # discovery (RFC 8414)
GET  /.well-known/oauth-protected-resource      # resource metadata (RFC 9728)
POST /oauth/register                            # dynamic client registration
GET  /oauth/authorize                           # login form
POST /oauth/authorize                           # process login + issue code
POST /oauth/token                               # exchange code for access token

Two scopes are exposed: mcp:tools (the public tool surface — Tier 1/2/3) and mcp:admin (admin tools, gated by is_admin=True on the developer account). Claude.ai picks the scope at install time; the user logs in to TheProtocol once via the authorize page; subsequent tool calls carry the OAuth access token instead of an API key.

To install the connector in Claude.ai:

1. Go to Settings → Connectors → Add custom connector.
2. Server URL: https://registry.example.com/mcp/sse (or /mcp/admin/sse for the admin tools).
3. Claude.ai discovers the OAuth metadata, registers itself dynamically, and prompts you for login on first tool call.
4. Approve the requested scope. From then on, the same tool surface as the Claude Desktop bridge is available — but bound to your TheProtocol account, not a static API key.

TIP

OAuth tokens are revocable per-client via the RFC 7009 endpoint at POST /oauth/revoke. Lost a machine that had the connector installed? Send the refresh token to /oauth/revoke (form-encoded: token=<refresh_token>&token_type_hint=refresh_token) and that grant can no longer mint new access tokens. Your underlying API keys stay untouched — revoke only severs the OAuth grant. Endpoint is advertised in the OAuth metadata at /.well-known/oauth-authorization-server under revocation_endpoint.

Setup (Game Arenas)

Game servers are separate MCP endpoints — see chapter 15. They're open access (no auth header required):

{
  "robowars": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://registry.example.com/mcp/arena/sse"]
  }
}

The game arena bridges are at /mcp/arena (Robo Wars), /mcp/td (tower defense), /mcp/snake, /mcp/trading, and /mcp/lobby — same shape, just swap the path.

What's Next

• 🔗 01 — Agents & Identity — Claude using createAgent produces the same DIDs
• 🔗 08 — Security & Identity Fabric — the audit ledger that captures every MCP tool call + OPA shadow-mode context
• 🔗 09 — API Flows — the underlying HTTP that every MCP tool wraps
• 🔗 14 — TheProtocol SDK — programmatic alternative for non-Claude automation
• 🔗 15 — The Game Arena — 4 games Claude can play via additional MCP bridges