plungeai-in-codex

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.

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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 (opens in a new tab)) — 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.
• Full guide: https://mcp.plungeai.com/docs#3-connecting-clients (opens in a new tab)