> ## 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 Code — voice AI from the terminal

> Use Anthropic's Claude Code CLI to create voice agents, configure phone numbers, and run outbound campaigns. Claude writes the Python; you watch it run.

[Claude Code](https://www.anthropic.com/claude-code) is Anthropic's terminal coding agent. Because it has a shell, the cleanest way to manage Kataven is to install the Python SDK and let Claude write & run the calls itself. **No MCP server required for this path.**

If you want to drive Kataven from chat-only Claude (Desktop, mobile, web), see [Manage with Claude Desktop](/guides/manage-with-claude-desktop) — that uses MCP.

## 1. Mint an API key

Open [hub.kataven.ai/settings](https://hub.kataven.ai/settings) → **API Keys** tab → **Create API key**.

Suggested name: `claude-code-local`. Pick an expiry (90 days is a good default for a workstation key). Click **Create** and **copy the `sk_live_…` token** — it only displays once.

## 2. Install the SDK

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

(SDK targets Python 3.10+. The MCP server isn't needed for Claude Code.)

## 3. Set the env var Claude Code will inherit

```bash theme={null}
export KATAVEN_API_KEY="sk_live_acme_..."
```

Add it to your `~/.zshrc` / `~/.bashrc` so every Claude Code session picks it up. The SDK reads `KATAVEN_API_KEY` automatically — Claude doesn't need to know the value.

<Note>
  `sk_live_` keys self-identify the account in their prefix, so `KATAVEN_ACCOUNT_ID` is **not** required. Only set it if you're testing with a Zitadel JWT.
</Note>

## 4. Launch Claude Code and ask

```bash theme={null}
claude
```

Then type:

> List all my agents and tell me which ones are pinned to a phone number. Then create a new "Sales SDR" agent with a friendly tone and attach the `general-faqs` playbook.

Claude reads the [Python SDK overview](/sdks/python/overview), writes a script, runs it, and reports back. You can ask follow-ups in plain English.

## Prompts that work well

* *"Show me every agent and its current model. If any are still on `gpt-3.5`, upgrade them to `gpt-4o-mini`."*
* *"I just uploaded a CSV of leads at `~/leads.csv`. Create an outbound campaign called 'Spring Q2 push' targeting them, but pause it immediately so I can review before going live."*
* *"Take the prompt from agent `front-desk-v1` and clone it into a new agent `front-desk-v2-experimental`. Don't attach any tools yet."*
* *"Place a test call from my main number to my cell using the Front Desk agent. Then show me the live transcript link."*

## Verify what Claude did

After Claude runs, sanity-check in the dashboard. Each link below opens the exact page where the change is visible:

| What changed                          | Check it at                                                                                                |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Agents created/edited                 | [hub.kataven.ai/agents](https://hub.kataven.ai/agents)                                                     |
| Prompts / playbooks / FAQs            | [hub.kataven.ai/knowledge](https://hub.kataven.ai/knowledge)                                               |
| Tools, integrations                   | [hub.kataven.ai/tools](https://hub.kataven.ai/tools), [hub.kataven.ai/store](https://hub.kataven.ai/store) |
| Phone numbers wired up                | [hub.kataven.ai/phone-numbers](https://hub.kataven.ai/phone-numbers)                                       |
| Live conversation (after a test call) | [hub.kataven.ai/conversations](https://hub.kataven.ai/conversations)                                       |
| Campaign metrics                      | [hub.kataven.ai/campaigns](https://hub.kataven.ai/campaigns)                                               |

## Why no MCP for Claude Code?

Claude Code can spawn processes (`python -c "…"`, write & run files). Anything the SDK can do, Claude can do directly. MCP is only useful when the AI tool **can't** spawn processes — Claude Desktop, ChatGPT Desktop, etc. See [Manage with Claude Desktop](/guides/manage-with-claude-desktop) for that flow.

## Sandbox / approval mode

We strongly recommend running Claude Code with the default approval prompts on for write operations. Reads (`agents.list`, `campaigns.list`) are safe to auto-approve; mutations (`agents.create`, `campaigns.start`, `calls.originate`) should require a click. Claude Code's `--dangerously-skip-permissions` flag skips this gate — only enable it on a disposable account.

For long-running automation where you don't want to approve each call, either:

* Mint a [scoped key](/authentication#mint-list-revoke-api-keys) for the specific account, OR
* Use the [MCP path](/guides/manage-with-claude-desktop) with read-only tools surfaced and write tools omitted.

## Troubleshooting

**`401 Unauthorized`** — `KATAVEN_API_KEY` isn't visible to the shell Claude Code is using. Run `echo $KATAVEN_API_KEY` from inside Claude Code before retrying.

**`403 Forbidden`** on `POST /api/v1/api-keys` or similar — `sk_live_` keys can't manage other keys, mint integrations, or set cost caps. Those routes require a Hub UI session. See [Authentication § Mint, list, revoke API keys](/authentication).

**`429 Too Many Requests` / "cost cap exceeded"** — your account hit a per-tenant outbound cap. View limits at [hub.kataven.ai/settings](https://hub.kataven.ai/settings) → **Limits** tab.

**Claude pauses and asks before each call** — that's the default; toggle in your Claude Code settings if you want broader auto-approve.

## What's next

* [Manage with Claude Desktop](/guides/manage-with-claude-desktop) — the MCP path for chat-only Claude.
* [Python SDK reference](/sdks/python/overview) — what Claude is reading when it figures out what's possible.
* [Your first agent](/guides/your-first-agent) — the same end-to-end flow if you want to do it yourself.