MCP

Headcode exposes its data APIs as Model Context Protocol tools, in addition to the REST API documented elsewhere in this site. Every tool mirrors exactly one REST endpoint and enforces the same data scope, so an MCP client and a REST caller see the same data under the same access rules.

The server is a stateless Streamable HTTP endpoint — a single JSON-RPC endpoint, not one path per tool.

Endpoint and authentication

https://api.headcode.dev/mcp

Authenticate the same way as REST, with an API key as a bearer token:

Authorization: Bearer hc_live_...

See Authentication for how to get a key, and API keys for scoping and rotating one.

Claude Code

claude mcp add --transport http headcode https://api.headcode.dev/mcp \
  --header "Authorization: Bearer hc_live_..."

Claude Desktop

Add an entry under mcpServers in Claude Desktop’s configuration file:

{
  "mcpServers": {
    "headcode": {
      "type": "http",
      "url": "https://api.headcode.dev/mcp",
      "headers": {
        "Authorization": "Bearer hc_live_..."
      }
    }
  }
}

Generic Streamable HTTP client

Any client that speaks MCP over Streamable HTTP can connect directly. Point it at the endpoint and send the bearer token on every request as a normal HTTP header — there is no separate handshake or session cookie beyond the Authorization header:

POST https://api.headcode.dev/mcp
Authorization: Bearer hc_live_...
Content-Type: application/json

Send standard MCP JSON-RPC methods (initialize, tools/list, tools/call, and so on) as the request body.

Available tools

The full, generated list of tools — names, descriptions, input schemas, required scope, and the REST endpoint each one mirrors — is on the MCP tools reference page. That page is generated directly from the live tool registry, so it is always in sync with what the server actually exposes.

Per-tier availability

Reaching /mcp at all requires the account’s plan to carry the mcp scope, on top of whatever per-tool data scopes (boards:read, history:read, and so on) a given tool needs — the same scopes REST enforces. At the time of writing, only the Enterprise plan grants mcp, so the MCP transport is currently an Enterprise-only capability. This placement is provisional pending a pricing decision and may change; see Plans and rate limits for the current plan table.

A key that is missing the mcp scope gets 403 Forbidden on every request to /mcp, including initialize and tools/list — the check happens before the request reaches any tool.

Quota behaviour

Every HTTP request to /mcp counts towards the account’s burst and daily rate limits exactly like a REST request, including protocol-overhead requests such as initialize and tools/list, not just tools/call. The counter is shared with REST calls made on the same key — there is no separate MCP allowance. See Plans and rate limits for how the limits work and what happens when one is exceeded.