MCP — how models talk to the wallet

Frequently asked questions

What is MCP and why does AgentWallet use it?

MCP (Model Context Protocol) is Anthropic's open standard for typed, streaming tool calls between LLM agents and external services. AgentWallet exposes every wallet operation — spend, refund, payout, USDC transfer, mandate operation, inbox read — as MCP tools so any compatible LLM client (Claude Desktop, Cursor, Continue, LangChain, LlamaIndex, OpenAI Agents SDK, Vercel AI SDK, your own) can drive the wallet without bespoke integration. One URL per agent goes into the client's MCP config; the catalog auto-loads and is callable in under a second.

What tools does the AgentWallet MCP server expose?

Roughly fifteen typed JSON-RPC tools, scoped to one agent and authenticated by that agent's pak_… bearer key. Wallet: wallet.status (computed balance + holds + headroom), wallet.send_payment (fiat payout via available rail, limit-gated), wallet.send_usdc (USDC transfer on Base, limit-gated), wallet.x402_pay (sign EIP-3009 auth for an x402 endpoint), wallet.list_activity, wallet.request_approval. Card: card.details (last4 + balance, never PAN), card.recent_authorizations. Comms: comms.send_sms, comms.send_email, comms.list_inbox. Identity: identity.who_am_i (metadata + AP2 public key), identity.sign_mandate (ES256 sign an AP2 IntentMandate), identity.discover (resolve another agent via /.well-known). Approvals: approvals.poll for the over-threshold queue.

How does an agent authenticate to its MCP server?

Each agent has a single pak_… bearer key issued at provisioning and rotatable in one PATCH. The SHA-256 fingerprint is stored in agent_identities and constant-time compared on every JSON-RPC request. The bearer key scopes every tool call to that one row — multi-tenancy is enforced at the storage layer, so no MCP call can ever reach across agents or across the Company tier. Keys are revocable in one click and any in-flight session terminates inside the same request cycle.

Is the MCP endpoint streaming?

Yes for long operations — payouts that wait for ACH/SEPA settlement, x402 round-trips that wait for on-chain confirmation, USDC transfers that wait for Base inclusion all stream incremental status frames back to the LLM client (pending → submitted → settled or failed) instead of blocking the call for minutes. Short operations (balance reads, mandate signs, inbox lists) return synchronously. Streaming uses MCP's standard transport so any compliant client picks it up without extra configuration.

How do I wire the MCP endpoint into my agent runtime?

One line per client. Claude Desktop and Cursor: paste the URL plus pak_… key into ~/.config/mcp.json (or the per-app equivalent) and restart. LangChain / LlamaIndex / Vercel AI SDK / OpenAI Agents SDK: install the standard @modelcontextprotocol client adapter and pass the URL + key. Your own runtime: the endpoint advertises itself via the standard JSON-RPC tools/list method, so any MCP-compliant client can discover the catalog at runtime without a hand-written schema.

How is MCP different from a plain REST API?

Three things. (1) Typed tool catalog with schema discovery — clients introspect the tool list at runtime instead of hard-coding endpoints, which lets us add tools without breaking deployed agents. (2) Native streaming for long operations — the LLM sees incremental status frames without long-polling. (3) LLM-first ergonomics — tool descriptions, parameter docstrings and error messages are written for an LLM reader, not a human developer. Under the hood every MCP tool maps one-to-one to a REST endpoint, so the same operations are reachable via standard HTTP for non-LLM clients.