# MCP Server (API Reference)

The MCP server is exposed at `POST /v1/agents/mcp`, JSON-RPC 2.0 over single-shot HTTP. This page is the API-style summary; for the full reference (tool list, resources, prompts, error codes, on-chain auth flow), see the dedicated MCP Server section.

### Endpoint

```
POST /v1/agents/mcp
Authorization: Bearer <jwt>
Content-Type: application/json
```

### Sandbox

```
POST /v1/agents/mcp        on api.brain.dev   → Base Sepolia
POST /v1/agents/mcp        on api.brain.fi    → Base mainnet
```

### Methods

Standard MCP JSON-RPC methods:

| Method                     | Purpose                                    |
| -------------------------- | ------------------------------------------ |
| `initialize`               | Capability negotiation                     |
| `tools/list`               | List tools the agent has scope for         |
| `tools/call`               | Invoke a tool                              |
| `resources/list`           | List concrete resources the agent can read |
| `resources/templates/list` | List the 5 URI templates Brain advertises  |
| `resources/read`           | Read a resource by URI                     |
| `prompts/list`             | List the 5 canned prompts                  |
| `prompts/get`              | Render a canned prompt with arguments      |

### The 10 tools

Five Ledger reads, two Wiki reads, one Raw contribute, one PaymentIntent propose, one agent action propose. **No `payment_intent.execute`.**

[**→ Tool reference**](/mcp-server/tools.md)

### The 5 resources

Resource templates addressable by `brain://` URIs:

```
brain://ledger/accounts/{account_id}
brain://ledger/transactions/{transaction_id}
brain://ledger/payment-intents/{payment_intent_id}
brain://wiki/{slug}
brain://raw/{raw_artifact_id}
```

[**→ Resources reference**](/mcp-server/resources.md)

### The 5 prompts

`cash_flow_summary`, `bills_due`, `spending_change`, `invoice_status`, `subscriptions`.

[**→ Prompts reference**](/mcp-server/prompts.md)

### Authentication

JWT plus on-chain `scope_hash` verification against `BrainMCPAgentRegistry`. Three pre-call checks run before any method dispatches; per-tool scope is checked at invocation.

[**→ Authentication reference**](/mcp-server/mcp-authentication.md)

### Error codes

| Code     | Meaning                                   |
| -------- | ----------------------------------------- |
| `-32001` | JWT invalid or expired                    |
| `-32002` | Agent record not active                   |
| `-32003` | `scope_hash` does not match on-chain hash |
| `-32004` | Per-call scope insufficient               |
| `-32005` | Tenant mismatch                           |
| `-32600` | Invalid request (standard JSON-RPC)       |
| `-32601` | Method not found                          |
| `-32602` | Invalid params                            |
| `-32603` | Internal error                            |

### A first call

```http
POST /v1/agents/mcp HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wiki.question",
    "arguments": {
      "tenant_id": "acme",
      "question": "What's our cash position right now?"
    }
  }
}
```

### What's next

<table data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🔌 MCP Overview</strong></td><td>The full architecture and surface map.</td><td><a href="/pages/TQ2qB7I3AZOpEbqR4fZT">/pages/TQ2qB7I3AZOpEbqR4fZT</a></td><td></td></tr><tr><td><strong>🛠️ Tools</strong></td><td>The 10 tools in detail.</td><td><a href="/pages/LEWpOYJSpmIuTr20aNe8">/pages/LEWpOYJSpmIuTr20aNe8</a></td><td></td></tr><tr><td><strong>🪪 Authentication</strong></td><td>JWT and on-chain scope verification.</td><td><a href="/pages/ZNnH2CuEVwz0dbBj8bG0">/pages/ZNnH2CuEVwz0dbBj8bG0</a></td><td></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.brain.fi/api-reference/mcp-server-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.