MCP Authentication
Sign in with your Betterness account, or use an API key.
Two ways in
| Method | Best for | How |
|---|---|---|
| Sign in (OAuth) | Claude, ChatGPT and other apps you use yourself | Connect by signing in |
API key (bk_*) | Scripts, cron jobs, agents that run without you | This page |
Signing in uses OAuth 2.0 with PKCE. The app registers itself (Client ID Metadata Document or Dynamic Client Registration), so there is nothing to set up on your side. The token it gets works only for the server you connected, with the permissions you accepted.
Generate a key
- Go to /console/keys
- Click Create Key
- Name it (e.g.
claude-desktop,cursor-laptop) - Copy the key — it starts with
bk_and is shown once
Use it
{
"mcpServers": {
"betterness": {
"url": "https://api.betterness.ai/mcp",
"headers": {
"Authorization": "Bearer bk_your_api_key_here"
}
}
}
}
Scopes
A key can be narrowed to the same permissions an app asks for when it signs in. A key with no permissions selected holds all of them, and a key can carry an expiry date.
Rotation
Generate a new key, update your config, then revoke the old one. The two coexist briefly so you don't lose access between rotations.
What happens on a 401
| Cause | Fix |
|---|---|
| An app you signed in with was disconnected in Connected apps | Connect it again and sign in |
Missing Authorization header | Confirm the JSON config has the headers block |
| Expired or revoked key | Generate a new one in the Console |
Wrong format (e.g. dropped Bearer) | Header value must be Bearer bk_... |
What happens on a 403
Authenticated but missing the tool's permission. An app connected by signing in can ask you for the missing permission and connect again. For a key, create one with that scope.

