MCP Troubleshooting

Why your tool calls fail and how to fix them.

Client never lists Betterness tools

Restart the client after editing config — most clients only reload MCP servers on launch
Confirm the JSON is valid (a stray comma will silently disable the entry)
Run betterness mcp status --json to see what the CLI thinks is configured

HTTP 400 with a transport error

The Betterness MCP server speaks Stateless HTTP. If your client config has a transport field, set it to "http". Most modern clients pick this by default.

HTTP 401 Unauthorized

Missing Authorization header — confirm the JSON config has the headers block
Wrong format — header value must be Bearer bk_... (not bk_... alone)
Expired or revoked key — generate a new one in the Console

HTTP 403 Forbidden

The key is authenticated but lacks scope for that tool. Open the key in the Console and add the relevant scope, or generate a wider-scope key.

Tool returns empty

Tool	Likely cause
Health data tools (`getActivity`, `getSleep`, `getVitals`, `getBodyComposition`)	No relevant wearable connected — call `listConnectedDevices`
`searchBiomarkers`	No approved lab results yet — check `getUserLabRecords` for any in PROCESSED status awaiting approval
`getBiologicalAge`	Same — needs approved lab results to calculate

Lab order stuck in "Paid"

Auto-init failed because profile was incomplete. Fix profile, then call initializeLabOrder.

generateLinkToken errors with "already connected"

The user already has that integration. Disconnect first with disconnectIntegration, or use a different provider.

Apple Health returns "use generateAppleHealthCode"

generateLinkToken doesn't support Apple Health. Switch to generateAppleHealthCode.

HTTP 429 Too Many Requests

Rate limit hit. Free tier: 100/day. Builder: 5,000/day. Backoff and retry, or upgrade.

Client logs / debug

Client	Where to look
Claude Desktop	Settings → Developer → Logs
Claude Code	Run with `--debug-mcp` flag
Cursor	Output panel → MCP
Windsurf	Output panel → MCP

Need more help?

SmartListings