> ## Documentation Index
> Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Drive the Checkfu API from the Claude Agent, Cursor, or any MCP client through one endpoint.

Checkfu serves the public API as a Model Context Protocol server at
`POST /v1/mcp` — a stateless Streamable HTTP endpoint speaking JSON-RPC 2.0.
It accepts both connection shapes the protocol defines: the legacy
`initialize`-handshake flow (`initialize`, `ping`, `tools/list`, `tools/call`)
and the `2026-07-28` stateless core (`server/discover`, `tools/list`,
`tools/call`), where every request carries its own context. Every tool is one
reviewed API operation; a `tools/call` is compiled into the equivalent REST
request and dispatched through the same router as every other client, so
authentication, Workspace binding, budgets, policy, and audit behave exactly as
documented in this reference. There is no second enforcement path to reason
about.

<Note>
  This endpoint is for driving the **Checkfu platform** from your coding agent
  or MCP client. It is distinct from the harness-facing MCP endpoint at
  `/v1/runtime/mcp/{connection_id}`, which serves a Run's connected tool catalog
  to the executing harness — see [Capabilities](/concepts/capabilities). You
  call the first; your agents' runtimes use the second.
</Note>

<Warning>
  The Checkfu CLI has no self-service public installation channel during private
  alpha. The commands below assume access through an explicitly authorized alpha
  arrangement. See [CLI access in private alpha](/getting-started/cli-access) for
  the source-checkout and HTTP alternatives.
</Warning>

## Connect a client

The CLI registers the server with your coding agent and keeps the bearer out
of the config file. Prefer a Principal credential: the written entry references
`CHECKFU_PRINCIPAL_ACCESS_CREDENTIAL`, and the server binds its Workspace and
Principal rather than trusting client-selected headers.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Claude Agent, narrow read-only Principal mode (writes .mcp.json)
checkfu connect --credential principal --api-url https://api.checkfu.com

# Cursor (.cursor/mcp.json), or print a snippet for any other client
checkfu connect --credential principal --client cursor
checkfu connect --credential principal --client generic
```

Export `CHECKFU_PRINCIPAL_ACCESS_CREDENTIAL` in the environment that starts the
client. Principal mode rejects Workspace selectors: the credential's retained
authority supplies it. API-key mode remains available as
`checkfu connect --credential api-key`; export a Workspace-bound `CHECKFU_API_KEY`.
The endpoint does not require Checkfu's dated `Checkfu-Version` REST
header — synthesized REST dispatches carry the latest version internally.

## Issue and manage a Principal credential

Use an existing Workspace identity-administration API key to issue the bearer
for one live Principal. The `secret` appears in exactly this response and is
never readable or replayed again:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.checkfu.com/v1/principals/prin_0123456789abcdef0123456789abcdef/access-credentials \
  -H "Authorization: Bearer $CHECKFU_API_KEY" \
  -H "Checkfu-Version: 2026-08-27" \
  -H "Idempotency-Key: principal-access-editor" \
  -H "Content-Type: application/json" \
  --data '{"audience":"api_mcp"}'
```

`audience` defaults to `api_mcp` for compatibility. It is immutable and keeps
this bearer out of the [A2A server](/reference/a2a); issue a separate `a2a`
credential when an external agent needs that protocol edge.

List credential metadata at `/v1/principals/{principal_id}/access-credentials`
or read one at `/v1/principal-access-credentials/{id}` without exposing its
secret. Rotate with `POST
/v1/principal-access-credentials/{id}/rotate`, or revoke with `POST
/v1/principal-access-credentials/{id}/revoke`; both take
`expected_generation_number` and a
fresh `Idempotency-Key`. Rotation invalidates the old bearer immediately and
returns the replacement once. Revocation is irreversible. Suspending or
deleting the Principal also denies the next request.

The Principal catalog is a closed read-only set: exact AgentDefinition,
MemoryStore, and SurfaceScope reads for which the Principal holds the matching
live PermissionAssignment and survives ActionPolicy evaluation. List, search, and direct calls use
that same set. Consequential operations and reads without an exact resource
mapping are absent, and guessing their tool names is denied.

<Warning>
  **The key you paste carries its full role.** Every `tools/call` re-authorizes
  against the same permissions as any other request with that key — the MCP
  endpoint grants nothing extra, and it narrows nothing either. An MCP client
  configured with a key can reach every operation that key can reach.

  Connect the narrowest Workspace-bound key that does the job, and never connect a root key. Treat the client's
  config file and environment as key custody, and
  [rotate](/reference/authentication) on any suspicion. Prefer the Principal
  credential above whenever its closed read-only catalog is sufficient. Use
  API-key mode only when the client genuinely needs broader control-plane
  operations.
</Warning>

## OAuth discovery

