Skip to main content
Three things every AI client needs: the binary on your machine, a Kataven API key, and the universal JSON entry. Once you have all three, picking a client guide is mechanical.

​
1. Install kataven-mcp

pip install kataven-mcp
Requires Python 3.10+. If you don’t have Python:
  • macOS: brew install python
  • Windows: python.org/downloads — install the latest 3.x and check “Add Python to PATH” during install
  • Linux: Use your distro’s package manager (e.g. apt install python3 python3-pip)
Verify the binary is on your $PATH: 
kataven-mcp --help
which kataven-mcp     # macOS / Linux
where kataven-mcp     # Windows
The path it prints (e.g. /usr/local/bin/kataven-mcp, /Users/you/Library/Python/3.11/bin/kataven-mcp) is what some GUI apps need if they don’t inherit your shell’s PATH.

​
2. Mint an API key

hub.kataven.ai/settings → API Keys tab → Create API key. Suggested naming convention: name the key after the AI app you’ll use it from — claude-desktop-laptop, cursor-work, team-zapier, chatgpt-personal. Makes rotation easier when you stop using a particular tool. Pick an expiry. 90 days is a good default for a workstation key; 1 year for a team-shared key in a vault. Click Create, copy the sk_live_… value — it shows once.
sk_live_ keys self-identify the account in their prefix, so KATAVEN_ACCOUNT_ID is not needed in your MCP config. Only set it if you’re testing with a Zitadel JWT.

​
3. The universal MCP server entry

Every direct-stdio client accepts this exact JSON shape. Memorize it once; the only thing that changes per app is where the file lives or which UI button opens it. 
{
  "mcpServers": {
    "kataven": {
      "command": "kataven-mcp",
      "env": { "KATAVEN_API_KEY": "sk_live_acme_..." }
    }
  }
}
Two clients use slightly different shapes — covered in their pages:
  • Zed uses context_servers instead of mcpServers (Zed setup →).
  • VS Code uses servers instead of mcpServers, and the file is mcp.json (VS Code setup →).
Remote-only clients (ChatGPT, Claude.ai web, n8n) need a different shape — see Tunneling.

​
What gets exposed

Once the server is wired up, the AI sees rich JSON-Schema for each Kataven tool’s arguments. Every Hub API verb is reachable:
  • Agents — kataven_list_agents, kataven_get_agent, kataven_create_agent, kataven_update_agent, kataven_delete_agent, kataven_attach_playbook, kataven_detach_playbook, kataven_attach_faq, kataven_detach_faq
  • Tools + integrations — kataven_list_tools, kataven_create_tool, kataven_list_integrations, kataven_install_integration, kataven_uninstall_integration
  • Knowledge — kataven_list_playbooks, kataven_create_playbook, kataven_list_faqs, kataven_create_faq, …
  • Telephony — kataven_list_phone_numbers, kataven_create_phone_number, kataven_update_phone_number, kataven_list_telephony_providers, …
  • Calls — kataven_originate_call, kataven_get_recording
  • Campaigns — kataven_list_campaigns, kataven_create_campaign, kataven_start_campaign, kataven_pause_campaign, kataven_stop_campaign, …
  • Widget — kataven_list_widget_keys, kataven_create_widget_key, kataven_get_widget_settings, …
  • Marketplace — kataven_list_templates, kataven_install_template, …
A few admin endpoints intentionally don’t appear (POST /api/integrations, POST /api/marketplace/agents, PUT /api/v1/call-limits, DELETE /api/v1/sessions/{id}/recording). Those require a Hub UI session — see Authentication and Security.

​
Next: pick your client

Every client guide is one page, ~2 minutes to read end to end: