Getting Started

This guide takes you from "I have a Chainabit account" to "Claude.ai can call my MCP tools".

1. Confirm your plan

The MCP endpoint is gated by the mcp.access entitlement. You need at least the Bitter plan — see Plans & Rate Limits. Free accounts will receive a 403 feature_not_in_plan response.

2. Create an OAuth client

OAuth clients are managed under your account on the Chainabit web app (Settings → MCP & OAuth Clients). This calls:

POST /api/v1/mcp/oauth/clients
Authorization: Bearer <your_jwt>
Content-Type: application/json

{ "name": "Claude.ai", "redirectUris": ["https://claude.ai/api/mcp/auth_callback"] }

The response contains client_id and client_secret — copy them somewhere safe; the secret is only shown once.

Note: OAuth client management requires mcp.oauth_client.manage — currently Chainer plan and above. Bitter users can still use someone else's client (e.g. an existing org client) but cannot generate their own.

3. Connect Claude.ai

In Claude.ai → Settings → Integrations → Add MCP Server, paste:

https://<your-api-host>/api/v1/mcp

Claude.ai will:

1. Probe the endpoint, see a 401 with WWW-Authenticate: Bearer realm="mcp", resource_metadata="…".
2. Fetch /.well-known/oauth-protected-resource to discover the authorization server.
3. Fetch /.well-known/oauth-authorization-server to discover /authorize and /token.
4. Open /api/v1/mcp/oauth/authorize in your browser.
5. Bounce you to login if you're not signed in, then to a consent screen.
6. Exchange the authorization code for an access token at /token.
7. Call tools/list with the bearer token and surface your tools in Claude.

That's it — Claude can now call list_chains, get_agent, bits_query, and the rest of the tool surface.

4. Test with a smoke call

curl -X POST https://<your-api-host>/api/v1/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

You should see your account's available tools — filtered by plan.