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

# Manage Kataven with Claude Desktop — MCP integration

> Wire the Kataven MCP server into Claude Desktop or Cursor and let Claude manage voice agents, run campaigns, and place test calls — all from chat.

[Claude Desktop](https://claude.ai/download) 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](/guides/manage-with-claude-code). The MCP server isn't needed there.

## 1. Mint an API key

[hub.kataven.ai/settings](https://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

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

Verify it runs over stdio (Ctrl-C to exit):

```bash theme={null}
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`:

```json theme={null}
{
  "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.

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

## 4. Wire it into Cursor (same shape)

Cursor uses the same MCP protocol. Edit `~/.cursor/mcp.json`:

```json theme={null}
{
  "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 changed               | Open in Hub UI                                                                                             |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Agents                     | [hub.kataven.ai/agents](https://hub.kataven.ai/agents)                                                     |
| Prompts / playbooks / FAQs | [hub.kataven.ai/knowledge](https://hub.kataven.ai/knowledge)                                               |
| Phone numbers              | [hub.kataven.ai/phone-numbers](https://hub.kataven.ai/phone-numbers)                                       |
| Live or recent calls       | [hub.kataven.ai/conversations](https://hub.kataven.ai/conversations)                                       |
| Campaign progress          | [hub.kataven.ai/campaigns](https://hub.kataven.ai/campaigns)                                               |
| Tools / integrations       | [hub.kataven.ai/tools](https://hub.kataven.ai/tools), [hub.kataven.ai/store](https://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](https://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](https://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](https://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](/guides/manage-with-chatgpt#openai-agents-sdk) for that workflow — same MCP server, more reliable result parsing.

## What's next

* [Manage with Claude Code](/guides/manage-with-claude-code) — the SDK path if you want a shell.
* [MCP Server reference](/sdks/mcp/overview) — every tool the server exposes.
* [Python SDK reference](/sdks/python/overview) — the underlying API the MCP server wraps.