MCP Authentication

The rule

The MCP server requires bk_* API keys for auth. Auth0 JWTs fail on async dispatch and are not accepted. This is intentional — keys are scoped, rotatable, and cleanly mapped to consent grants.

Generate a key

1. Go to /console/keys
2. Click Create Key
3. Name it (e.g. claude-desktop, cursor-laptop)
4. 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 & consent

Each key carries a default scope set, and additional consent grants can narrow or widen access per data category. Manage from the Console:

• Scopes — the categories (biomarkers, wearables, profile, etc.) the key is allowed to read or write
• Grants — explicit per-tool authorizations, revocable individually

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
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 unauthorized. The key lacks scope for that tool — open the key in the Console and add the scope, or generate a wider-scope key.