# 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](/docs/support). Those three things resolve most reports on the first reply.