Troubleshooting

401 Unauthorized

Your Bearer key is missing, malformed, or revoked.

• Confirm the header is exactly Authorization: Bearer mk_live_xxxx — note the space after "Bearer", and that the key starts with mk_live_.
• If you copy-pasted from a terminal, check for trailing whitespace or a wrapped newline.
• Re-issue at /account/keys if the key was rotated or revoked. Keys are shown once; we store only a bcrypt hash.

429 Too Many Requests

You hit a rate limit. Free-tier callers share a per-IP/day quota; paid-tier callers share a per-key/minute quota.

• Inspect the Retry-After header on the 429 — it's the seconds to wait before the next call.
• If you're scripting via the HTTP API, back off exponentially (1s → 2s → 4s, jitter) and respect Retry-After when present.
• See rate limits for tier quotas.

Empty results on a well-known target

Mosaic labels heuristic and partial layers honestly. A few tools will return an empty array on a target you'd expect to have coverage:

• mosaic_find_similar_targets requires the Foldseek structure index. Until the operator builds it, the tool returns an empty array with a hint in _provenance.note.
• find_resistance_bypass_map is gated on the literature-mined resistance relations (GLiREL pre-mid-2024 papers). Newer-than-coverage targets may return sparse results.
• Compound-level queries on targets with no approved drug often return empty — that's the correct answer; the graph is honest about absence.

MCP handshake hangs / no tools discovered

Your client connected but doesn't see Mosaic's tools. Common causes:

• The URL is /sse, not the bare host. Full URL: https://mcp.getmosaic.dev/sse.
• Claude Desktop caches the MCP manifest across restarts — after editing claude_desktop_config.json, fully quit (⌘Q on macOS) and reopen, not just close the window.
• In Claude Code, run /mcp to see connection status. If it shows "disconnected", verify the key with a curl probe (below).

Verify the key separately from the MCP handshake:

curl -sS https://api.getmosaic.dev/v1/health \
  -H "Authorization: Bearer mk_live_xxxx"

Expect 200 with a JSON body. A 401 here points at the key; anything else points at the client config.

Tool call times out

KG-native traversals are bounded but a few queries are expensive (multi-hop talent migration on a heavily-edged target). If a tool times out at 30s, narrow the request:

• Pass an explicit limit (most KG-native tools accept one; default is 20).
• For find_talent_migration, constrain by therapy area or year range.
• If timeouts persist, drop us a note at [email protected] with the exact tool name + parameters; some traversals are pre-materialised on a nightly cadence.