Connect an agent with MCP

Connect a Streamable HTTP MCP client, discover the tools, start work, and handle an approval.

The Developer API at https://api.openfactor.ai also exposes its operations as tools through Open Factor's Streamable HTTP MCP endpoint. An MCP-capable client can inspect projects, start workflows, and read results without a bespoke client.

Endpoint

Use this Streamable HTTP endpoint to connect an MCP client:

{
  "url": "https://mcp.openfactor.ai/mcp",
  "headers": {
    "Authorization": "Bearer <your API key>"
  }
}

The endpoint uses /mcp for Streamable HTTP. The /.well-known/oauth-protected-resource/mcp endpoint publishes its RFC 9728 protected-resource metadata, including the authorization server.

Authentication

Authenticate with a Developer API key sent as Authorization: Bearer <api-key> or x-api-key: <api-key>, or with a platform OAuth 2.0 access token sent as Authorization: Bearer <access-token>. Public discovery is readable without credentials; tool calls require authentication. See API keys and the API overview for credentials and access details.

Discover the tools

Start with the four task tools: handoff, status, result, and budget. Every API operation is also available as a tool named by its canonical command, such as workflows.runs.control. Use resources/list and resources/read to discover and read the served developer guide. Call tools/list for the current tool schemas.

Start work and follow it

handoff starts a Workflow from a plan, a named template, or a published revision. status reports the run state, task progress, and any pendingApprovals. result returns completed outputs, and budget reports spend.

Approvals

When policy requires approval, handoff returns approval_required with an idempotencyKey, plus workflowId and revisionId when the start was gated. Approval happens outside MCP. After approval, call handoff with the returned ids to get the run. If the response includes only the key, approval publishes the Workflow without starting it; find its revision with the workflow list and get tools, then call handoff with its ids.

Durable tasks

A client that declares the io.modelcontextprotocol/tasks extension on the 2026-07-28 protocol may receive a durable task handle from handoff. The task follows the same Workflow run, polls with tasks/get, and cancels with tasks/cancel. The handle is bound to the API key that created it.

Next steps