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 — that uses MCP.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.
1. Mint an API key
Open 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
3. Set the env var Claude Code will inherit
~/.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.
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.4. Launch Claude Code and ask
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, 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 togpt-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-v1and clone it into a new agentfront-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 |
| Prompts / playbooks / FAQs | hub.kataven.ai/knowledge |
| Tools, integrations | hub.kataven.ai/tools, hub.kataven.ai/store |
| Phone numbers wired up | hub.kataven.ai/phone-numbers |
| Live conversation (after a test call) | hub.kataven.ai/conversations |
| Campaign metrics | 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 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 for the specific account, OR
- Use the MCP path 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.
429 Too Many Requests / “cost cap exceeded” — your account hit a per-tenant outbound cap. View limits at 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 — the MCP path for chat-only Claude.
- Python SDK reference — what Claude is reading when it figures out what’s possible.
- Your first agent — the same end-to-end flow if you want to do it yourself.