Overview
Brain exposes a Model Context Protocol (MCP) server so agents can read financial state, retrieve memory, and propose actions within tenant-signed policy. Brain runs the underlying ingest, normalization, policy, and execution; the agent works against a single scoped surface.
Agents propose actions. Policies decide what runs. Humans stay in control where the policy says they should.
Endpoint
https://mcp.brain.fi (canonical; maps to POST /v1/agents/mcp)
Transport
JSON-RPC 2.0 over single-shot HTTP
Backed by
The same Ledger, Wiki, and PaymentIntent surface as the HTTP API
The MCP surface uses single-shot HTTP. One request, one response, one audit event. Streaming transports may follow once we see a use case that needs them.
Surface Map
The MCP surface is intentionally small. 16 tools, 7 resource templates, 5 canned prompts.
🛠️ 16 Tools
Five Ledger reads, two Wiki reads, one Raw contribute, three PaymentIntent (propose, cancel, list), three proposal tools (list, get, decide), one evidence resolve, one agent action propose.
📦 7 Resources
Resource templates addressable by brain:// URIs: ledger accounts/transactions/obligations/payment-intents, wiki pages, payments/action_types catalog, and per-action proofs.
💬 5 Prompts
Canned prompts for the most common agent loops: cash flow, bills, spending, invoices, subscriptions.
🪪 Authentication
JWT plus on-chain scope hash verification against BrainMCPAgentRegistry. Per-tenant rate limit on the route so one misbehaving agent cannot crowd out other tenants.
What an External Agent Can Do
Read Ledger
ledger.account.get, ledger.accounts.list, ledger.transactions.list, ledger.obligations.list, ledger.counterparties.list
ledger:read
Read Wiki
wiki.question, wiki.page.get
wiki:read
Contribute to Raw
raw.contribute
raw:write
Propose payment
payment_intent.propose
payment_intent:propose
Read proposals
proposals.list, proposals.get, evidence.resolve
execution:read
Decide a proposal
proposals.decide
payment_intent:approve or execution:read
Propose agent action
agent.action.propose
execution:propose
proposals.decide declares no tool scope of its own. It accepts either payment_intent:approve or execution:read at the call boundary, then enforces member approval authority downstream (user-principal actor resolution, active-member and approval-role checks, and the money-path approval gates).
There is no payment_intent.execute on the MCP surface. External agents may propose but never execute. Execution always goes through Brain's deterministic pre-execution gate (13 numbered checks + 4 hardening additions), behind human approval where policy demands it.
What Makes the MCP Surface Different
The MCP tools call the same Ledger, Wiki, and PaymentIntent code paths that back the HTTP API. That has three concrete consequences:
Identical Policy gating
A payment_intent.propose over MCP runs through the same Policy evaluator as one created via HTTP
Identical audit emission
Tools that mutate state emit the same inner audit events the HTTP API emits, plus an outer agent.mcp.tool_called event
No bypass path
There is no shortcut. MCP cannot skip Policy or write to the Ledger directly.
Architecture
A First Call
Response:
What's Next
Last updated
