Connect your AI assistant to the Keyban MCP server

Tutorial

What you'll do

Wire an AI assistant — Claude Code, Claude Desktop, or claude.ai — to your Keyban organization through the Model Context Protocol. At the end you'll be able to ask things like "list my applications" or "send a chat completion via Keyban", and the assistant will execute them against your real backend.

• Time~5–10 min
• DifficultyDepends on the path
• You'll needA Keyban API key

How it goes, end to end

1. 1

   Step 1: Get a key

   Mint an API key from the Keyban admin dashboard.

3. 2

   Step 2: Wire it up

   Pick the path matching your assistant — CLI, Connectors, or mcp-remote.

5. 3

   Step 3: Verify

   Ask the assistant to list your applications.

Three phases: get an API key, wire it into your assistant, then verify with a real prompt.

Step 1 — Get a Keyban API key

Sign in to the Keyban admin dashboard, open Settings → API keys, and create a new key with the permissions your assistant should have. The key is shown once — copy it now and store it safely.

Treat the key like a password

The MCP bridge forwards this key on every tool call. Anyone with the key can do anything the key is allowed to do. Don't paste it into shared chats, and rotate it from the dashboard if you suspect a leak.

Step 2 — Wire it up to your assistant

Pick the path that matches the assistant you use:

Assistant	Path	Plan needed
Claude Code (CLI)	A — claude mcp add	Any (free works)
Claude Desktop / claude.ai	B — Custom Connectors	Pro / Team / Enterprise
Claude Desktop, no paid plan	C — mcp-remote shim	Free

Path A is the simplest — one command and you're done. Path B is the cleanest UI for non-CLI users on a paid plan. Path C is the legacy fallback when neither is available.

Option A — Claude Code CLI (recommended)

One command, no JSON to edit:

claude mcp add --transport http keyban https://mcp.prod.keyban.io/mcp \
  --header "X-Api-Key: kb_live_replace_me"

The server is recorded in ~/.claude.json (or .mcp.json if you scope it to a project with --scope project). Verify the connection from inside a Claude Code session:

/mcp

keyban should appear in the list with connected. To list servers from the shell instead, run claude mcp list. To remove the server later: claude mcp remove keyban.

If you'd rather not inline the key on the command line, export it first:

export KEYBAN_API_KEY="kb_live_..."
claude mcp add --transport http keyban https://mcp.prod.keyban.io/mcp \
  --header "X-Api-Key: $KEYBAN_API_KEY"

Option B — Custom Connectors (Claude Desktop or claude.ai, Pro+)

If you're on a paid Anthropic plan, the dashboard UI handles the wiring without editing any file:

1. Open Settings → Connectors in Claude Desktop or claude.ai.
2. Click Add custom connector.
3. Fill in:
   • Name: Keyban
   • Server URL: https://mcp.prod.keyban.io/mcp
   • Auth header: X-Api-Key: kb_live_replace_me
4. Save. The connector appears in your tools palette as soon as you start a new chat.

This path also supports OAuth 2.1 if Keyban exposes an OAuth flow on the bridge later — you can swap the static API key for an interactive sign-in without rewriting your config.

Option C — Claude Desktop via mcp-remote (Free plan fallback)

Native HTTP transport isn't available on Claude Desktop Free. Use the mcp-remote shim, which proxies stdio (the only transport Claude Desktop Free accepts) to the remote HTTP endpoint.

Claude Desktop reads its MCP configuration from a JSON file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux (unofficial builds)	~/.config/Claude/claude_desktop_config.json

Open the file (create it if it doesn't exist) and add a keyban server entry:

{
  "mcpServers": {
    "keyban": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.prod.keyban.io/mcp",
        "--header",
        "X-Api-Key:${KEYBAN_API_KEY}"
      ],
      "env": {
        "KEYBAN_API_KEY": "kb_live_replace_me"
      }
    }
  }
}

A few details worth knowing:

• ${KEYBAN_API_KEY} is interpolated by mcp-remote from the env block. Storing the key in env (rather than inlining it in args) keeps it out of process listings.
• Replace https://mcp.prod.keyban.io/mcp with http://localhost:3334/mcp if you're running the bridge locally via tilt up -- --dev-mcp.
• Quit Claude Desktop entirely (⌘Q on macOS, File → Exit on Windows — closing the window is not enough), then relaunch it. The 🛠 icon in the chat composer should show keyban.

