---
title: "The hub MCP endpoint (JSON-RPC 2.0, one message per request)"
method: POST
path: "/agent/hub/mcp"
tags: ["mcp"]
---

# The hub MCP endpoint (JSON-RPC 2.0, one message per request)

`POST /agent/hub/mcp`

## Request

- Base URL: `https://api.bubblio.dev`
- URL: `https://api.bubblio.dev/agent/hub/mcp`
- Auth: none declared

Same envelope as every per-door endpoint (64KB body cap, notifications → 202,
protocol errors as JSON-RPC `error` on HTTP 200). Tool routing differs in exactly
two ways: a sixth tool `find { query }` searches the live directory, and the five
door tools take a `door` argument (handle or door id) resolved through the
UNCHANGED per-door machinery — custody, approvals, mandates, payments, and rate
buckets all scope to the resolved door, exactly as if the agent had knocked on the
door's own URL. The hub is routing, never a bypass, and holds no credential.

## Request body

- JsonRpcRequest
  - `jsonrpc` '2.0', required
  - `id` union: Omit entirely for a notification (answered 202, no body).
    - string
    - number
  - `method` 'initialize' | 'ping' | 'tools/list' | 'tools/call', required
  - `params` object: For tools/call: { name, arguments }.

## Response `200`

JSON-RPC result — or a JSON-RPC error object for malformed/unknown requests.

- JsonRpcResponse
  - `jsonrpc` '2.0', required
  - `id` union, required
    - string
    - number
  - `result` object: For tools/call: MCP content — `{ content: [{ type: 'text', text }], isError? }` where `text` is a JSON document (see QuoteAnswer / ConfirmAnswer / Receipt for the action tools). Tool FAILURES arrive here with `isError: true`, phrased for the calling model; JSON-RPC `error` is reserved for protocol problems.
  - `error` object
    - `code` integer
    - `message` string

## Other responses

- `202`: Notification (no `id`): acknowledged, no body.
- `413`: Body over 64KB (JSON-RPC error envelope).
- `429`: A published ceiling tripped (JSON-RPC error envelope, code -32000; HTTP 429 so generic clients back off too). `Retry-After` is advisory and clamped to 3600s; the MESSAGE carries the real limit to pace against.

---

[API](https://skmtc.dev/bubblio/apis/bubblio-agent-door-api.md) · [All operations](https://skmtc.dev/bubblio/apis/bubblio-agent-door-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bubblio/apis/bubblio-agent-door-api/revisions/d858aff9c01d?raw)