A stock MCP client that sends a request to `/v1/mcp` without a valid bearer
receives a `401` whose `WWW-Authenticate` header carries a
`resource_metadata_url`. Fetching that URL returns an
[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) protected-resource
metadata document naming this resource and pointing at Checkfu as its own
authorization server. The corresponding
[`.well-known/oauth-authorization-server`](https://datatracker.ietf.org/doc/html/rfc8414)
document is honest about the model: Checkfu does not implement a standard
OAuth authorization-code flow (D95 rejected a full authorization server; it
may layer on without changing authority), so `grant_types_supported` is empty
and `service_documentation` points here. A client that requires a standard
flow learns it is not available; a client that can use a bearer discovers
that it needs one and where to obtain it.

Because Checkfu is also an OAuth *client* when connecting to external MCP
servers, its custody adapter validates the [RFC 9207](https://datatracker.ietf.org/doc/html/rfc9207)
`iss` parameter in every authorization redirect whose server includes one,
refusing a mismatch before the authorization code is redeemed. Client
registration uses RFC 7591 dynamic registration (D215), deduplicated to one
client per integration; Client ID Metadata Documents will replace DCR on the
specification's own removal clock, not before summer 2027.

Checkfu speaks two MCP connection shapes on the same endpoint, and a stock
client may open with either.

The **legacy shape** (`2025-06-18` / `2025-11-25`) begins with a conforming
`initialize` request containing `protocolVersion`, `capabilities`, and
`clientInfo`, then sends `notifications/initialized`. A client requesting
either legacy version receives that version back, and an unsupported requested
version receives the baseline `2025-06-18`. After initialization, send the
negotiated version in `MCP-Protocol-Version` on every request.

The **`2026-07-28` stateless shape** has no handshake. Each request is
self-contained: it carries `io.modelcontextprotocol/protocolVersion`,
`io.modelcontextprotocol/clientCapabilities`, and optionally
`io.modelcontextprotocol/clientInfo` in request `_meta`, and sets the routable
`Mcp-Method` (and `Mcp-Name` for `tools/call`) headers plus
`MCP-Protocol-Version: 2026-07-28`, which must agree with `_meta`. Probe with
`server/discover` to learn the supported versions and capabilities; the result
of every request carries `resultType` (an absent field reads as `"complete"`,
so legacy clients are unaffected). `ping` and `initialize` are not served on
this shape; a `2026-07-28` client uses `server/discover` instead.

Checkfu supports MCP `2026-07-28`, `2025-11-25`, and `2025-06-18`. MCP
interprets an omitted `MCP-Protocol-Version` header as legacy `2025-03-26`;
Checkfu does not claim that batching-era protocol, so an omitted header or a
legacy version Checkfu does not serve is rejected with `-32600`. On the
stateless `2026-07-28` shape, a `_meta` version Checkfu does not serve answers
`UnsupportedProtocolVersionError` (`-32022`) listing the supported set, and a
`MCP-Protocol-Version` header that disagrees with `_meta` — or a `Mcp-Method` /
`Mcp-Name` header that disagrees with the body — answers
`HeaderMismatchError` (`-32020`).

Send each request as `application/json`. JSON-RPC requests and final responses
are each limited to 4 MiB, and a synthesized REST result may contribute at
most 1 MiB before MCP framing. The endpoint accepts no query parameter except
one optional `catalog`, whose value must be exactly `compact` or `full`.
Because this is a bearer-authenticated non-browser endpoint, requests carrying
an `Origin` header are rejected before authentication or body processing.

## The tool catalog

`tools/list` returns a curated compact catalog — the core Session journey
(create, drive, read the ledger, fork, diff), agents, runs, ActionApprovals, memory,
and usage — plus `checkfu_search_operations`, which searches every projected
operation by name or capability. Any operation search returns is callable as a
tool without being listed, so the compact default never limits what an agent
can do; it only keeps the advertised catalog small. `?catalog=full` lists
every projected operation instead.

Tool names are operationIds with the group separator flattened:
`sessions.createSession` becomes `sessions_createSession`. Arguments are
nested as `{ "path": { … }, "query": { … }, "body": { … } }` matching the
operation's documented parameters. Mutation tools whose REST operation accepts
an idempotency header require `idempotency_key` and refuse the call when it is
missing. Keys are 1–255 non-space printable ASCII characters; reuse the same key
on retries. Mutations without REST idempotency support do not advertise a key
and retain their documented compare-and-swap or idempotent-delete semantics. Tool
annotations carry `readOnlyHint` and `destructiveHint` from the same reviewed
registry that produces this reference.

Operations that accept or return credentials, single-use proofs, pairing
material, or capability URLs remain REST-only so those values never enter a
model transcript. Multipart uploads and tar imports or exports are also
REST-only because the generic MCP bridge carries JSON.

REST failures come back as tool results with `isError: true` and the complete
[wire error](/reference/errors) body, so an agent can read the reason and
self-correct — a `404` names the missing resource, a `400` names the invalid
field, a `429` names the exhausted budget.