Step 3 — Verify with three short prompts

Open a new chat in your assistant (or run claude for Claude Code) and run these prompts in order. Each one exercises a different layer of the bridge.

3.1 — Read the org-scoped surface

List the applications in my Keyban organization.

The assistant calls list_applications, which is org-scoped. You should get a JSON-shaped table of every application your API key can read. If you see an empty list, your org has no applications yet — create one from the dashboard and re-run the prompt. If you see a 401, the auth header isn't reaching the bridge — see Troubleshooting.

3.2 — Run a tool with elicitation

Look up the application called "Loyalty Portal" in Keyban.

The assistant calls lookup_application_id. If exactly one application matches, the tool returns the UUID directly. If several match, the bridge elicits a choice — the assistant shows you a small picker — and resumes the call with your answer. This exercises the bridge's elicitation capability, which is the only non-trivial protocol feature most clients support today.

3.3 — Optional: a write call

Mint 10 loyalty points on the account <accountId> for SKU WINE-2020-001.

The assistant invokes mint_loyalty_points. If your organization has the Loyalty module enabled and your API key permits writes, the points are minted on-chain and the optimistic balance is updated. This proves the bridge handles tool calls (POST endpoints), not just resources.

LLM endpoints are not exposed via MCP

You won't find llm_chat_completion or list_llm_providers in your assistant's tool palette. LLM proxying through the MCP bridge is intentionally excluded — your assistant is already an LLM, so routing chat completions through Keyban's LLM API would be redundant and double-billed. The Keyban LLM API stays available for other Keyban controllers; it is just not surfaced as an MCP tool.

Troubleshooting

Claude Code

/mcp shows the server as failed. Run claude mcp list from the shell to see registered servers and their config, then re-run claude mcp add after fixing the URL or header. Common cause: a typo in the header value — the syntax is --header "X-Api-Key: kb_live_..." with a colon-space separator.

401 Unauthorized on every tool call. The API key has been revoked or never had the right permissions — mint a new one from the dashboard. Make sure you used X-Api-Key (the Keyban backend doesn't accept Authorization for static keys).

Custom Connectors

Connector saved but doesn't appear in the tool palette. Start a new chat — Claude refreshes the connector list per-conversation, not live.

Connector tile shows "Connection error". Open the tile to see the error detail. If it's a 401, rotate the key. If it's a 5xx, check https://api.prod.keyban.io/healthz.

mcp-remote (Claude Desktop Free)

npx: command not found when Claude Desktop starts. Claude Desktop spawns npx from your shell's PATH. Install Node.js from nodejs.org (the LTS build is fine), then restart Claude Desktop.

401 Unauthorized on every tool call. Three usual suspects:

• The API key has expired or been revoked — mint a new one from the dashboard.
• The header name is wrong. The Keyban backend expects X-Api-Key exactly. Don't rename it to Authorization unless you're using a JWT instead.
• Whitespace or quotes around the key. The --header X-Api-Key:${KEYBAN_API_KEY} syntax is sensitive — make sure your env value has no surrounding spaces.

Connection drops mid-conversation. The bridge attaches an Mcp-Session-Id header to negotiated sessions. Claude Desktop sometimes restarts the connection without echoing this header — the bridge closes the stale session and lets the new one through, so this is harmless. If it happens repeatedly, restart Claude Desktop.

Verifying the bridge directly (no client)

Hit the local health endpoint while developing:

curl -i http://localhost:3334/healthz

A 200 OK confirms the bridge is reachable. Otherwise check tilt status dap-mcp and tilt logs dap-mcp.

Going further

• See the MCP tools reference for the complete catalogue your assistant can now call, including which capabilities are intentionally excluded (super-admin scope).
• Cursor users can adapt the Option C snippet under .cursor/mcp.json — the configuration shape is identical, only the parent file location differs.
• The official MCP Inspector is the fastest way to validate a connection without involving an LLM client.

No connection without authentication

The Keyban MCP server never accepts anonymous traffic for org-scoped operations. If you can connect but every tool returns 401, the bridge is healthy — your auth header just isn't reaching it. That's almost always a config typo, not a server problem.