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

# Install the Kataven MCP server — pip, API key, universal config

> Install kataven-mcp via pip, mint an sk_live_ API key, and copy the universal MCP server JSON entry that every AI client accepts.

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](/sdks/mcp/overview#two-ways-mcp-clients-connect) is mechanical.

## 1. Install `kataven-mcp`

```bash theme={null}
pip install kataven-mcp
```

Requires Python 3.10+. If you don't have Python:

* **macOS:** `brew install python`
* **Windows:** [python.org/downloads](https://www.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`:

```bash theme={null}
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](https://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.**

<Note>
  `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.
</Note>

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

```json theme={null}
{
  "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 →](/sdks/mcp/clients/zed)).
* **VS Code** uses `servers` instead of `mcpServers`, and the file is `mcp.json` ([VS Code setup →](/sdks/mcp/clients/vs-code)).

Remote-only clients (ChatGPT, Claude.ai web, n8n) need a different shape — see [Tunneling](/sdks/mcp/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](/authentication) and [Security](/sdks/mcp/security).

## Next: pick your client

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

* 🟢 **Direct stdio** — [Claude Desktop](/sdks/mcp/clients/claude-desktop), [Cursor](/sdks/mcp/clients/cursor), [Windsurf](/sdks/mcp/clients/windsurf), [Zed](/sdks/mcp/clients/zed), [VS Code](/sdks/mcp/clients/vs-code), [JetBrains](/sdks/mcp/clients/jetbrains), [Warp](/sdks/mcp/clients/warp), [Goose](/sdks/mcp/clients/goose), [Raycast](/sdks/mcp/clients/raycast)
* 🟡 **Remote (needs tunnel)** — [ChatGPT](/sdks/mcp/clients/chatgpt), [Claude.ai web](/sdks/mcp/clients/claude-web), [n8n](/sdks/mcp/clients/n8n)
* ⚙️ **Programmatic** — [OpenAI Agents SDK / LangGraph / Agno / AutoGen](/sdks/mcp/programmatic)