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.

Claude Desktop is the chat-only Claude app — no shell. To let it drive Kataven, install the Kataven MCP server, which exposes every Hub API verb as a tool Claude can call directly from chat. If you’re using Claude Code (terminal coding agent with a shell), use the SDK directly — see Manage with Claude Code. The MCP server isn’t needed there.

​
1. Mint an API key

hub.kataven.ai/settings → API Keys tab → Create API key. Suggested name: claude-desktop. 90-day expiry is fine for a personal-machine key. Copy the sk_live_… value — it shows once.

​
2. Install the MCP server

pip install kataven-mcp
Verify it runs over stdio (Ctrl-C to exit): 
KATAVEN_API_KEY=sk_live_acme_... kataven-mcp

​
3. Wire it into Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Add a kataven entry under mcpServers: 
{
  "mcpServers": {
    "kataven": {
      "command": "kataven-mcp",
      "env": {
        "KATAVEN_API_KEY": "sk_live_acme_..."
      }
    }
  }
}
Restart Claude Desktop. The Kataven tools (kataven_list_agents, kataven_create_agent, kataven_originate_call, …) appear in Claude’s tool picker. You’ll see a 🔧 icon next to messages where Claude calls one.
If the tools don’t appear, check Claude Desktop’s MCP logs (Help → Check for Updates → Developer Tools → Console). Most issues are JSON syntax errors in the config or the kataven-mcp binary not being on $PATH for the GUI app’s environment. Try command: "/usr/local/bin/kataven-mcp" (or which kataven-mcp to find the absolute path) if the bare name doesn’t resolve.

​
4. Wire it into Cursor (same shape)

Cursor uses the same MCP protocol. Edit ~/.cursor/mcp.json: 
{
  "mcpServers": {
    "kataven": {
      "command": "kataven-mcp",
      "env": {
        "KATAVEN_API_KEY": "sk_live_acme_..."
      }
    }
  }
}
Restart Cursor. Tools appear in chat and composer.

​
5. Ask Claude to do something

Open a new conversation in Claude Desktop and try:
Show me all phone numbers I’ve registered, and tell me which ones aren’t pinned to an agent.
Claude calls kataven_list_phone_numbers + kataven_list_agents, joins them, and answers.
Create an agent called “Front Desk” with a friendly greeting, then attach the general-faqs playbook to it.
Claude chains kataven_create_agent → kataven_attach_playbook.
Place a test call from +12025550123 to my cell +14155550100 using the Front Desk agent.
Claude calls kataven_originate_call and returns the live transcript link.

​
Verify what Claude did

What changedOpen in Hub UI
Agentshub.kataven.ai/agents
Prompts / playbooks / FAQshub.kataven.ai/knowledge
Phone numbershub.kataven.ai/phone-numbers
Live or recent callshub.kataven.ai/conversations
Campaign progresshub.kataven.ai/campaigns
Tools / integrationshub.kataven.ai/tools, hub.kataven.ai/store

​
Risk + permissions

Every MCP tool call uses your sk_live_ key — Claude has full account scope. Treat the key like a CI deploy key. To limit blast radius:
  • Mint a separate key per use case at hub.kataven.ai/settings → API Keys. Rotate when you stop using a particular tool.
  • Set per-tenant cost caps so a runaway loop can’t drain your balance. View / edit at hub.kataven.ai/settings → Limits tab (note: editing requires a Hub UI session, not sk_live_).
  • Confirm risky tool calls (kataven_originate_call, kataven_start_campaign, kataven_delete_*) before letting Claude run them. Claude Desktop asks by default for write tools.

​
Troubleshooting

Tools don’t appear in Claude. Check the JSON syntax of claude_desktop_config.json (a missing comma silently disables the file) and that kataven-mcp is reachable. Restart the app after every config change. 401 inside a tool result. The KATAVEN_API_KEY in the config is wrong, expired, or revoked. Mint a new one at hub.kataven.ai/settings → API Keys. 403 on a write tool. A few admin endpoints (cost caps, integration authoring, recording deletion) reject sk_live_ callers by design. The MCP server doesn’t expose them — if you see a 403, it’s coming from the server. Calls succeed but Claude doesn’t see results. Some chat surfaces strip structured tool results before the model sees them. If this is consistent, switch to the OpenAI Agents SDK programmatic path for that workflow — same MCP server, more reliable result parsing.

​
What’s next