Codex CLI is OpenAI’s terminal coding agent. Like Claude Code, it has a shell — so the cleanest way to manage Kataven is to install the Python SDK and let Codex write the calls itself. No MCP server required for this path. If you want to drive Kataven from chat-only ChatGPT (Desktop or Web), see Manage with ChatGPT — 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
hub.kataven.ai/settings → API Keys tab → Create API key. Suggested name:codex-local. Copy the sk_live_… value — it shows once.
2. Install the SDK
npm install @kataven/server) if you’d rather Codex write TypeScript.
3. Set the env var Codex will inherit
~/.zshrc / ~/.bashrc so every Codex session has it. The SDK reads the env var automatically — Codex doesn’t need to know the value.
KATAVEN_ACCOUNT_ID is not required when KATAVEN_API_KEY starts with sk_live_ — the account is in the prefix.4. Launch Codex 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.
Codex reads the Python SDK overview, writes the script, runs it, and reports back.
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. Pause it immediately so I can review before going live.” - “Take the prompt from agent
front-desk-v1and clone it intofront-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 Codex did
| What changed | Check it at |
|---|---|
| Agents | hub.kataven.ai/agents |
| Prompts, playbooks, FAQs | hub.kataven.ai/knowledge |
| Phone numbers | hub.kataven.ai/phone-numbers |
| Live or recent calls | hub.kataven.ai/conversations |
| Campaign progress | hub.kataven.ai/campaigns |
| Tools, integrations | hub.kataven.ai/tools, hub.kataven.ai/store |
Why no MCP for Codex?
Codex can spawn processes (python -c "…", write & run files). Anything the SDK can do, Codex can do directly. MCP is only useful when the AI tool cannot spawn processes — Claude Desktop, ChatGPT Desktop, n8n nodes, etc.
Sandbox / approval mode
We strongly recommend running Codex with 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. Codex’s --full-auto mode will happily place outbound calls without asking — only enable it on a disposable account.
Troubleshooting
401 Unauthorized — KATAVEN_API_KEY isn’t set in the shell Codex is using. Run echo $KATAVEN_API_KEY from inside Codex before retrying.
“Account not found” — you’re using a Zitadel JWT instead of an sk_live_ key, and KATAVEN_ACCOUNT_ID isn’t set. Easier path: mint an sk_live_ key (step 1).
403 Forbidden on POST /api/v1/api-keys or admin endpoints — sk_live_ keys can’t manage other keys, mint integrations, or set cost caps. Those routes require a Hub UI session.
429 Too Many Requests — per-tenant cost cap exceeded. View limits at hub.kataven.ai/settings → Limits tab.
What’s next
- Manage with ChatGPT — the MCP path for chat-only ChatGPT.
- Manage with Claude Code — the same flow with Anthropic’s terminal agent.
- Python SDK reference — what Codex reads when it figures out what’s possible.