Integration guide

MCP Tool Server

Connect temporalBLOCK to Claude Desktop, Cursor, Windsurf, or any MCP-compatible AI assistant in seconds. Your API key is the only required configuration — no OAuth, no local proxy, no extra tooling.

Auth

Send your tblk_live_* or tblk_test_* key as the X-API-Key header on every request. Get a key from the waitlist. Free-tier demo keys work too — a great way to test the integration before upgrading.

Do not use Authorization: Bearer <key> — that returns a 401 WRONG_AUTH_HEADER error. A missing or unrecognised key returns a 401 INVALID_API_KEY error.

What is MCP?

The Model Context Protocol (MCP) is an open standard for giving AI assistants access to external tools and data sources. When you add temporalBLOCK as an MCP server, your AI client automatically discovers the full Temporal Skills catalog — no prompt engineering or function-call wiring required.

The server speaks JSON-RPC 2.0 over HTTP, supports the Streamable-HTTP SSE transport required by Claude Desktop, and is stateless — every request is independent with no session management needed on your end.

One-line config

Add the following block to your AI client's MCP server config file, replacing tblk_live_YOUR_KEY_HERE with a key from your dashboard.

// claude_desktop_config.json (or your client's equivalent)
{
  "mcpServers": {
    "temporalblock": {
      "url": "https://api.temporalblock.com/api/v1/mcp",
      "headers": {
        "X-API-Key": "tblk_live_YOUR_KEY_HERE"
      }
    }
  }
}

The snippet above uses the Claude Desktop / Cursor format. The dashboard waitlist generates a pre-filled version with your actual key.

Supported clients

Any client that speaks MCP Streamable-HTTP transport (protocol version 2025-06-18) works. The table below shows the config file location for the most common ones.

Client	Config location
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
ChatGPT Desktop	Settings → MCP Servers in the app (macOS). Uses the same mcpServers JSON block.
Cursor	.cursor/mcp.json in your project root, or ~/.cursor/mcp.json globally
Windsurf	~/.codeium/windsurf/mcp_config.json
Any MCP host	See your client's documentation for the mcpServers config location

Auto-discovery manifest

The manifest at https://api.temporalblock.com/api/mcp.json returns server metadata (name, version, auth scheme, endpoints) in a machine-readable format so AI clients can auto-configure. No auth required.

curl https://api.temporalblock.com/api/mcp.json

Tool list & tier gating

tools/list returns the entire catalog. Tools outside your key's tier include an "Upgrade to Standard" or "Upgrade to Pro" note in their description so your AI assistant can explain what is available — rather than silently hiding capabilities.

To browse the raw tool list for your key:

// Fetch the live tool list to see what your key can call
curl -H "X-API-Key: tblk_live_YOUR_KEY_HERE" \
  "https://api.temporalblock.com/api/v1/tools?format=anthropic"

See Temporal Skills for the full tier breakdown: Bundled (Lite+), Standard+, and Pro+. Free demo keys expose a smaller starter set (calibration, calendars, date-math) — enough to verify the integration end-to-end.

Endpoints

Path	Description
POST /api/v1/mcp	JSON-RPC 2.0 endpoint. Supports `initialize`, `tools/list`, `tools/call`, `ping`.
GET /api/v1/mcp	SSE streaming transport. Set `Accept: text/event-stream`. Required by Claude Desktop and other streaming-capable clients.
GET /api/mcp.json	Public manifest. Machine-readable server metadata for auto-discovery. No auth required.

Getting Started Guide — authentication, calibrate, bridge & full endpoints.
Temporal Skills — full catalog of tools exposed through the MCP surface, with tier breakdown.