MCP Server v1.0.0

Connect Claude Desktop or any Model Context Protocol (MCP) client to your Superkabe organization. Drives the full v1 API surface — 16 tools covering leads, campaigns, validation, replies, and infrastructure — through a single Node.js subprocess over stdio.

1. What is MCP?

The Model Context Protocol is an open standard for connecting AI clients (like Claude Desktop, Claude Code, Cursor, and third-party agents) to external tools, data sources, and actions through a uniform JSON-RPC contract. An MCP server exposes a set of tools, resources, and prompts that the client can discover and invoke on behalf of the model.

The Superkabe MCP server is a thin translation layer: it receives tool invocations from the client over stdio, turns them into authenticated HTTPS calls against /api/v1, and returns the structured JSON response back to the model.

2. Why use it?

• Chat with your platform. Ask Claude Desktop "which of my mailboxes have bounced in the last 24h?" and let it answer from live Superkabe data.
• Agentic workflows. Build agents in Claude Code or Cursor that plan outbound campaigns, inspect engagement, draft replies, or audit deliverability — all without hand-rolling the REST client.
• Zero glue code. Input/output schemas are declared with Zod and auto-discovered by every MCP client. You do not write client bindings.
• Least-privilege security. The key you hand the MCP server carries exactly the scopes you grant — nothing more. Revoke the key to revoke the agent.

3. Installation

Prerequisites

• Node.js 20 or newer
• A Superkabe account and an API key generated from Dashboard → API & MCP
• An MCP-compatible client — Claude Desktop, Claude Code, Cursor, Continue, or any custom runtime

Option A — install from source (recommended during staging)

git clone https://github.com/Superkabereal/Superkabe.git superkabe
cd superkabe/mcp-server
npm install
npm run build # compiles TypeScript to dist/index.js

Option B — npx (once published)

# No install step — npx fetches and runs on demand
SUPERKABE_API_KEY=sk_live_... npx -y @superkabe/mcp-server

Sanity-check the server

Run it directly and confirm it prints the connection line to stderr:

SUPERKABE_API_KEY=sk_live_abc123 \
SUPERKABE_API_URL=https://api.superkabe.com \
node dist/index.js

# stderr:
# Superkabe MCP Server v1.0.0 connected (https://api.superkabe.com)

The process will sit idle waiting for JSON-RPC on stdin. Ctrl-C to exit. MCP clients spawn this process automatically — you do not run it manually in normal use.

4. Client configuration

4.1 Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
 "mcpServers": {
 "superkabe": {
 "command": "node",
 "args": ["/absolute/path/to/superkabe/mcp-server/dist/index.js"],
 "env": {
 "SUPERKABE_API_KEY": "sk_live_abc123...",
 "SUPERKABE_API_URL": "https://api.superkabe.com"
 }
 }
 }
}

Restart Claude Desktop. A new tools icon should appear in the chat — clicking it lists all 16 Superkabe tools.

4.2 Claude Code

Two equivalent options. Same JSON shape as Claude Desktop:

• Global: add to ~/.claude/settings.json under an mcpServers key.
• Per-project: create .mcp.json at the project root.

// .mcp.json (project root) or under mcpServers in ~/.claude/settings.json
{
 "mcpServers": {
 "superkabe": {
 "command": "npx",
 "args": ["-y", "@superkabe/mcp-server"],
 "env": {
 "SUPERKABE_API_KEY": "sk_live_abc123...",
 "SUPERKABE_API_URL": "https://api.superkabe.com"
 }
 }
 }
}

Restart the Claude Code session. /mcp in the CLI lists registered servers; the Superkabe tools should appear with no further setup.

4.3 Cursor

Cursor reads MCP config from one of two locations:

• Global: ~/.cursor/mcp.json
• Per-project: <project>/.cursor/mcp.json

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

Open Cursor Settings → MCP to see the server status (green dot = connected). Composer agents pick up the tools automatically on next prompt.

4.4 Continue

Continue reads <project>/.continue/config.json. Add an mcpServers entry alongside your existing config:

