Troubleshooting
Diagnose credentials, protocol errors and endpoint timeouts without guessing.
Authentication fails
- Check /v1/me using the exact key and bearer header your integration sends.
- Ask the operator to check expiry, revocation and scopes. Never share the complete key in support logs.
- A 403 from browser code can mean the Origin header was rejected. Use a server-side integration.
- An MCP authentication failure may also reflect its upstream API being unavailable; check both health endpoints.
MCP connection fails
Use https://mcp.recursift.app/mcp, not the root hostname or an email address. GET returns 405 by design; use a Streamable HTTP client with POST and Accept: application/json, text/event-stream. A client that only supports OAuth cannot use the key-only sign-in flow.
For stdio, use an absolute binary path, supply RECURSIFT_API_KEY, and leave MCP_TRANSPORT unset. Keep diagnostic output off stdout.
A query is pending or timed out
Check that the selected endpoint is enrolled, recently seen and able to poll the control plane. Check its configured model locally. Poll the existing query ID; submitting the same question again through MCP creates another job. A timed-out endpoint is unknown, not clean.
No findings from /findings may simply mean the job has not been retrieved/materialized yet. GET /queries/{id} first. A missing stored summary is not a negative hunt result.
Check service health
curl --fail-with-body https://api.recursift.app/health
curl --fail-with-body https://mcp.recursift.app/healthBoth return HTTP 200 when their respective health checks pass. MCP health is process liveness; it does not prove that an endpoint or its model can answer. API health checks its database connection.