Troubleshooting

MCP connection

Claude Desktop doesn’t show “oka” in the MCP status bar

Fully quit and reopen Claude Desktop (not just close the window).
Confirm your claude_desktop_config.json is valid JSON — a trailing comma will silently break it.
Run the server manually to see errors:
Terminal window
```
OKA_API_KEY=sk_... npx -y @oka-core/reason
```
Make sure you’re using @oka-core/reason (not @oka/reason — the package was renamed to avoid an npm name collision).

Tools don’t appear in Claude Code or Cursor

Each MCP client stores its config in a different location. Verify the mcpServers block is in the right file for your client and that the command / args match the getting started guide.

API keys

`401 Unauthorized`

Confirm the Authorization: Bearer <token> header is set.
Check that the key hasn’t been revoked — you can view active keys in app.oka.so under Settings → API keys.
Prod and dev environments use separate keys. A prod key won’t work against reason.dev.oka.so and vice versa.

Using Reason

`observe` succeeds but `context` returns nothing

Both calls must target the same workspace. If you omit the workspace flag, Reason defaults to the current working directory — make sure the write and read happen from the same project.

Learnings aren’t appearing yet

Consolidation runs periodically in the background. Freshly written events may take a few minutes to be distilled into queryable learnings. Raw events are available immediately via semantic_search.

Billing limits

`402 plan_limit_exceeded`

Your plan’s monthly allowance for that meter (model tokens, API calls, or knowledge searches) is exhausted. The response says which limit you hit and where you stand:

{
  "error": "plan_limit_exceeded",
  "limit_type": "api_calls",
  "current_usage": 10000,
  "max_allowed": 10000
}

Retrying won’t help until the billing period resets. Upgrade from the dashboard for an immediate, prorated limit increase. See Usage, plans & limits for how metering works. Storage never returns 402 — it’s a soft cap billed as overage.

Rate limits

`429 Too Many Requests`

The response includes Retry-After and X-RateLimit-Reset headers — back off and retry after the indicated time. If you consistently hit limits, reach out to discuss a higher ceiling.

Need help?

Email us at support@oka.so or open a conversation at oka.so. Including the X-Request-Id header value from the failing response helps us diagnose faster.