Chainabit MCP Server

This page covers exposing Chainabit as an MCP server to clients such as Claude Desktop, Cursor, and Windsurf. It does not cover connecting an external MCP server to Chainabit or using the NEXUS local MCP server. Once connected, a client can discover the tools available to your workspace.

What the Chainabit MCP server exposes

The server implements the Model Context Protocol over HTTP POST (/api/v1/mcp). After authentication, the AI client auto-discovers all tools available to your workspace, including:

• Native Chainabit workspace tools (bits, chainies, chains, calendar, etc.)
• Active connector tools from your workspace (GitHub, Notion, Slack, and others)

The tool list is driven by your workspace configuration — connectors you have enabled appear automatically.

Authentication options

Option A — API key (simplest)

1. Log in to chainabit.com
2. Go to Settings → API Keys
3. Click Generate new key and copy it — you cannot view it again

Use this key as a Bearer token in the Authorization header.

Option B — OAuth 2.0 + PKCE (recommended for Claude Desktop)

Chainabit supports OAuth 2.0 Authorization Code + PKCE. MCP clients that support OAuth (such as newer Claude Desktop versions) can authenticate without a static API key.

The OAuth discovery endpoint is:

GET https://api.chainabit.com/.well-known/oauth-authorization-server

Claude Desktop and other MCP clients that support RFC 8414 will discover the flow automatically. For manual setup, see the OAuth flow section below.

Option C — OAuth client credentials (for Claude.ai and tools with a backend)

Claude.ai's remote MCP connector requires an OAuth Client ID and OAuth Client Secret. Chainabit lets you generate these directly from your account settings.

Available on the Pro plan.

1. Log in to chainabit.com
2. Go to Settings → API → MCP OAuth Clients
3. Click Generate new client — enter a name and your redirect URI (e.g. https://claude.ai/callback)
4. Copy the Client ID and Client Secret — the secret is shown once

Then in Claude.ai's Add custom connector form:

• Remote MCP server URL: https://api.chainabit.com/api/v1/mcp
• OAuth Client ID: (your generated client ID)
• OAuth Client Secret: (your generated client secret)

Claude.ai will handle the full OAuth flow — redirecting you to Chainabit's consent screen and exchanging tokens automatically.

Connect your AI client

Claude Desktop (API key)

Open ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and add:

{
  "mcpServers": {
    "chainabit": {
      "url": "https://api.chainabit.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CHAINABIT_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. A hammer icon indicates tools are available.

Cursor

Go to Cursor Settings → MCP → Add Server and enter:

• Name: Chainabit
• URL: https://api.chainabit.com/api/v1/mcp
• Auth header: Authorization: Bearer YOUR_CHAINABIT_API_KEY

Windsurf

Go to Windsurf Settings → Extensions → MCP Servers and add:

{
  "name": "chainabit",
  "url": "https://api.chainabit.com/api/v1/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_CHAINABIT_API_KEY"
  }
}

OAuth 2.0 flow

For clients that support OAuth 2.0 Authorization Code + PKCE natively, Chainabit acts as the authorization server. The flow:

1. Client calls GET /api/v1/mcp/oauth/authorize with client_id, redirect_uri, code_challenge (S256), and scope=mcp:tools
2. Chainabit redirects to the consent UI at chainabit.com/consent
3. You approve the request — Chainabit redirects back to redirect_uri?code=...
4. Client exchanges the code via POST /api/v1/mcp/oauth/token using code_verifier
5. Client receives access_token (1 hour TTL) and refresh_token (30 day TTL)
6. Client calls POST /api/v1/mcp/oauth/token with grant_type=refresh_token to rotate tokens

Client ID: chainabit-mcp (no secret required — public client) Allowed scopes: mcp:tools openid profile:read

Workspace tool policies

You can control which tools are available to AI clients per workspace:

Policy	Behavior
allow	Tool runs without any confirmation prompt
ask	Tool always requires your approval before running
block	Tool is disabled — the AI client receives an error

Manage policies at: Settings → Workspace → Tool Permissions

Or via API: PUT /api/v1/workspaces/{workspaceId}/tool-policies/{toolKey}

# Block a destructive tool
curl -X PUT https://api.chainabit.com/api/v1/workspaces/YOUR_WS_ID/tool-policies/bits.delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"policy": "block"}'

Example prompts

Once connected, try:

Search my bits for anything related to sprint planning.

List the connector instances in my workspace. Which ones are from GitHub?

What chains do I have? Get details for the one named "Morning Review".

Who are the members of my workspace and what roles do they have?

Health check

curl -X POST https://api.chainabit.com/api/v1/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"ping","id":1}'

Expected response:

{"jsonrpc":"2.0","id":1,"result":{}}

List available tools

curl -X POST https://api.chainabit.com/api/v1/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'