Skip to main content
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.

​
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

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

​
3. Set the env var Claude Code will inherit

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

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, 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:

​
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