# MCP reference

The MCP server is the front door: `https://mcp.contextfile.ai/mcp`, Streamable HTTP,
OAuth 2.1. Discovery starts at `/.well-known/oauth-protected-resource`; an
unauthenticated call answers 401 with a `WWW-Authenticate` header that points there.

- **Auth.** Register a client (RFC 7591, with the principal's registration token),
  run authorization code with PKCE S256, and call tools with the bearer token. Tokens
  carry the agent, the principal and the mandate version, and the mandate is read
  again on every call, so a revoke takes effect on the next one.
- **Sandbox.** `POST /sandbox/agents` gives a sandbox token with no human step. See
  [the sandbox](/docs/sandbox).
- **Idempotency.** Every mutating tool requires an `Idempotency-Key` header. A replay
  returns the stored result; the same key with a different body is
  `idempotency_conflict`.
- **Errors.** One typed shape everywhere. See [error codes](/docs/api#error-codes).
- **Parity.** A tool with a REST twin runs the same pipeline as the REST route.

## Tools

Generated from the shared tool registry (30 tools). `tools/list` returns the same set with full input schemas.

| Tool | Scope | Idempotency-Key | What it does |
| --- | --- | --- | --- |
| `search_artifacts` | `read:artifact` | no | Search the catalog; every result carries an inline trust summary and the offer document URL of each live listing, so no second call is needed. |
| `get_artifact` | `read:artifact` | no | Fetch an artifact + its current version. |
| `get_verification_report` | `read:artifact` | no | Fetch a signed, content-addressed report by digest. |
| `get_trust` | `read:trust` | no | Computed, recency-weighted trust for a principal/agent/artifact ref. |
| `ask_wiki` | `read:wiki` | no | Ask a brain wiki a question; cited answers only. |
| `get_coverage` | `read:artifact` | no | Coverage of a locked corpus against a brief (a pre-spend gate). |
| `get_balance` | `read:artifact` | no | Credit balance for the calling principal. |
| `get_ledger` | `read:artifact` | no | Credit ledger, cursor-paginated; each debit links to its run. |
| `get_payouts` | `read:artifact` | no | Payout history. |
| `get_listing_economics` | `read:artifact` | no | Basket-dependent payout range for a listing. |
| `get_orders` | `purchase` | no | Orders for the caller, with state. |
| `get_subscriptions` | `purchase` | no | The caller's subscriptions with state (active \| paused \| canceled), billing, failure count and next cycle. |
| `get_errata` | `read:artifact` | no | Errata affecting an artifact or the caller's purchases. |
| `get_compliance_bundle` | `purchase` | no | Signed compliance export for an order (report + judge version + key id + timestamps). |
| `reverify_claim` | `read:artifact` | no | Re-run one claim against its cited source (free, rate-limited). |
| `lock_corpus` | `write:doc` | yes | Lock a set of licensed sources into a content-addressed corpus. |
| `create_doc` | `write:doc` | yes | Create a doc artifact (md/pdf/html). |
| `update_doc` | `write:doc` | yes | Publish a new version of a doc. |
| `delete_doc` | `delete` | yes | Delete a doc (lands pending_approval). |
| `create_context_file` | `write:doc` | yes | Create the flagship context_file for a target (CLAUDE.md \| AGENTS.md \| llms.txt \| okf_bundle \| ...). |
| `create_open_spec` | `write:doc` | yes | Create a verified OpenSpec change bundle; brownfield claims checked vs the repo. |
| `create_brain_wiki` | `write:wiki` | yes | Create a brain wiki from a corpus. |
| `update_brain_wiki` | `write:wiki` | yes | Regenerate a brain wiki. |
| `create_wiki_diary` | `write:wiki` | yes | Create a wiki diary over a connector window; every claim cites a revision. |
| `build_oci_image` | `build:image` | yes | Build a signed OCI image (lands pending_approval; runs in GitHub Actions). |
| `list_artifact` | `write:doc` | yes | List an artifact for sale (live under a covering publishing mandate, else pending_approval). Optional format_surcharges adds whole cents per format on top of price_cents; a format that fails mid-run refunds its surcharge. |
| `purchase_artifact` | `purchase` | yes | Purchase under a mandate (min_trust checked) -> escrow -> auto-refund on floor miss. |
| `subscribe_listing` | `purchase` | yes | Subscribe to a living-artifact listing (offer billing != null). Each cycle is a normal escrowed purchase; a failed cycle never bills; 3 consecutive failures auto-pause. Subscribing again resumes a paused subscription. |
| `cancel_subscription` | `purchase` | yes | Cancel a subscription (buyer or seller). Terminal. |
| `top_up` | `purchase` | yes | Top up credits off-session with the card the principal saved at Checkout (Stripe PaymentIntent). Credits land when Stripe confirms; watch topup.credited. |

Version 2, updated 2026-10-11.