MCP Server Docs: Claude, Cursor & API Setup

1. In Claude, open Settings → Connectors and remove the existing Brand Kit OS connector.
2. Click Add Custom Connector and paste:
   https://www.brandkitos.com/mcp

   bk_claude_connector_v1
   No Client Secret — PKCE handles verification.
3. Approve OAuth. The Brand Kit OS icon will appear on the connector tile.

Applies to all tools equally. If you hit the limit, wait up to 60 seconds.

Granular section write scopes

Instead of brand_kit:write, you can grant least-privilege keys with per-section scopes such as brand_kit:write:expression. Configure these in Settings → API Keys.

Team membership gate

Shared brand kits: viewers and editors can read, but only owners or members with role admin may use write or generate tools via MCP, even when the credential lists write scopes. Check membership_role from list_brand_kits before calling write tools.

Content Types

The server supports both application/json and text/event-stream responses based on the client's Accept header.

Session Management

The server issues an Mcp-Session-Id header on the initialize response. Clients should include this header on all subsequent requests for the same session.

Tool error response shape

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "isError": true,
    "content": [{ "type": "text", "text": "Access denied to this brand kit" }],
    "_meta": {
      "error_code": "access_denied",
      "retryable": false,
      "recovery_hint": "Confirm the brand_kit_id is correct, or ask the brand kit owner to share it..."
    }
  }
}

Error codes & recommended agent behavior

Request correlation

Every response carries an Mcp-Request-Id header (also exposed inside _meta.request_id on tool errors and inside JSON-RPC error.data.request_id on protocol errors). Paste it into Settings → API Keys → Analytics to find the row in request logs.

Time budgets

• • Each tool call has a 90-second ceiling.
• • AI gateway calls (generate_*) have a 60-second sub-budget; the upstream fetch is cancelled on timeout.
• • Tokens are refunded automatically when an AI call times out or fails after deduction.

"No brand kit tools available"

The MCP server connection may not have started. Check that your API key or OAuth connection is valid and restart Claude Desktop.

401 Unauthorized / "Invalid API key"

Your API key may have expired or been revoked. Generate a new one from Settings → API Keys.

403 Forbidden — "Subscription required"

MCP access requires a Base or Premium plan. Upgrade your plan.

429 Rate limit exceeded

Wait up to 60 seconds and try again. The limit is 100 requests per minute.

Connector not appearing in Claude

Make sure you've completely quit Claude Desktop and restarted it. For the Custom Connector, verify you entered the correct Server URL and Client ID.

Globe icon on the Claude connector tile

Claude caches the favicon from the server URL you originally pasted. Remove the existing Brand Kit OS connector in Settings → Connectors and re-add it using the branded URL https://www.brandkitos.com/mcp to pick up the Brand Kit OS icon.

Claude asks for approval on every tool call

This is a Claude client behavior, not a Brand Kit OS issue. Our MCP server already sends the readOnlyHint annotation on every read and preview tool (list_*, get_*, preview_*), per the MCP spec. Claude's connector UI currently prompts for approval regardless of this hint. Cursor and Cline honor the annotation and auto-approve read/preview calls. You can safely approve repeated read calls in Claude — they do not modify any data.