// .continue/config.json
{
 "models": [ /* your models */ ],
 "mcpServers": {
 "superkabe": {
 "command": "npx",
 "args": ["-y", "@superkabe/mcp-server"],
 "env": {
 "SUPERKABE_API_KEY": "sk_live_abc123...",
 "SUPERKABE_API_URL": "https://api.superkabe.com"
 }
 }
 }
}

4.5 Auto-configure (any client)

If you cloned the repo, run the bundled setup script — it detects which clients you have, prompts for your API key + URL, and writes the right JSON to the right path:

cd superkabe/mcp-server
./setup.sh

Re-run any time to update credentials or add another client.

4.6 Built from source instead of npx

If you cloned the repo and ran npm run build, swap command/args for an absolute path to the compiled entry:

"command": "node",
"args": ["/absolute/path/to/superkabe/mcp-server/dist/index.js"],

4.7 Environment variables

4.8 Scope matrix — which scopes do I need?

Each MCP tool is gated by a single API-key scope. Pick the scopes that match the tools you actually want the agent to call. The agent will receive a Missing required scope error for anything you didn't grant.

Recommended scope bundles

• Read-only analyst (11/16 tools, zero writes): account:read leads:read validation:read campaigns:read reports:read replies:read mailboxes:read domains:read
• Lead ops (read-only + import + validate, no campaign sends): the read-only set plus leads:write validation:trigger
• Full agent (all 16 tools incl. real sends): every scope above plus campaigns:write replies:send

5. Tool call lifecycle

1. User asks Claude a question that requires live data.
2. Claude chooses a registered tool and emits tool_use with JSON arguments.
3. The MCP client serializes the call as JSON-RPC and writes it to the server's stdin.
4. The server validates the arguments against the Zod schema, makes an HTTPS call to the Superkabe v1 API with Authorization: Bearer $SUPERKABE_API_KEY.
5. The v1 controller enforces the relevant scope, runs the Postgres query, returns { success, data }.
6. The server wraps the response as a text content block (JSON-stringified) and returns it over stdio.
7. Claude receives the tool_result, incorporates it into its next response.

6. Security model

• No ambient credentials. The server reads exactly one env var (SUPERKABE_API_KEY). It does not read ~/.aws/credentials, gcloud, or any other system state.
• Scoped keys. The tools the server attempts are defined at build time. The tools the server is allowed to execute are determined by the scopes on the API key you hand it. Grant the minimum.
• Organization scoping. Every API call is automatically scoped to the key's organization by orgContext. The MCP server cannot leak across tenants.
• Rate limits apply. MCP traffic is rate-limited per API key like any other client (§6 of the API documentation).
• Stdio not sockets. The server opens no listening ports; compromise requires local process access.
• No persistent state. The server holds only transient request context. Killing the process forgets everything.

7. Tool reference

Every tool exposed by the Superkabe MCP server, in the order it appears in mcp-server/src/index.ts. Each tool maps 1:1 to a v1 API endpoint — see the API documentation for response shapes.

8. Error handling

When the v1 API returns a non-2xx status, the MCP server converts the error into a text content block and sets isError: true on the tool result. Example:

// Server returns to Claude:
{
 "content": [{ "type": "text", "text": "Error: Missing required scope: campaigns:write" }],
 "isError": true
}

Common failure modes and how Claude should recover:

9. Example sessions

9.1 Daily deliverability brief

9.2 Launching a net-new campaign

9.3 Reply triage

10. Troubleshooting

Enable debug logging

The server logs to stderr so MCP client logs capture it:

# macOS Claude Desktop logs
tail -f "~/Library/Logs/Claude/mcp-server-superkabe.log"

# Run manually with verbose Node logs
NODE_DEBUG=http,https SUPERKABE_API_KEY=... node dist/index.js

11. Updating

When new tools are added to the Superkabe MCP server you simply update the package and restart your MCP client — schemas are auto-advertised over the protocol. No client code changes.

cd superkabe/mcp-server
git pull
npm install
npm run build
# Restart Claude Desktop / Cursor / your client

12. Protocol compatibility

• Implements MCP server capability tools only — no resources, prompts, or sampling yet.
• Tested against @modelcontextprotocol/sdk 1.12.x on the server side; any conformant MCP client should interoperate.
• Transport is StdioServerTransport. HTTP/SSE transport is on the roadmap; open an issue if you need it.