Skip to main content
Checkfu exposes the public API at POST /v1/mcp as a Streamable HTTP JSON-RPC endpoint. MCP is another interface over the same contract as HTTP, SDK, CLI, and UI. Every tools/call is compiled into the equivalent ordinary API request and dispatched through the same router, authentication, Workspace binding, ownership, policy, Budget, and audit checks. It is not a second resource writer or runtime authority.
This endpoint drives the Checkfu platform from an MCP client. It is distinct from the runtime-facing connected-tool endpoint used by an executing harness.
The Checkfu CLI has no self-service public installation channel during private alpha. CLI setup examples require a source checkout or an explicitly authorized alpha artifact. Read CLI access first.
Plain HTTP against the Checkfu API needs no private package. The Checkfu CLI and TypeScript SDK are optional private-alpha artifacts; the HTTP requests work without them. Part of this flow is behind a rollout fence; a deployment that has not enabled it refuses the request rather than running it. Confirm capability status before making availability part of your application’s contract.

​
Connect a client

For Principal mode, first issue a credential for an existing Principal using an identity-admin API key. The api_mcp audience exposes selected Principal-authorizable reads, managedTools_invokeManagedTool, sessions_createSession, and sessions_driveSession. A fresh Managed Tool invocation requires the Principal’s current use_tool and allow_spend permissions and any required approval. Check capability status for serving availability; discovery alone does not make a Managed Tool executable. Connected-account setup and mutations outside this named catalog remain unavailable to this credential. Principal Session creation and input use the native serving path and the same authenticated Principal as requester and acting identity. They require current Session and resource authority; possessing the credential is not sufficient. sessions_driveSession accepts plain-text user.message input in this path. Structured input and other Session control events remain unavailable to a Principal credential. Keep the same idempotency key and body for an exact retry. A retry does not restore revoked authority: result delivery rechecks the current viewer, while retaining an already accepted input or effect. Confirm the selected Agent and deployment are supported through capability status before calling. The secret appears only in the issue response; keep it in the environment that starts your MCP client. Set CHECKFU_PRINCIPAL_ID and CHECKFU_API_KEY before running this command:
Then export the one-time secret from the response:
Keep that idempotency key unchanged when retrying the same issuance. Rotate or revoke the credential through the Principal access credential API if its custody changes. An a2a-audience credential cannot call /v1/mcp. The registered checkfu connect command can write a client configuration while keeping the bearer in the environment:
Principal credentials expose the closed catalog authorized for that Principal. API-key mode remains available when the client genuinely needs broader Workspace control-plane operations:
The credential supplies Workspace authority. The MCP client does not select another Workspace or Principal in tool arguments. Treat the client configuration and environment as credential custody. Do not put a bearer into a prompt, repository, Agent source package, or model-visible tool argument.

​
Discover before calling

The compact catalog returned by tools/list contains a curated set of operations plus the platform discovery tool:
Call it with exactly one argument:
The query must be a non-empty string. Search covers every operation projected from the reviewed public OpenAPI document, not only tools in the compact list. A returned operation is callable by the exact returned tool name and input schema. Use ?catalog=full only when a client needs the complete projected catalog up front. The compact catalog is preferred for model context size.

​
Tool names and arguments

Projected operation names flatten the operation ID separator. For example, an operation ID such as sessions.createSession is exposed as sessions_createSession. Operation arguments preserve the public request structure:
Only include members advertised by that tool’s returned schema. Mutation tools require idempotency_key only when the underlying API operation supports and requires it. Do not infer neighboring tools. A generated SDK method, a reserved Effect Schema, or a similar REST path does not prove that an MCP tool is served.

​
Authoring through MCP

MCP invokes the same canonical Agent operations as HTTP. It does not reserve a resource or become an authoring owner. Authentication, authorization, concurrency, and resource-specific policy apply to every request. Internal source ownership does not expose a public proposal or transfer tool. Resolve the returned typed error through the supported resource workflow; do not retry through another interface to bypass it. See Authoring authority.

​
Agent source validation tool

agentBlueprints_validateSource validates Agent configuration source without storing anything. Checkfu has no Blueprint installation tools. Create Agents and their dependent resources with the ordinary operation tools. Always use the exact schema returned by discovery, especially for mutations and idempotency.

​
AutomationGraph tools

The current model-callable AutomationGraph operation tools are:
automationGraphs_submitAutomationGraphWebhookSecret is deliberately not a model-callable MCP tool. Its generated SDK method exists as applications.submitWebhookSecret, but the operation is human-completion only because it accepts a write-only secret. An authorized API-key caller may use checkfu_request_human_completion with the exact operation ID and then observe the Application through automationGraphs_getAutomationGraphApplication.

​
Agent authoring

Author Agents through the canonical Agent tools returned by MCP discovery. Authenticated authorization and concurrency controls apply; repository CI owns merge policy. Discover the currently served tools before composing an authoring workflow. Internal ownership enforcement and activation remain implementation details, not customer MCP resources or tools.

​
Human-completion handoff

API-key callers may see this platform tool:
Its input is { "operation_id": "<exact operation id>" }, using a value returned by operation search. It hands a sensitive operation to the signed-in person without executing it or placing credentials, consent URLs, pairing codes, or capability bytes in model context. A handoff does not grant additional authorization or bypass canonical resource policy. The human still completes the governed operation through the protected surface.

​
Session tasks are projections

The MCP Tasks extension projects an existing Session as an asynchronous handle. tasks/get reads that Session and tasks/cancel uses the existing interruption path. No new task runtime, transcript, scheduler, or recovery authority is created. Session remains execution truth.

​
Security and authority

Operations that would put credentials, single-use proofs, pairing material, capability URLs, multipart uploads, or binary archives into generic model context remain excluded from the projection. Every call re-authorizes the credential. MCP grants nothing extra and does not narrow an API key by itself. Use the narrowest credential that can perform the intended operation. A source compiler called through MCP still cannot execute Runs, fire Automations, settle ActionApprovals, broker credentials, own Usage, or replace recovery and retention rules.
  1. Call tools/list.
  2. Use checkfu_search_operations when no listed tool fits.
  3. Read the exact returned input schema.
  4. Call the exact operation tool once with a stable idempotency key when required.
  5. Treat typed conflicts, policy denials, Budget failures, and ownership refusals as authoritative results, not invitations to try another interface.