# Vaultfire MCP server

Endpoint: `https://theloopbreaker.com/api/mcp`, the exact URL advertised in
`/.well-known/agent.json` and `/api/health`.

The server is **read-only**. It lists, describes and checks Vaultfire's live
Base V2 x402 API surface. It never takes payment, signs, broadcasts, holds
keys, moves funds or calls a paid provider. Vaultfire V3 is source-review only:
its activation, payments and funds stay disabled, and this server exposes no
V3 execution.

## Transport

- Streamable HTTP, stateless. `POST` only. `GET` and `DELETE` return 405, and
  no SSE session or `Mcp-Session-Id` is issued.
- Protocol versions: `2026-07-28` (current, stateless `_meta` and
  `server/discover`). The legacy `initialize` handshake is accepted for
  `2025-11-25`, `2025-06-18` and `2025-03-26`. Any other version gets JSON-RPC
  error `-32022` along with the supported list.
- `2026-07-28` requests must send the `MCP-Protocol-Version` header, plus the
  `Mcp-Method` and `Mcp-Name` headers where the spec requires them. If a
  header disagrees with the body, the server returns `-32020`.
- `Content-Type: application/json` is required (otherwise 415). `Accept` must
  allow `application/json` (otherwise 406). Bodies are capped at 64 KiB (413),
  and JSON-RPC batches are rejected. Notifications return 202 with no body.
- A browser `Origin` outside the site allowlist gets 403. Server-side clients
  that send no `Origin` are allowed.
- Rate limit: 120 requests per minute per client IP, in its own bucket that is
  separate from the x402 API.

## Tools

| Tool | Purpose | Side effects |
| --- | --- | --- |
| `vaultfire_list_operations` | List V2 x402 operations: price, payment requirement, chains, success-schema availability, support scope. Filters: `pathPrefix`, `paymentRequired`, `limit`, `offset`. | None |
| `vaultfire_get_operation` | Full contract for one operation (`path`, optional `method`): input schema, example, success schema or the reason it is missing, payment/auth, errors. | None |
| `vaultfire_release_identity` | Source commit/tree this deployment was built from, endpoint counts, release-status document. | None |
| `vaultfire_service_health` | Runs the real free health handler. | None |
| `vaultfire_chainlink_status` | Runs the real free Chainlink status handler (public RPC reads). | Outbound public RPC reads |

76 operations are indexed: 74 paid and 2 free. All 76 publish a success
schema, but the evidence behind it differs: 44 schemas come from an observed
local response (43 unsigned Base transaction preparations and 1 static registry
read), while 32 are declared by the authoritative handler only and have no
captured live-provider response. `vaultfire_get_operation` returns that scope in
`successSchemaNote`, so treat a declared-only schema as a shape contract, not as
evidence that the provider currently fulfils the call. Operations under `/api/x402/actions/` return **unsigned**
transactions for your own wallet to review. Vaultfire never executes them.

## Golden path

1. Discover: `GET /.well-known/agent.json` and find the `mcp` record.
2. Inspect: `GET /api/health` and confirm `mcp.endpoint` and versions.
3. Connect with an official MCP client:

```js
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(new URL('https://theloopbreaker.com/api/mcp')));
const { tools } = await client.listTools();
const identity = await client.callTool({ name: 'vaultfire_release_identity', arguments: {} });
```

4. Safe operation: call `vaultfire_release_identity`, then check the returned
   commit against canonical Twigpine main.
5. Durable receipt: the MCP server is read-only and produces no receipts. To
   exercise durable receipts end to end, use the V3 partner sandbox
   (`full-v3/partner`, local only, synthetic settlement, no funds). It is
   described in the repository's onboarding guide.
6. Verify and retry: every tool is idempotent and read-only. Retrying the same
   call is safe. Back off on HTTP 429.

## Acceptance

Independent acceptance runs from a separate process
(`acceptance/mcp-client/`) with pinned official clients
`@modelcontextprotocol/sdk` 1.32.1 and `@modelcontextprotocol/client` 2.3.1.
It covers both version eras, header validation, origin rejection and every
tool. Result logs and hashes are in the repository under
`audit-evidence/oct21-2026-remediation/`. Local acceptance results do not
prove production availability. Check `/api/health` on the live deployment.