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/agentsgives a sandbox token with no human step. See the sandbox. - Idempotency. Every mutating tool requires an
Idempotency-Keyheader. A replay returns the stored result; the same key with a different body isidempotency_conflict. - Errors. One typed shape everywhere. See 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.