# MCP

**Status: Planned. No MCP server is live.**

The capabilities response and the agent manifest advertise a future `/mcp` location so clients can
discover the intended surface. That path is not served today. Do not configure an MCP client to
connect to it, and do not treat the advertised URL as a working endpoint.

## Why it is not live

An MCP server would expose purchasing tools to a model runtime. That requires a credential model
that works with MCP clients, a tool-level mandate, approval enforcement and a strict ban on
returning bearer secrets. Those controls are being designed together with the agent budget and
approval work. Shipping the endpoint before them would create a path around the controls.

## Intended tool surface

The target is a small, explicit tool set. Read-only tools come first.

| Tool | Purpose | Status |
| --- | --- | --- |
| `get_capabilities` | Read flags, limits and documentation URLs. | Planned |
| `search_catalog` | Find offers by destination, type and validity. | Planned |
| `create_quote` | Bind offers and quantities to a 15-minute quote. | Planned |
| `create_order` | Buy a quote or use one-call ordering with an expected total. | Planned |
| `get_order` | Read purchase and child order status. | Planned |
| `get_usage` | Read current limits, usage and wallet. | Planned |

The following are explicitly out of scope for the first MCP release:

- Redemption, LPA text or QR SVG. Bearer credentials must not enter model context.
- Wallet funding, card data, saved payment methods or Stripe calls.
- Agent creation, key issuance, key rotation, allowlist changes or scope changes.
- Any endpoint that reveals upstream identity, cost or internal order fields.

## Auth model

The HTTP API uses HMAC-SHA256 over a canonical request. An MCP client that cannot add custom
signing headers cannot call this API directly. The planned server is expected to sit behind a
server-side credential broker:

- The MCP client authenticates to the broker, not with the API secret in its config.
- The broker holds the API secret and signs each call.
- The broker enforces the agent mandate, budget and approval state.
- The broker strips LPA, QR, secrets and internal fields from tool output.

A static API secret pasted into an MCP client configuration is not acceptable. Do not build one.

## Safety rules for any MCP integration

1. Never place the API secret in an MCP config, prompt, tool description or model context.
2. Never expose a tool that returns LPA text or QR data.
3. Require an explicit human approval above the mandate, even if the tool surface allows ordering.
4. Reject an order when the expected total, currency or recipient is outside the mandate.
5. Reuse the same idempotency key for a retry of the same logical order.
6. Stop on `402`, `403 ip_not_allowed`, `409 price_changed` and `approval_required`.
7. Do not let a model raise budgets, create keys or change allowlists.
8. Log tool calls with request ids, not credentials or personal data.

## Use the HTTP API today

Until the MCP server ships, integrate the HTTP API directly:

- <a href="/docs/api.md">Raw API Markdown</a> for the complete reference.
- <a href="/docs/agent-prompt.md">Agent prompt</a> for a paste-ready system prompt.
- [Agent payment](/docs/agent-payment) for the buying flow.
- [Approval flow](/docs/approval-flow) for the human control.

## Discovery

The docs agent manifest records the MCP state as `not_available` and links to this page. It does
not publish a fake server URL. When a server is live, the manifest will carry a real `serverUrl`,
the transport, the auth model and the tool list.

## Related

- [Agent identities](/docs/agent-identities).
- [Agent payment](/docs/agent-payment).
- [Prompt](/docs/prompt).
- [llms.txt](/llms.txt) for a compact machine-readable index.