MCP Troubleshooting
Why your tool calls fail and how to fix them.
"Unable to process redirect callback" while signing in
The sign-in took too long or was sent twice, so its one-time session is spent. Close the page and start the connection again from the app.
"This app was disconnected"
The app was disconnected in Connected apps. Connect it again from the app and sign in.
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)
- Check the URL:
https://api.betterness.ai/mcpfor members,https://api.betterness.one/mcpfor Betterness One. Abk_*key works only on the first, abko_*key only on the second.
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
Authorizationheader — confirm the JSON config has theheadersblock - Wrong format — header value must be
Bearer bk_...(notbk_...alone) - Expired or revoked key — generate a new one in the Console
HTTP 403 Forbidden
The app or key lacks the tool's permission. An app connected by signing in can ask for it and connect again; for a key, create one with that scope.
Tool returns empty
| Tool | Likely cause |
|---|---|
Health data tools (getActivityData, getSleepData, 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 can't be connected from the assistant
generateLinkToken doesn't support Apple Health. The member connects it in the Betterness iOS app, under Settings → Wearables.
A tool answers "rate limit exceeded"
The member's per-minute limit for that tool, or the hourly limit across all tools, was reached. The call comes back as a tool error, not an HTTP 429. Wait a minute and retry, and avoid calling the same tool in a tight loop. See Limits & scopes.
confirm_action answers stale
The price or the appointment changed after the preview. Prepare the action again and show the user the new preview.
Client logs / debug
| Client | Where to look |
|---|---|
| Claude Desktop | Settings → Developer → Logs |
| Claude Code | Run with --debug, or /mcp for each server's status |
| Cursor | Output panel → MCP |
| Windsurf | Output panel → MCP |
Need more help?
- Limits & scopes
- Support:
support@betterness.ai

