Overview

RobotMoney exposes a Model Context Protocol (MCP) server so agents can read financial state, retrieve memory, and propose actions within tenant-signed policy. RobotMoney 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.

Property	Value
Endpoint	https://mcp.robotmoney.com (canonical; maps to POST /v1/agents/mcp)
Transport	JSON-RPC 2.0 over single-shot HTTP
Backed by	The same Ledger, Wiki, Authorization, 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. 21 tools, 1 concrete resource plus 6 resource templates, 5 canned prompts.

21 Tools

Five Ledger reads, two Wiki reads, two Raw tools, three PaymentIntent tools, four Authorization tools, three proposal tools, one evidence resolve, one agent action propose.

Tools

7 Resources

One concrete resource (brain://payments/action_types) readable via resources/read, plus six templated brain:// URIs (ledger accounts/transactions/obligations/payment-intents, wiki pages, per-action proofs) returned only from resources/templates/list, not resources/list.

Resources

5 Prompts

Canned prompts for the most common agent loops: cash flow, bills, spending, invoices, subscriptions.

Prompts

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.

MCP Authentication

What an External Agent Can Do

Capability	Tools	On-chain Scope
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
Request a decision	authorizations.create, authorizations.get	payment_intent:propose
Read proposals	proposals.list, proposals.get, evidence.resolve	execution:read
Review a proposal	proposals.decide, authorizations.approve, authorizations.reject	member authority
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 RobotMoney's deterministic pre-execution gate (13 numbered checks + 4 hardening additions), behind human approval where policy demands it.

→ The pre-execution gate

What Makes the MCP Surface Different

The MCP tools call the same Ledger, Wiki, Authorization, and PaymentIntent code paths that back the HTTP API. That has three concrete consequences:

Property	Effect
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

        ┌─────────────────────────────────┐
        │  External agent              │
        └────────────┬────────────────────┘
                     │  JSON-RPC 2.0 over HTTPS
                     │  Authorization: Bearer <jwt>
                     ▼
        ┌─────────────────────────────────┐
        │  RobotMoney edge                │
        │  Validates JWT, resolves        │
        │  principal (tenant + scopes)    │
        └────────────┬────────────────────┘
                     │
                     ▼
        ┌─────────────────────────────────┐
        │  MCP dispatcher                 │
        │  - Method routing               │
        │  - 3 pre-call checks:           │
        │    a) agent active              │
        │    b) JWT scope_hash matches    │
        │       on-chain hash             │
        │    c) JWT tenant == agent       │
        │       tenant                    │
        │  - Per-tool scope enforcement   │
        └────────────┬────────────────────┘
                     │
                     ▼
        ┌─────────────────────────────────┐
        │  Shared RobotMoney services:    │
        │  Ledger reads & writes          │
        │  Wiki Q&A and pages             │
        │  PaymentIntent proposal flow    │
        └─────────────────────────────────┘
                     │
                     ▼
            Audit events emitted at every step

A First Call

POST / HTTP/1.1
Host: mcp.robotmoney.com
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wiki.question",
    "arguments": {
      "question": "What's our top expense category this month?"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "**Q:** What's our top expense category this month?\n**A:** AWS at $61,404 across 3 environments.\n\nCited evidence:\n  - `tx_4127` (ledger_transaction): AWS Inc $61,404.00"
      }
    ],
    "structuredContent": {
      "answer": "AWS at $61,404 across 3 environments.",
      "evidence": [
        {
          "entityId": "tx_4127",
          "entityType": "ledger_transaction",
          "excerpt": "AWS Inc $61,404.00"
        }
      ],
      "model": "...",
      "usage": { "inputTokens": 812, "outputTokens": 46 }
    }
  }
}

What's Next

Tools

The 21 tools in detail.

Tools

Authentication

How JWT and on-chain scope verification work together.

MCP Authentication