Skip to main content

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.

ChatGPT, unlike Codex CLI, doesn’t have a shell. To let it manage your Kataven account, connect it to the Kataven MCP server, which exposes every Hub API verb as a tool ChatGPT can call directly. Two integration paths, depending on where you’re using ChatGPT:
WherePath
ChatGPT DesktopMCP — point its config at a local kataven-mcp process
OpenAI Agents SDK (programmatic)MCP — register the Kataven MCP source in your agent
If you’re using Codex CLI (terminal coding agent with a shell), use the SDK directly — no MCP. See Manage with Codex.

​
1. Mint an API key

hub.kataven.ai/settings → API Keys tab → Create API key. Suggested name: chatgpt-desktop or openai-agents-prod. Copy the sk_live_… value — it shows once.

​
2. Install the MCP server

pip install kataven-mcp
Verify it runs over stdio (Ctrl-C to exit): 
KATAVEN_API_KEY=sk_live_acme_... kataven-mcp

​
3a. Wire up ChatGPT Desktop

ChatGPT Desktop reads MCP servers from a config file. The exact path varies by ChatGPT version — consult OpenAI’s current MCP documentation. The Kataven server entry looks the same everywhere: 
{
  "mcpServers": {
    "kataven": {
      "command": "kataven-mcp",
      "env": {
        "KATAVEN_API_KEY": "sk_live_acme_..."
      }
    }
  }
}
Restart ChatGPT Desktop. Kataven tools (kataven_list_agents, kataven_create_agent, kataven_originate_call, …) appear in the tool picker.
MCP support in ChatGPT clients is evolving. If your ChatGPT build doesn’t expose MCP, fall back to the OpenAI Agents SDK path below — it’s been stable since the Agents SDK launched.

​
3b. Wire up the OpenAI Agents SDK (programmatic)

If you’re building your own agent that uses ChatGPT-style models, register Kataven MCP as a tool source: 
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

kataven_mcp = MCPServerStdio(
    params={
        "command": "kataven-mcp",
        "env": {"KATAVEN_API_KEY": "sk_live_acme_..."},
    }
)

agent = Agent(
    name="Ops",
    instructions="You manage the Kataven voice platform on the user's behalf.",
    mcp_servers=[kataven_mcp],
)

result = Runner.run_sync(agent, "Pause every running campaign so I can deploy.")
print(result.final_output)
The model sees rich JSON-Schema for each Kataven tool’s arguments and fills in fields itself — you don’t write API code.

​
4. Try a few prompts

Show me all my agents and which phone numbers point to them.
ChatGPT calls kataven_list_agents, then kataven_list_phone_numbers, joins them, presents a table.
Create a “Tier 2 Support” agent with a friendlier tone than the existing “Support” agent.
ChatGPT reads kataven_get_agent for Support, derives a revised prompt, calls kataven_create_agent.
Place a test call from +12025550123 to my cell using the Front Desk agent.
ChatGPT calls kataven_originate_call with your inputs.

​
Verify what ChatGPT did

What changedOpen in Hub UI
Agentshub.kataven.ai/agents
Prompts, playbooks, FAQshub.kataven.ai/knowledge
Phone numbershub.kataven.ai/phone-numbers
Live or recent callshub.kataven.ai/conversations
Campaign progresshub.kataven.ai/campaigns
Tools, integrationshub.kataven.ai/tools, hub.kataven.ai/store

​
Risk + permissions

Every tool call hits the same sk_live_ key — meaning ChatGPT has full account scope. Treat the key the same way you’d treat a CI deploy key. To restrict blast radius:
  • Mint a separate key per use case at hub.kataven.ai/settings → API Keys. Rotate when you stop using a particular client.
  • Set per-tenant cost caps so a runaway loop can’t drain your balance — view at hub.kataven.ai/settings → Limits.
  • Confirm risky tool calls (kataven_originate_call, kataven_start_campaign, kataven_delete_*) before letting ChatGPT run them.

​
Troubleshooting

Tools don’t appear. ChatGPT didn’t load the MCP config — restart the app after editing the config, and check the developer console / log if your build exposes it. Verify kataven-mcp is on $PATH for the GUI app’s environment. 401 inside a tool result. The KATAVEN_API_KEY in the config is wrong or revoked. Mint a new one at hub.kataven.ai/settings → API Keys. 403 on a write tool. Cost-cap edits, integration authoring, and recording deletion require a Hub UI session — sk_live_ callers get 403. The MCP server doesn’t expose them at all. Calls succeed but ChatGPT doesn’t see results. Some chat surfaces strip structured tool results before the model sees them. Use the Agents SDK path (§3b) if you need reliable parsing.

​
What’s next