> ## 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 ChatGPT — MCP integration + OpenAI Agents SDK

> Drive Kataven from ChatGPT Desktop via MCP, or programmatically via the OpenAI Agents SDK. Build voice agents, run campaigns, and place calls from chat.

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:

| Where                                | Path                                                    |
| ------------------------------------ | ------------------------------------------------------- |
| **ChatGPT Desktop**                  | MCP — 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](/guides/manage-with-codex).

## 1. Mint an API key

[hub.kataven.ai/settings](https://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

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

Verify it runs over stdio (Ctrl-C to exit):

```bash theme={null}
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:

```json theme={null}
{
  "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.

<Note>
  **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.
</Note>

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

```python theme={null}
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 changed             | Open in Hub UI                                                                                             |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| Agents                   | [hub.kataven.ai/agents](https://hub.kataven.ai/agents)                                                     |
| Prompts, playbooks, FAQs | [hub.kataven.ai/knowledge](https://hub.kataven.ai/knowledge)                                               |
| Phone numbers            | [hub.kataven.ai/phone-numbers](https://hub.kataven.ai/phone-numbers)                                       |
| Live or recent calls     | [hub.kataven.ai/conversations](https://hub.kataven.ai/conversations)                                       |
| Campaign progress        | [hub.kataven.ai/campaigns](https://hub.kataven.ai/campaigns)                                               |
| Tools, integrations      | [hub.kataven.ai/tools](https://hub.kataven.ai/tools), [hub.kataven.ai/store](https://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](https://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](https://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](https://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

<a id="openai-agents-sdk" />

* [Manage with Codex](/guides/manage-with-codex) — the SDK path if you want a shell.
* [Manage with Claude Desktop](/guides/manage-with-claude-desktop) — same MCP idea, Anthropic side.
* [MCP Server reference](/sdks/mcp/overview) — every tool the server exposes.