---
name: plungeai-in-codex
description: "Connect OpenAI Codex CLI to PlungeAI (Ocean Studio) over MCP — native streamable-HTTP in ~/.codex/config.toml (env-var or static bearer token), the codex mcp add terminal command, the mcp-remote bridge fallback, and a plungeai_whoami + plungeai_list_agents verify. Use when the user is in Codex CLI (or asks about ChatGPT + PlungeAI) and says connect / install / set up PlungeAI, mentions config.toml or mcp_servers, or plungeai_* tools never appear. ChatGPT web has no PlungeAI connector yet (OAuth pending) — Codex CLI is the OpenAI-ecosystem door. For another editor use its plungeai-in-<tool> skill; for an unlisted but MCP-capable client use plungeai-mcp-setup's generic client config."
---

# PlungeAI in OpenAI Codex CLI

Codex CLI talks to PlungeAI over the Streamable HTTP MCP server at
`https://mcp.plungeai.com/v1`. One `ozk_` bearer key authenticates it (and
the One API, if generated code calls PlungeAI directly). This is also the
OpenAI-ecosystem door today: ChatGPT web connectors require OAuth (PlungeAI
OAuth in progress), so ChatGPT users connect through Codex CLI instead.

## Prerequisites

- An `ozk_` key: Dashboard → **One API → Keys** (https://dashboard.plungeai.com) —
  self-service, shown once, copy it now.

## Connect (once) — native streamable HTTP (primary)

Codex supports remote streamable-HTTP servers natively. In
`~/.codex/config.toml` (user-level TOML — the right home for anything
key-related):

    [mcp_servers.plungeai]
    url = "https://mcp.plungeai.com/v1"
    bearer_token_env_var = "PLUNGEAI_API_KEY"

Export `PLUNGEAI_API_KEY` in the shell profile; the config file itself never
holds the key, so this pattern is safe even if the file is shared. A static
header works too — user-level file only, never committed:

    http_headers = { Authorization = "Bearer ozk_YOUR_KEY" }

Or from the terminal:

    codex mcp add plungeai --url https://mcp.plungeai.com/v1 --bearer-token-env-var PLUNGEAI_API_KEY
    codex mcp list

## Fallback — mcp-remote bridge (only if the build lacks native `url`)

    [mcp_servers.plungeai]
    command = "npx"
    args = ["-y", "mcp-remote", "https://mcp.plungeai.com/v1",
            "--header", "Authorization: Bearer ozk_YOUR_KEY"]
    startup_timeout_sec = 30

`startup_timeout_sec` defaults to **10 s** — an npx cold start can exceed
it, and then the tools "never appear" with no useful error; set 30. If the
bridge 401s, the client is mangling spaces inside `args` — switch to the
native form above rather than fighting the quoting.

## Verify

1. `codex mcp list` shows `plungeai` (or `/mcp` in the TUI shows it
   connected).
2. Ask Codex: "use plungeai_whoami to confirm my identity" → an identity
   card.
3. "use plungeai_list_agents to search 'web search'" → live results from the
   active agent catalog.

## Quirks

- `config.toml` is TOML, not JSON — no braces or trailing commas; the table
  header is exactly `[mcp_servers.plungeai]` (underscore, not dash).
- `tool_timeout_sec` defaults to 60 s — long CNL workflows should run in
  async mode (`plungeai_execute_workflow` with `mode: "async"` +
  `plungeai_get_workflow_status`) rather than one long synchronous call.
- `/mcp` inside the Codex TUI shows active MCP servers and their status;
  `codex mcp get plungeai` / `codex mcp remove plungeai` manage the entry.
- Codex approval modes gate tool calls; in full-auto the money-verb
  PlungeAI operations still pause with a structured `needs_approval`
  outcome — relay it, then `plungeai_continue`.
- `enabled = false` disables the server without deleting the entry.
- ChatGPT web: no PlungeAI connector yet — OAuth is in progress. Point
  ChatGPT users at Codex CLI in the meantime.

## Where next

- Operating the `plungeai_*` tools once connected: **plungeai-mcp-setup**.
- Writing code that calls `https://api.plungeai.com` directly: **plungeai-api-setup**.
- Picking MCP vs the One API for a given job: **choose-your-plungeai-door**.
- An unlisted but MCP-capable client, or the shared connect concepts (native
  remote vs. stdio bridge, key hygiene): **plungeai-mcp-setup**.