Claude (MCP Server)

Connect any Claude surface to Superkabe via the Model Context Protocol — run leads, campaigns, validation, and replies through natural language prompts

Overview

Superkabe exposes 17 tools over the Model Context Protocol — Anthropic's open standard for letting AI agents discover and call backend APIs. Once Claude is connected, you can prompt naturally:

Claude chains the right tools (import_leads → validate_leads → get_validation_results → create_campaign → launch_campaign), reads the results between steps, and executes. No Superkabe UI required for the workflow itself.

1. Claude.ai (browser)

Claude.ai connects to remote MCP servers over HTTPS using OAuth 2.0 with Dynamic Client Registration (RFC 7591) and PKCE (RFC 7636). Superkabe runs an OAuth authorization server alongside the MCP endpoint at api.superkabe.com, so the entire connection is handled in-browser through a consent flow — no API key copy/paste, no install.

Add the integration

1. Open claude.ai → Settings → Integrations → Add Integration.
2. Grab your per-org MCP URL from Dashboard → API & MCP → MCP Server tab. It looks like:

https://api.superkabe.com/mcp/<your-org-slug>

The <your-org-slug> is unique per organization. The dashboard fills in the right value for you — copy directly from there. (The legacy https://api.superkabe.com/mcp URL still works for single-org accounts, but the per-org URL is recommended for everyone.)

3. Claude.ai opens a popup to Superkabe's consent screen showing the org name.
4. Sign in to your Superkabe account if you aren't already. Important: sign in with an account that belongs to the org named on the consent screen — if you sign into a different org, Superkabe will block the consent and ask you to sign in correctly.
5. Review the requested scopes and click Authorize. The 17 Superkabe tools become available in any Claude conversation, and the resulting OAuth grant is bound to that one org only.

What happens behind the scenes

When Claude.ai first calls POST /mcp/<org-slug> without auth:

1. Superkabe returns 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp/<slug>".
2. Claude.ai fetches that metadata and discovers our authorization server.
3. Claude.ai fetches /.well-known/oauth-authorization-server for the auth endpoints.
4. Claude.ai POSTs to /register (Dynamic Client Registration) — no manual app registration required.
5. Claude.ai redirects you to /authorize with resource=https://api.superkabe.com/mcp/<slug>; we bounce to /oauth/consent on superkabe.com showing the org name.
6. You log in (with an account belonging to the named org) and click Authorize. Superkabe returns an authorization code to claude.ai with the grant pinned to that one org.
7. Claude.ai exchanges the code for an access token at /token (with PKCE verifier).
8. From here on, every /mcp/<slug> call carries Authorization: Bearer oat_…. The backend enforces that the slug in the URL matches the org the token was issued for — present an Acme token at /mcp/beta and you get 403.

Access tokens expire after 1 hour. Refresh tokens are valid for 90 days. Claude.ai refreshes silently — you only see the consent screen the first time you connect.

Verify the connection

Once authorized, the dashboard Integrations page shows the Claude card as Connected. The same status comes from GET /api/oauth/connections — see § 5.

Disconnect

Dashboard → Integrations → Claude card → Manage → Disconnect. Revokes all tokens for that client immediately. Claude.ai will prompt you to re-authorize on next use. See Disconnecting Integrations for details.

2. Local clients (Desktop, Code, Cursor)

Claude Desktop, Claude Code (CLI), Cursor, and Continue spawn the MCP server as a local stdio process on your machine. Authentication is a Superkabe API key in the env block of your client config — same key you'd use for the REST API.

Generate an API key

1. Open Dashboard → API & MCP.
2. Click Create new key. Give it a name (e.g. "Claude Desktop on laptop").
3. Tick the scopes you want Claude to have. Read-only set: account:read leads:read campaigns:read mailboxes:read domains:read replies:read validation:read reports:read.
4. Copy the key (sk_live_…). It's shown once — store it somewhere secure.

Configure your client

Same JSON shape across every client — only the file path differs:

{
  "mcpServers": {
    "superkabe": {
      "command": "npx",
      "args": ["-y", "@superkabe/mcp-server"],
      "env": {
        "SUPERKABE_API_KEY": "sk_live_your_key_here",
        "SUPERKABE_API_URL": "https://api.superkabe.com"
      }
    }
  }
}

Where to put it:

Restart your client. Look for a tools indicator (Claude Desktop shows a hammer icon, Cursor shows the connector count). 17 Superkabe tools should be available.

First prompt

Try one of these to confirm the connection:

• "List my campaigns and tell me which mailboxes are in healing."
• "Show me all replies from the last 24 hours and flag anything that looks positive."
• "If any campaign has a bounce rate above 2%, pause it."

3. The 17 tools

Every tool maps 1:1 to a v1 REST endpoint and is gated by a specific scope on your API key (or OAuth grant). Grant the minimum.

4. Security model

• Per-grant org scoping. Every OAuth access token and API key is tied to one organization. Cross-tenant access is structurally impossible — there's no "super-key" that crosses orgs.
• Hashed at rest. Both sk_live_… API keys and oat_… OAuth tokens are stored only as SHA-256 hashes. The plaintext value is shown to the user once at creation and never again.
• Scope-gated tools. The MCP server attempts every tool, but the backend rejects calls whose scope isn't on the bearer token. Read-only keys can't create campaigns even if Claude tries.
• Short-lived OAuth tokens. Access tokens expire after 1 hour; refresh tokens after 90 days. Revocation via POST /revoke or the dashboard is immediate.
• PKCE-only OAuth. All OAuth clients are public clients with PKCE — no client secrets shipped to claude.ai or any other browser-resident integration.
• Stateless transport. The HTTP MCP endpoint (/mcp) holds no per-session state — every request is independently authenticated, no session hijack surface.
• Stdio opens no ports. Local clients spawn the npm package as a subprocess that talks over stdin/stdout. Compromise requires local process access.

5. API reference (OAuth + connections)

Discovery

GET https://api.superkabe.com/.well-known/oauth-authorization-server
GET https://api.superkabe.com/.well-known/oauth-protected-resource/mcp
GET https://api.superkabe.com/.well-known/oauth-protected-resource/mcp/<your-org-slug>

The third endpoint is per-org and returns metadata pointing at resource: https://api.superkabe.com/mcp/<slug>. Claude.ai discovers it from the WWW-Authenticate header on the first /mcp/<slug> call. Returns 404 for unknown slugs.

OAuth endpoints

• POST /register — Dynamic Client Registration (RFC 7591). Returns client_id; no secret (PKCE).
• GET /authorize — kicks off the consent flow. Redirects to /oauth/consent on superkabe.com.
• POST /token — exchanges authorization code for access + refresh tokens. Also handles refresh-token grant.
• POST /revoke — revokes a single token (access or refresh).

List active connections

GET https://api.superkabe.com/api/oauth/connections
Authorization: Bearer sk_live_…  # or any auth — JWT cookie also works

Response:

[
  {
    "client_id": "mcp_client_a4cce2cca6baf67e084ef681",
    "client_name": "Claude",
    "client_uri": null,
    "logo_uri": null,
    "scopes": ["account:read", "leads:read", "leads:write", "campaigns:read", "campaigns:write", ...],
    "granted_at": "2026-04-29T10:43:24.000Z",
    "last_used_at": "2026-04-29T11:02:08.000Z",
    "access_token_expires_at": "2026-04-29T12:02:08.000Z",
    "refresh_expires_at": "2026-07-28T10:43:24.000Z"
  }
]

Powers the "Connected" status on the Integrations page. One row per distinct OAuth client tied to your org with at least one non-revoked, non-expired grant. Refresh-token rotation is deduped by client_id.

Revoke connections

POST https://api.superkabe.com/api/oauth/connections/revoke
Authorization: Bearer <jwt-or-api-key>
Content-Type: application/json

{ "client_id": "mcp_client_a4cce2cca6baf67e084ef681" }

Marks every access & refresh token for that (org, client) pair as revoked. Effective immediately — claude.ai will get 401 on next call. Omit client_id to revoke all OAuth grants for the org at once.

6. Troubleshooting

Verbose logs (stdio)

# Claude Desktop (macOS)
tail -f "$HOME/Library/Logs/Claude/mcp-server-superkabe.log"

# Claude Desktop (Windows)
Get-Content -Wait "$env:APPDATA\Claude\Logs\mcp-server-superkabe.log"

# Cursor
tail -f "$HOME/.cursor/logs/mcp-server-superkabe.log"

# Verbose Node HTTP tracing
NODE_DEBUG=http,https SUPERKABE_API_KEY=… npx @superkabe/mcp-server