MCP client compatibility

What every MCP-speaking client expects in its config, where its quirks live, and how to point it at BlackLake. The site (https://www.blacklake.systems) names these clients in the marketing-promise audit; this doc is the engineering source of truth keeping those claims honest.

Two BlackLake MCP modes:

Local mode — npx blacklake serve exposes http://localhost:8788/mcp (stdio + SSE). Use for laptops, customer-owned execution, stdio upstreams.
Cloud mode — https://api.blacklake.systems/mcp and /mcp/u/<upstream> (HTTPS only). Use when the gateway runs in BlackLake and the agent runs anywhere with internet.

Client	Transport	Auth	Cloud OK?	Local OK?	Tested versions	Notes / quirks
Claude Code (Anthropic CLI)	stdio + http	`Authorization: Bearer` env	✅	✅	0.12+ (2026-05)	Reads `mcpServers` from `.claude/mcp.json` per-project. Long-running tool calls get cancelled at 60s — set `BLACKLAKE_TIMEOUT_MS=120000` if needed.
Codex (OpenAI Codex CLI)	http	`x-api-key` header	✅	✅	0.7+ (2026-04)	Config in `~/.codex/mcp.json`. Streaming SSE works; auto-reconnect on disconnect.
Cursor	stdio + http	env var, `Authorization`	✅	✅	0.45+	UI editor at Settings → MCP. Stdio servers load on app start; http servers on first call.
Windsurf	http	`Authorization`	✅	✅	1.0+	Uses `mcp_config.json` per workspace. No stdio support; cloud-mode only.
Claude Desktop	stdio	env var	✅ via local proxy	✅	1.0+	Config in `~/Library/Application Support/Claude/claude_desktop_config.json` (mac). Cloud mode requires running `npx blacklake serve` locally and pointing Claude Desktop at the local stdio endpoint.
Aider	http	env var, `Authorization`	✅	✅	0.85+	`--mcp` flag. CLI-only, no UI.
Goose (Block)	http	`Authorization`	✅	✅	1.0+	Config in `~/.config/goose/mcp_servers.toml`. Streaming partial.
VS Code Copilot	stdio	env var	❌ today	✅	preview	Stdio only in current preview; cloud HTTPS support shipping in vNext.
JetBrains AI	http	`Authorization`	✅	✅	2025.1+	Plugin settings → MCP servers.

Legend: ✅ supported and tested. ❌ not supported on the listed transport. "✅ via local proxy" means the client speaks stdio only and needs npx blacklake serve running locally as a bridge.

Config snippets — top three#

Claude Code#

.claude/mcp.json in the repo root:

{
  "mcpServers": {
    "blacklake": {
      "url": "https://api.blacklake.systems/mcp/u/<upstream-id>",
      "headers": {
        "Authorization": "Bearer ${BLACKLAKE_API_KEY}"
      }
    }
  }
}

For local mode swap the URL for http://localhost:8788/mcp/u/<upstream-id>.

Codex#

~/.codex/mcp.json:

{
  "blacklake": {
    "url": "https://api.blacklake.systems/mcp/u/<upstream-id>",
    "headers": {
      "x-api-key": "${BLACKLAKE_API_KEY}"
    }
  }
}

Cursor#

Settings → MCP → Add server, paste:

{
  "blacklake": {
    "url": "https://api.blacklake.systems/mcp/u/<upstream-id>",
    "headers": {
      "Authorization": "Bearer ${BLACKLAKE_API_KEY}"
    }
  }
}

Cloud vs local differences#

Property	Cloud (`api.blacklake.systems`)	Local (`localhost:8788`)
Transport	HTTPS + SSE	HTTP + SSE + stdio
OAuth-aware upstreams	Yes (per-upstream OAuth)	Static credentials only today
Stdio upstreams	No	Yes
Customer-owned execution	No	Yes
Latency	~50–150ms gateway hop	~5–20ms loopback
TLS	Required	Not enforced

Stdio upstreams (e.g., npx some-mcp-server) only work in local mode because they're a child process — the cloud gateway can't fork a customer's binary.

Smoke test per client#

A working blacklake_evaluate call from each client end-to-end is the minimum smoke. The test:

Configure the client with the snippet above.
Call any tool the upstream exposes from inside the client.
Confirm a row landed at GET /v1/evaluations with agent_resolved: true.
The decision token comes back on the response (bldt_v1: or bldt_v2:).

If the client supports SSE streaming, also confirm partial chunks land in the client UI, not just the final response.

Known compatibility issues#

Claude Code 0.10.x dropped streamed responses on auth errors. Fixed in 0.11.0 — recommend upgrading.
Cursor < 0.43 parsed env-var substitution incorrectly (${VAR} printed verbatim). Fixed in 0.43+.
Windsurf 0.9.x had no auto-reconnect; required closing + reopening the workspace after a network blip. Fixed in 1.0.
VS Code Copilot preview stdio only — see the matrix.

When a client breaks#

Capture the request that hit BlackLake — GET /v1/audit?source=mcp&limit=20 shows the last 20 MCP-routed events.
Check the upstream health: GET /v1/mcp/upstreams/:id/health.
If signature/auth is the issue, regenerate the upstream secret via POST /v1/mcp/upstreams/:id/rotate.
If the client claims a tool that BlackLake doesn't reflect, run POST /v1/mcp/upstreams/:id/refresh-tools to re-discover.

Public claim audit#

The site claims compatibility with all clients above. This doc is the source of truth for which versions we've actually tested (the Tested versions column). When marketing or sales adds a new client to the public list, add a row here first or note the gap in docs/CLAIM-TO-CAPABILITY-REGISTRY.md.