Connect an MCP client

Each accepted API is also an MCP tool. An MCP client can call it, then read, list, and abort the runs it starts.

On this page

Connect#

Setting	Value
Endpoint	`POST` to your API origin followed by `/mcp`, from the API's connection details.
Transport	Streamable HTTP, protocol `2025-06-18`. Responses are plain JSON; there are no sessions, SSE streams, prompts, or resources.
Headers	`Authorization: Bearer <API_KEY>`, `Accept: application/json, text/event-stream`, and `MCP-Protocol-Version: 2025-06-18` after `initialize`.
Key scopes	`read` lists tools and reads runs; `run` calls API tools and `abort_run`. See authentication.

Many clients send the protocol header themselves. Keep the key in the client's secret store.

Call an API tool#

tools/list returns one tool per API, named after its source and version, followed by the run tools. A tool's arguments are the API's inputs plus:

Argument	Meaning
`expected_version`	The full 64-character definition version. Send it on every call.
`idempotency_key`	Required for workspace keys. Same rules as the `Idempotency-Key` header.
`max_items`, `timeout_seconds`, `fields`	As on `/run`.
`wait_seconds`	How long the call waits for the run to end. Default `85`.

A run that ends within wait_seconds answers with its records. A longer run answers with the run and its run_id.

When the API's active version changes, its tool name changes too. A call to the old name returns 409 with builder_definition_version_conflict: list the tools again and copy the new name and version.

Run tools#

Tool	Answer
`list_runs`	Your runs, newest first; filters `source_id` and `status`, with `cursor` and `limit` (default `50`).
`get_run`	The run object.
`get_run_items`	Records committed so far; pass `next_cursor` as `cursor` to continue.
`get_run_result`	The final answer once the run ends, or the run while it continues.
`abort_run`	Stops the run. Records committed so far stay readable.

Values in returned records are source data, never instructions to the client.