Skip to main content
View as Markdown

MCP Troubleshooting

The handful of things that go wrong, and what fixes them.

My client says the server is unauthorised​

  • The header must read exactly Authorization: Bearer kx_mcp_… — the word Bearer, one space, then the key.
  • Check for a trailing space or newline from copy-paste.
  • Confirm the key is still active in Settings → General → MCP Connection, and has not expired.

Tools are listed, but every call fails or times out​

This is the signature of the extension not being reachable. tools/list is answered by the server alone, so it works regardless; real calls need your browser.

  • Is Chrome running? Minimised is fine; quit is not.
  • Is the Kortex extension enabled and signed in to the same account?
  • Ask your assistant to call get_status — it reports the connection state directly.
  • Open the Kortex popup once. That wakes the extension immediately.

The first call takes forever, then everything is fast​

Expected. Chrome suspends idle extensions, and Kortex can take up to 30 seconds to wake. Only the first call of a session pays it. If your client has a short tool timeout, raise it to at least 60 seconds.

The assistant says a tool does not exist​

Your key's profile is filtering it out. A read-only key genuinely does not see write tools — this is the design, not a bug. Generate a Standard key if the assistant needs to make changes, and check you did not deny that tool by name.

It is working on the wrong Google account​

Ask for list_accounts, then tell your assistant to pass that email as the account argument. Tool calls never change the account selected in your dashboard, so the two can differ.

"Rate limit exceeded"​

60 calls per minute per key, 120 per minute across all your keys. The error says how long to wait. If an agent is looping, stop it — the limit is protecting you from it.

Claude Desktop shows no Kortex tools​

  • Node.js must be installed, since the config runs npx mcp-remote.
  • The JSON must be valid — a stray trailing comma silently disables the whole file.
  • Fully quit and reopen Claude Desktop; closing the window is not enough.
  • Check Claude Desktop's MCP log for the kortex server's startup output.

Answers come back without citations​

Pass the session_id from the first ask_question back on follow-ups. Without it each question starts a fresh conversation, and Gemini Notebook has less to ground against. If a source is still being ingested, is_source_ready will say so.

Still stuck​

Include the tool name, the exact error text and the output of get_status when you contact support. Those three things resolve most reports on the first reply.