CLI tools — five-minute quick start

Govern Claude Code, Codex, Cursor, or any other MCP-compatible CLI tool through BlackLake. Every tool call to GitHub, Cloudflare, Linear, Sentry, Notion, your filesystem, your shell — flows through your policies and lands a signed receipt on the audit ledger. The developer keeps using their tool normally; MCP is one of the capture paths into BlackLake's control plane.

This is the fastest path for many coding tools. The same policy, cost, and receipt model also applies through the SDK, CI, shell wrapper, cloud audit ingest, existing workflow engines, and Depth durable workflows.

What you'll set up#

  CLI tool  →  MCP client config  →  BlackLake MCP gateway  →  Policy  →  Upstream MCP  →  Signed receipt

The CLI tool stays the same. The MCP client config (.mcp.json for Claude Code, ~/.cursor/mcp.json for Cursor, etc.) gets one extra entry — blacklake — pointing at our gateway. That's the whole integration.

1. Get a user-scoped API key#

Sign in to console.blacklake.systems and create one in Settings → API keys. The key starts with bl_usr_….

2. Add BlackLake to your tool's MCP config#

Claude Code#

Add to .mcp.json in your project root (or ~/.claude/mcp_servers.json for global):

{
  "mcpServers": {
    "blacklake": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.blacklake.systems/mcp",
        "--header",
        "Authorization: Bearer YOUR_BL_USR_KEY"
      ]
    }
  }
}

Codex#

Codex reads .codex/config.json. Add:

{
  "mcpServers": {
    "blacklake": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.blacklake.systems/mcp",
        "--header",
        "Authorization: Bearer YOUR_BL_USR_KEY"
      ]
    }
  }
}

Cursor#

Cursor → Settings → MCP Servers → add an entry pointing at https://api.blacklake.systems/mcp with the same Authorization: Bearer header.

Other clients#

Any MCP-compatible tool follows the same shape. The two URL forms BlackLake exposes:

• Aggregate (default) — https://api.blacklake.systems/mcp — fans out to every MCP service you've registered. One connection, every tool. Recommended.
• Per-service — https://api.blacklake.systems/mcp/u/<service-name> — single named endpoint scoped to one service. Useful when you want a CLI tool talking only to one provider, for example an MCP-integrated GitHub AI Actor.

3. Register an upstream MCP server#

The console's MCP Upstreams page has one-click templates for the providers you probably want first: Linear, Notion, Sentry, Cloudflare Radar, Cloudflare Docs, Atlassian, GitHub. Pick one — the form pre-fills the canonical MCP URL, the OAuth mode, and a sensible starter policy. Click Add upstream.

If the provider supports OAuth dynamic-client-registration (Linear, Notion, Sentry, Cloudflare Radar, Atlassian), follow the Set up auth flow to wire it up — BlackLake registers the client automatically. For providers without OAuth metadata (the public GitHub MCP server), paste a personal access token as a static Authorization: Bearer header on the upstream row.

4. Make a real call#

Restart your CLI tool and ask it to do something a real human would ask:

"Search the Cloudflare docs for queue retry semantics"

The first call auto-creates an AI Actor (mcp:cloudflare-docs), an inventory of the service's tools, and a default mcp:cloudflare-docs:default policy with the recommended outcome from the template. Watch the call land on console.blacklake.systems/evaluations.

5. Write your first real policy#

The default auto-created policy is a sensible starting point — typically allow for read-only providers and approval_required for write-capable ones. Sharpen it:

• Console → Policies → Start from a recipe ships six prebuilt patterns: ask before production deploys, deny cloud deletion, ask before refunds, allow read-only docs/search, two-person approval for payments, deny if estimated cost exceeds limit.
• Pick the one that fits, tweak the selectors, and save.

Every governed call now produces a signed receipt — bl.decisions.verify(decision_token) from the SDK proves the decision was real, not an LLM hallucination.

What about the developer experience?#

It doesn't change. Claude Code / Codex / Cursor see one extra MCP server (blacklake) and use it like any other. The user types prompts, the tool calls tools, BlackLake quietly evaluates and forwards. Calls that need approval pause; the approver gets a magic-link in email or push notification and decides on their phone. Calls that get denied surface as a normal MCP error the AI Actor can react to.

Next steps#

• Mobile approvals — set up notifications in Console → Settings so approvers can decide from their phone via the magic-link /decide page.
• Cost coverage — the Console → Usage page shows per-call cost across all priced models. Pricing coverage lists which models are tracked; unpriced models get an explicit warning instead of silently rolling up as $0.
• Integration health — Console → Integrations → Health aggregates MCP / GitHub / webhooks / audit ingest / cost capture into one operator view.
• Session identity — when you graduate to SDK calls, pass context.session = { user, machine, repo, branch, cwd, tool_client } so the audit trail attributes work correctly per developer. See Concepts → Session-actor convention.