Skip to main content

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.

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 — 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: 
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: 
"command": "kataven-mcp"
with the absolute path: 
"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 → 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 instead. See Security § Endpoints intentionally not exposed.

​
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.

​
”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 — 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: 
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 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. 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 — start-of-doc sanity checks.
  • Security — risk model + key revocation.
  • Tunneling — for tunnel-specific issues.