> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kataven MCP — troubleshooting

> Tools don't appear, 401 errors, 403 errors, tool-cap warnings, tunnel disconnects — every common Kataven MCP failure mode and the fix.

Every common failure mode and what to do about it. Find your symptom, read the fix.

## "The Kataven tools don't appear in my AI app."

Nine times out of ten, one of these three things:

### 1. JSON syntax error in the config file

A missing comma quietly disables most config files. Paste your file contents into [jsonlint.com](https://jsonlint.com/) — it'll point at the line.

Common mistakes:

* Trailing comma after the last entry: `{ "kataven": {...}, }` ← invalid in standard JSON.
* Missing comma between two `mcpServers` entries.
* Smart quotes from a word processor: `"kataven"` (curly) vs `"kataven"` (straight).

### 2. `kataven-mcp` not on the PATH the GUI app sees

GUI apps don't always inherit your shell's `$PATH`. Test:

```bash theme={null}
which kataven-mcp     # macOS / Linux
where kataven-mcp     # Windows
```

The output is the absolute path, e.g. `/usr/local/bin/kataven-mcp` or `/Users/you/Library/Python/3.11/bin/kataven-mcp` or `C:\Users\you\AppData\Roaming\Python\Python311\Scripts\kataven-mcp.exe`.

In your config, replace:

```json theme={null}
"command": "kataven-mcp"
```

with the absolute path:

```json theme={null}
"command": "/Users/you/Library/Python/3.11/bin/kataven-mcp"
```

### 3. The app didn't fully restart

Most apps load MCP config at startup only. **Cmd+Q** (Mac) / Ctrl+Q (Linux) / right-click system tray → Exit (Windows) — then relaunch. Closing the window isn't enough; Claude Desktop, Cursor, ChatGPT all keep running in the background after window close.

## "401 Unauthorized" inside a tool result

The `KATAVEN_API_KEY` in your config is wrong, expired, or revoked.

1. Check the key's status at [hub.kataven.ai/settings](https://hub.kataven.ai/settings) → **API Keys**. If it shows as **Disabled** or expired, mint a new one.
2. Make sure the value in your config doesn't have stray whitespace or smart quotes.
3. Make sure your config copy starts with `sk_live_` not `sk_live_…` (literal ellipsis from copying a docs example).

## "403 Forbidden" on a write tool

Four endpoints intentionally reject `sk_live_` callers (cost caps, integration authoring, recording deletion, marketplace template creation). The MCP server doesn't expose them at all — if you see a `403`, it's coming from the server because the AI tried a path the spec marks as Hub-UI-only. Edit those at [hub.kataven.ai/settings](https://hub.kataven.ai/settings) instead. See [Security § Endpoints intentionally not exposed](/sdks/mcp/security#endpoints-intentionally-not-exposed-via-mcp).

## Cursor — "Tool limit reached"

Cursor caps active MCP tools at \~40 across all configured servers. Above the cap, Cursor silently loses access to extra tools.

Fix:

* Settings → **Cursor Settings** → **MCP** → disable MCP servers you don't need right now.
* Or scope kataven to a per-project `.cursor/mcp.json` if it's only relevant for one repo (so it's not loaded globally).

## Tunnel disconnects mid-conversation (ChatGPT / Claude.ai web / n8n)

Free ngrok URLs change between sessions and idle out after \~2 hours. Fix with one of:

* **Pin a paid ngrok subdomain:** `ngrok http --domain=kataven.your-handle.ngrok.app 8080`. URL stays the same across restarts.
* **Switch to Cloudflare Tunnel:** `cloudflared tunnel --url http://localhost:8080`. Stable URLs, free.
* **Switch to Tailscale Funnel** if your machine's already on Tailscale.

Full alternatives: [Tunneling § Stable URLs](/sdks/mcp/tunneling#stable-urls).

## "The AI runs the tool but doesn't seem to see the result"

Some chat surfaces drop or truncate structured tool-result payloads before the model reads them. Most common in:

* ChatGPT.com web with very long tool output (e.g. listing 100s of agents).
* Some n8n workflows with strict result-truncation settings.

Workarounds:

1. **Ask for a summary, not a dump.** *"How many agents do I have?"* instead of *"List every agent."*
2. **Switch to the [OpenAI Agents SDK programmatic path](/sdks/mcp/programmatic#openai-agents-sdk)** — stdio over the Agents SDK parses results reliably.
3. **For Cursor, Claude Desktop, JetBrains** the result-passing is solid; this issue is mostly browser-side ChatGPT.

## "Server failed to start"

The AI app launched `kataven-mcp` and got an error. Run the same command yourself in a terminal to see the actual stderr:

```bash theme={null}
KATAVEN_API_KEY=sk_live_acme_... kataven-mcp
```

Common causes:

* **`pip` installed kataven-mcp into a different Python than your shell uses.** Run `which python` and `which kataven-mcp`. If they point at different installations, reinstall via the same Python: `python -m pip install kataven-mcp`.
* **Python version too old.** kataven-mcp requires Python 3.10+. Check `python --version`. If you have 3.9 or older, install a newer Python (`brew install python` on macOS, [python.org](https://www.python.org/downloads/) on Windows).

## "401 Unauthorized" *outside* a tool (server itself can't reach api.kataven.ai)

The `kataven-mcp` server tried to authenticate with the Hub API and got rejected. Most likely:

* Your machine has no internet access.
* A corporate proxy is intercepting HTTPS to `api.kataven.ai`. Set `HTTPS_PROXY=https://your-proxy:port` in the same env block as `KATAVEN_API_KEY`.

## Cursor / VS Code agent picks the wrong tool

The Kataven MCP exposes \~40+ tools; LLMs sometimes confuse `kataven_list_agents` with `kataven_list_tools`. Mitigations:

* Be specific in prompts: *"List the agents (kataven\_list\_agents)."*
* Disable other MCP servers temporarily so the active tool catalog is smaller.
* For agent-mode IDEs, re-prompt after a wrong tool fires — Cursor/Copilot self-correct on the second iteration most of the time.

## Still stuck?

Email [support@kataven.ai](mailto:support@kataven.ai). Include:

* The AI app name + version (e.g. *"Claude Desktop 0.10.4 on macOS 15.2"*).
* The exact error text — copy from the AI app's console or a tool-result inline if you can.
* The failing prompt and which tool the AI was trying to call (`kataven_*`).
* A redacted version of your `mcpServers` config (omit the `KATAVEN_API_KEY` value).

## See also

* [Install](/sdks/mcp/install) — start-of-doc sanity checks.
* [Security](/sdks/mcp/security) — risk model + key revocation.
* [Tunneling](/sdks/mcp/tunneling) — for tunnel-specific issues.