Connecting clients

Source: orchestration/mcp-gateway/integrations.ts, install-routes.ts, platform/src/worker/install.ts (the install page on www), llms-routes.ts, docs-routes.ts, skill-dist.generated.ts, index.ts; apps/ocean-skills/skills/plungeai-in-*/SKILL.md (per-client facts, checked against vendor docs by that skill set), apps/ocean-skills/skills/plungeai-mcp-setup/SKILL.md, apps/ocean-skills/.mcp.json (the plugin's MCP server), apps/ocean-skills/scripts/mirror-public.sh; live GET /install, /install.json, /install/:tool, /connect/<tool>/SKILL.md and https://skills.plungeai.com/index.json (live-verified 2026-09-24).

Every client needs the same two things: the URL https://mcp.plungeai.com/v1 and the header Authorization: Bearer ozk_YOUR_KEY. What differs is where each client keeps its config and what it calls the fields. https://api.plungeai.com/v1/mcp is the same server and works in any of these configs; this chapter uses the canonical URL.

Setup skill paths are on https://mcp.plungeai.com (for example https://mcp.plungeai.com/connect/cursor/SKILL.md); the same skills are on https://skills.plungeai.com as plungeai-in-<tool> (3.16).

3.1 Before you start

Transport. The server speaks Streamable HTTP (clients call it "http", "remote" or "streamable-http"). A client that can only launch local stdio servers connects through the mcp-remote bridge (3.14). A client that can only speak the old SSE transport cannot connect: the server answers GET with 405 at once.

Where the key goes. Put the literal key only in a user-level config file or the client's secret store. A config file inside a repository should reference an environment variable instead; each section below shows the client's syntax for that. This guide names the variable PLUNGE_API_KEY; the setup skills and the install page use PLUNGEAI_API_KEY. Any name works as long as your config and your shell agree. Before committing, run the git grep check in 2.9.

Check the key outside the client first. If this returns your identity card, the key is good and any remaining problem is in the client config:

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_whoami","arguments":{"user_request":"verify my plungeai connection"}}}'

Verify in the client. The same three checks work everywhere:

1. The client's MCP panel or command shows plungeai connected, with tools listed.
2. Ask: "use plungeai_whoami to confirm my identity" → an identity card (user id, tier, key label, rate window, server).
3. Ask: "use plungeai_list_agents to search 'web search'" → live registry results. This proves the catalog is reachable, not just the key.

Reload after every edit. Clients read the tool list when they connect. After changing the config — or after a platform update adds a tool — restart the client or reload its MCP servers before debugging anything else.

Approvals are server-side. A client's auto-approve or auto-run setting only skips the client's own confirmation prompt. Outward, irreversible operations (payments, sends) still stop with a needs_approval outcome. An agent's staged action continues only after your explicit answer; a trust-fence refusal cannot be continued over MCP at all and runs only from Ocean Studio (6.6).

Tool caps. Some clients limit how many tools they send to the model across all connected servers. PlungeAI adds 22 (fewer with a fenced key). If plungeai_* tools are missing, turn off tools or servers you do not use.

3.2 Claude Code

Terminal one-liner (the key expands from your shell and is stored in ~/.claude.json):

claude mcp add --transport http plungeai https://mcp.plungeai.com/v1 \
  --header "Authorization: Bearer $PLUNGE_API_KEY" --scope user

• --scope user: every project. Default local: this project only. Both live in ~/.claude.json.
• Never --scope project with a literal key — it writes the key into the repo's .mcp.json.

Team-shared project file (safe to commit — it holds no key; each developer exports PLUNGE_API_KEY before starting Claude Code):

{
  "mcpServers": {
    "plungeai": {
      "type": "http",
      "url": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer ${PLUNGE_API_KEY}" }
    }
  }
}

Verify: claude mcp list (or /mcp in a session) shows plungeai connected; then the three checks in 3.1.

Quirks:

• 401 (No valid authentication provided…): the header never arrived or the key is wrong. Re-check the header field in ~/.claude.json / .mcp.json rather than the key value, and look for whitespace pasted into the key.
• Connected but no plungeai_* tools: restart the session after any config edit.
• Long CNL workflows: ask for them to run in the background (mode: "async" + plungeai_get_workflow_status) rather than one long synchronous call.
• Type /plungeai and pick /plungeai:plungeai (MCP) to start from the server's prompt; run it bare and give your request in the next message (Prompts & resources).
• Skills for Claude Code (conventions, CNL authoring): working today, download a zip from https://skills.plungeai.com (or https://mcp.plungeai.com/skill.zip, the workflow-authoring skill) and unzip it into .claude/skills/ or ~/.claude/skills/. When the public repo is published: claude plugin marketplace add PlungeAI/plungeai-agent-skills, then claude plugin install plungeai@plungeai (3.16). The plugin also registers its own plungeai MCP server (header Bearer ${PLUNGEAI_API_KEY}), so install it instead of claude mcp add, not in addition, and export PLUNGEAI_API_KEY. If you already added the server by hand, keep only one of the two.

3.3 Claude.ai and Claude Desktop

Two surfaces, two capabilities:

Why a bridge: the custom-connector UI in claude.ai and Desktop (Settings → Connectors → Add custom connector) authenticates only through OAuth and has no field for a bearer header, and the PlungeAI MCP server has no OAuth yet.

Claude Desktop. Needs Node.js (the bridge runs through npx). Open Settings → Developer → Edit Config; the file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Merge:

{
  "mcpServers": {
    "plungeai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.plungeai.com/v1",
               "--header", "Authorization: Bearer ozk_YOUR_KEY"]
    }
  }
}

Quit Claude Desktop completely and start it again; the file is read only at start.

claude.ai web. First turn on Settings → Capabilities → Code execution and file creation (required for any custom skill). Then Customize → Skills → + → Upload a skill and upload https://mcp.plungeai.com/skill.zip (the workflow-authoring skill; start with this one), or a single-skill zip from https://skills.plungeai.com (https://skills.plungeai.com/<name>.zip), one skill per upload. Skill names may not contain the reserved word "claude", so plungeai-in-claude-ai and plungeai-in-claude-code cannot be uploaded to claude.ai. The all-in-one plungeai-agent-skills.zip holds all 32 skills; it is for unzipping into a skills folder, not for upload.

Verify: Desktop — the three checks in 3.1. claude.ai web has no live call to check; ask Claude to draft a PlungeAI CNL workflow to confirm the skill loaded.

Quirks:

• Windows: Desktop does not escape spaces inside args. If the bridge answers 401 only on Windows, use "--header", "Authorization:${AUTH_HEADER}" and add "env": { "AUTH_HEADER": "Bearer ozk_YOUR_KEY" } to the same entry.
• Logs: ~/Library/Logs/Claude/mcp*.log (macOS), %APPDATA%\Claude\logs (Windows). Read them before editing the config again.
• The bridge is an npx process; a cold start takes a few seconds. If the tools never appear, wait, then check the logs.
• Claude Desktop caps a single tool call at about 4 minutes. For anything longer, ask for it to run "in the background": you get an execution id at once and ask for the status or result later.
• 401 through the bridge with a key that looks right: whitespace, or a missing ozk_ prefix — paste the key again.

3.4 Cursor

One click. Open https://www.plungeai.com/install, type your ozk_ key into the box at the top, then click Add to Cursor and confirm Cursor's install dialog. The link is rewritten in your browser to include the header. Clicked without a key, the server installs with no header (it shows red, 401) and you add the headers block by hand.

By hand, in ~/.cursor/mcp.json (user-level — the right place for a literal key):

{
  "mcpServers": {
    "plungeai": {
      "url": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer ozk_YOUR_KEY" }
    }
  }
}

A project .cursor/mcp.json gets committed; there, reference a variable: "Authorization": "Bearer ${env:PLUNGE_API_KEY}" (Cursor interpolates ${env:…} in command, args, env, url and headers).

Verify: Settings → MCP → plungeai has a green dot and lists tools; then the checks in 3.1 in Agent chat.

Quirks:

• MCP tools run in Agent and Plan modes. Ask mode is read-only and does not call them.
• Tool calls ask for approval per call by default.
• Red status or "No tools found" right after install: check auth first — the headers object must sit inside the plungeai entry, and the key must be intact.
• After editing mcp.json, toggle the server off and on in Settings → MCP (or restart Cursor).
• The plungeai-in-cursor skill notes a reported cap of roughly 40 MCP tools across all servers (not in Cursor's current docs). If plungeai_* tools are missing, turn off unused servers or tools and reopen the chat.
• Keep sessions discovery-first with a line in .cursor/rules/plungeai.mdc: "PlungeAI: agent ids come from a live plungeai_list_agents search — never from memory." Rules files are committed; never put the key there.

3.5 VS Code (GitHub Copilot)

From a terminal (simplest):

code --add-mcp '{"name":"plungeai","type":"http","url":"https://mcp.plungeai.com/v1","headers":{"Authorization":"Bearer ozk_YOUR_KEY"}}'

In PowerShell or cmd, double-quote the JSON and escape the inner quotes with \".

One click: type your key into the box on https://www.plungeai.com/install, click Add to VS Code, confirm the MCP dialog.

Committed-safe workspace file .vscode/mcp.json: the inputs block makes VS Code prompt for the key once and store it encrypted, so the file never holds the key:

{
  "inputs": [
    {
      "id": "plungeai-key",
      "type": "promptString",
      "password": true,
      "description": "PlungeAI ozk_ key"
    }
  ],
  "servers": {
    "plungeai": {
      "type": "http",
      "url": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer ${input:plungeai-key}" }
    }
  }
}

Machine-wide instead: MCP: Open User Configuration, or MCP: Add Server with the user scope — same fields, outside any repo.

Verify: MCP: List Servers shows plungeai running and the chat Tools picker lists plungeai_*; then the checks in 3.1 in Copilot agent chat.

Quirks:

• MCP tools run in agent mode (Chat view → mode picker → Agent).
• At most 128 tools per chat request across all sources. Over the limit, deselect servers or tools in the Tools picker, or let github.copilot.chat.virtualTools.threshold group tools beyond the threshold.
• Mistyped key: MCP: List Servers → plungeai → Show Output shows the 401. Restart the server from the same menu; if it does not ask for the stored input again, remove and re-add the server.
• Locked-down setups: chat.mcp.access decides which MCP servers may run, and organisation policies (ChatAllowedMcpServers, ChatDeniedMcpServers, ChatAllowManagedMcpServersOnly) can allow- or deny-list servers. A missing MCP section in settings usually means one of these.
• VS Code asks you to confirm you trust a server before its first start, except when it is started directly from mcp.json.

3.6 Codex CLI (and ChatGPT)

Codex CLI supports remote streamable-HTTP servers natively. In ~/.codex/config.toml:

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

Export PLUNGE_API_KEY in your shell profile; the file holds no key. Or add it from the terminal:

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

A static header also works, in the user-level file only: http_headers = { Authorization = "Bearer ozk_YOUR_KEY" }.

Fallback for a build without native url support — the mcp-remote bridge:

[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 seconds; an npx cold start can exceed it, and then the tools never appear with no useful error. If the bridge answers 401, Codex is splitting the spaces inside args — use the native form above.

Verify: codex mcp list shows plungeai (or /mcp in the TUI shows it connected); then the checks in 3.1.

Quirks:

• config.toml is TOML: no braces around the table, no trailing commas, and the header is exactly [mcp_servers.plungeai] (underscore).
• tool_timeout_sec defaults to 60 seconds. Run long workflows with mode: "async" and poll plungeai_get_workflow_status.
• codex mcp get plungeai and codex mcp remove plungeai manage the entry; enabled = false turns it off without deleting it.
• ChatGPT (web): not supported yet. ChatGPT connectors need OAuth, and PlungeAI OAuth is in progress. ChatGPT users connect through Codex CLI for now.

3.7 Gemini CLI

Merge into ~/.gemini/settings.json (user-level):

{
  "mcpServers": {
    "plungeai": {
      "httpUrl": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer ozk_YOUR_KEY" }
    }
  }
}

The key is httpUrl, not url. Gemini CLI uses url for SSE servers; this server answers an SSE-style GET with 405, so a url entry never connects. This is the most common mistake with this client.

If your build has no httpUrl, bridge instead:

{
  "mcpServers": {
    "plungeai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.plungeai.com/v1",
               "--header", "Authorization: Bearer ozk_YOUR_KEY"]
    }
  }
}

A project .gemini/settings.json gets committed — keep the literal key in the user-level file.

Verify: /mcp in the CLI lists plungeai with its tools; then the checks in 3.1.

Quirks:

• /mcp reload reconnects the servers and re-reads their tools after a settings edit. (/mcp refresh exists on some builds but has had reload bugs upstream.) If neither picks up the change, restart the CLI.
• Tool calls ask for confirmation by default; "trust": true on the server entry skips that prompt. Platform approvals still pause.
• A setup that used to work and now shows no tools usually means the key was revoked or expired — run the curl check in 3.1 before touching the config.
• A GEMINI.md line such as "PlungeAI agent ids come from a live plungeai_list_agents search — never from memory" keeps sessions discovery-first. Context files are committed; never put the key there.

3.8 OpenCode

Merge into ~/.config/opencode/opencode.json (user-level) or the project's opencode.json:

{
  "mcp": {
    "plungeai": {
      "type": "remote",
      "url": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer ozk_YOUR_KEY" }
    }
  }
}

The top-level key is mcp (not mcpServers), and a remote server needs "type": "remote". In a committed project file, use variable substitution: "Authorization": "Bearer {env:PLUNGE_API_KEY}" ({file:path} also exists, for a key file).

Verify: the checks in 3.1.

Quirks:

• The project config merges over the user config. If tools behave oddly, check whether a committed opencode.json (or .jsonc) redefines mcp.plungeai, for example with "enabled": false.
• {env:…} is resolved at startup: export the variable before launching OpenCode, or the header goes out empty and you get 401.
• MCP servers connect at startup; restart the session after any config edit.
• OpenCode reads AGENTS.md — the place for a discovery-first reminder. It is committed; never put the key in it.

3.9 Windsurf

Windsurf has no install-page button; it is configured by file. Merge into ~/.codeium/windsurf/mcp_config.json (user-level), then refresh the MCP servers in Cascade's MCP panel or restart Windsurf:

{
  "mcpServers": {
    "plungeai": {
      "serverUrl": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer ozk_YOUR_KEY" }
    }
  }
}

serverUrl is the documented key for remote servers (Windsurf also accepts url, but its examples use serverUrl). Older stdio-only builds use the mcp-remote bridge, with the same command/args block as in 3.7.

Verify: Cascade's MCP panel shows plungeai with tools after a refresh; then the checks in 3.1 in Cascade.

Quirks:

• Config edits are not hot-reloaded: refresh the MCP panel (or restart) after every change.
• Cascade has a limit of roughly 100 tools across all servers. If plungeai_* tools are missing, turn off unused servers and refresh.
• Discovery-first rules go in .windsurf/rules/*.md (the older .windsurfrules is still read) or ~/.codeium/windsurf/memories/global_rules.md. Rules files are committed; never put the key there.

3.10 Replit

Replit's MCP integration is for Replit Agent while it builds. Apps the Agent ships call the One API (https://api.plungeai.com) with their own key in Replit Secrets.

One click: type your key into the box on https://www.plungeai.com/install, then click Add to Replit; the integration is imported with its Authorization header. Clicked without a key, add the header afterwards under the integration's Advanced settings.

By hand: Integrations → MCP Servers → + Add MCP server → Display name PlungeAI, Server URL https://mcp.plungeai.com/v1, then Advanced settings → custom header Authorization = Bearer ozk_YOUR_KEY.

The integration is account-level: the Agent gets the plungeai_* tools in all your projects.

Verify: ask the Agent "use plungeai_whoami to confirm my identity", then "use plungeai_list_agents to search 'web search'".

Quirks:

• Two key locations, never mixed: the integration's header (for the Agent) and Replit Secrets (for your Repl's own code). Never put the key in source files, .replit or replit.nix.
• An app that works in the workspace but answers 401 after deploy: the deployment's secrets are missing the key.
• A tool that requires confirmation prompts before it runs; platform approvals still pause regardless.
• The usual split when you ask the Agent to "build an app that uses PlungeAI": it uses MCP to find and test the right agent, then writes app code that calls the One API with the key from Replit Secrets.

3.11 Lovable

Two connectors, two purposes.

Chat connector (any plan). Connectors → + → MCP server → Server name PlungeAI, Server URL https://mcp.plungeai.com/v1, Authentication → bearer token / API key → paste your ozk_ key. Lovable's chat now has the plungeai_* tools while it builds.

• Chat connectors are personal: each workspace member connects the server with their own key.
• They are build-time only and never part of the published app.
• Workspace admins can switch custom MCP servers off for everyone (Connectors → Admin settings → Chat connectors → "Custom MCP"). A member who cannot find "MCP server" in the picker is hitting that switch.

App connector (workspace admin). So that apps built in Lovable call PlungeAI in production, an admin creates a custom connector for the One API. Connectors → + → Custom connector:

Members connect it to their apps with their own key; Lovable checks the key against the test request (green check = valid) and attaches it to every One API call the app makes, so generated code must never add its own Authorization header. The full admin pack, including the agent knowledge to attach to the connector, is at https://mcp.plungeai.com/lovable/SETUP.md.

Verify: chat — the checks in 3.1; app connector — the green check when an app is connected.

Quirks:

• If generated code contains an Authorization header, the connector knowledge was not attached or the connector step was skipped.
• The app connector is admin-only. Non-admins use the chat connector for building and hand SETUP.md to their admin.

3.12 Bolt.new

Bolt is a hosted builder: no config file, only the connector form. From the Bolt home chatbox: + → Connectors → Manage connectors → Custom MCP server:

Bolt does not document which header its API-key field sends. The server accepts both X-API-Key: ozk_… and Authorization: Bearer ozk_…, so the raw key works; confirm with the checks below.

Verify: in the builder chat, the checks in 3.1.

Quirks:

• Auto-enable for all projects turns the connector on in each new project; existing projects enable it from the same Connectors menu.
• Adding a connector turns all its tools on, and the tool list is global — you cannot choose tools per project.
• Tools missing mid-session: in Manage connectors, check the connector is enabled for this project and its tools are on.
• The connector key authenticates the builder only. The shipped app needs a server function that holds the key as an environment variable and calls the One API. An app that worked in preview but answers 401 when deployed usually shipped without that variable. The key must never reach the client bundle or a browser fetch.
• Long CNL workflows can outlast a builder-chat step: ask for them to run in the background.

3.13 v0 (Vercel)

v0 is a hosted builder: no config file, only the MCP form. Open + in the prompt form → MCPs → add your own server (the project settings page offers the same under Add MCP):

Then pick the server's permission mode: Disabled, Ask for Approval (Manual) or Always Run (Auto). Manual is the sensible default.

The generated app cannot call MCP. The builder chat uses MCP; the generated Next.js app calls the One API on the server side only, for example from a Route Handler:

// app/api/plungeai/route.ts
export async function POST(req: Request) {
  const { prompt, agentId } = await req.json()
  const r = await fetch(`https://api.plungeai.com/v1/agents/${agentId}/execute`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PLUNGE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ prompt, sync: true }),
  })
  return Response.json(await r.json())
}

Keep the key in a Vercel environment variable for every environment that needs it — never in a client component, never prefixed NEXT_PUBLIC_. The route is documented at https://api.plungeai.com/docs#9-agents-plane.

Verify: in the builder chat, the checks in 3.1.

Quirks:

• Previews run without the project's environment variables until the project is linked or deployed; a 401 from a preview app does not mean the MCP integration is wrong.
• If generation puts the fetch in a "use client" component, regenerate with: "PlungeAI calls go through a Route Handler; the key stays server-side."
• Long CNL workflows: ask for them to run in the background rather than one long builder-chat call.

3.14 Any other MCP client

1. Native remote / HTTP support (preferred): URL https://mcp.plungeai.com/v1, header Authorization: Bearer ozk_YOUR_KEY (or X-API-Key: ozk_YOUR_KEY).

2. stdio-only client: bridge with mcp-remote (Node 18+):

   { "mcpServers": { "plungeai": { "command": "npx",
     "args": ["-y", "mcp-remote", "https://mcp.plungeai.com/v1",
              "--header", "Authorization: Bearer ozk_YOUR_KEY"] } } }

   Clients that split spaces inside args (mcp-remote's README names Cursor, Codex CLI and Claude Desktop on Windows): pass "--header", "Authorization:${AUTH_HEADER}" plus "env": { "AUTH_HEADER": "Bearer ozk_YOUR_KEY" } in the same entry. Raise the client's startup timeout if it has one — an npx cold start can exceed it.

3. SSE-only or OAuth-only client (ChatGPT web connectors, claude.ai custom connectors): not supported yet. Use the One API instead — every capability is reachable over plain HTTPS (https://www.plungeai.com/docs/one-api).

A config written before 2026-09-20 may point at https://mcp.plungeai.com/mcp. That path still answers with the same server, so it keeps working; new configs use /v1.

3.15 One-click installs

The install page — https://www.plungeai.com/install — has one card per target: Claude Code, claude.ai / Claude Desktop, Cursor, VS Code, Replit, Lovable, Bolt.new, v0, Windsurf, the Ocean CLI and ChatGPT / Codex. Each card lists the steps and, where there is one, a ready config snippet. Type your key into the box at the top first: the Add to Cursor, Add to VS Code and Add to Replit buttons are then rewritten in your browser to carry the Authorization header. The page makes no network call with the key; it never leaves the page.

Deeplink redirects — GET /install/:tool answers 302 to the client's install link, without a key (you add the header afterwards). It exists for cursor, vscode and replit; any other tool is 404 (live-verified 2026-09-24):

curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' https://mcp.plungeai.com/install/cursor

The headers part is present only when the page built the link from a key you typed.

Machine-readable — GET /install.json has the same data: name, mcp, api, openapi, llms_txt, skill, and tools[] with id, name, method (deeplink · snippet · guide), snippet, skill, steps[] and, for the three deeplink tools, deeplink:

curl -s https://mcp.plungeai.com/install.json

Per-client setup skills — GET /connect/<tool>/SKILL.md returns the plungeai-in-<tool> skill as Markdown, for the twelve tools claude-code, claude-ai, cursor, vscode, codex, gemini-cli, opencode, windsurf, replit, lovable, bolt, v0. GET /connect/SKILL.md is the client-independent plungeai-mcp-setup skill. Paste the URL into your client and ask it to follow the steps:

curl -s https://mcp.plungeai.com/connect/cursor/SKILL.md

Other distribution routes on the same host (no key needed):

3.16 The skills catalog

https://skills.plungeai.com is the catalog of PlungeAI skills — instruction packs your AI client loads so it already knows how to set up and use PlungeAI. A skill is not a connection; it complements one. Version 3.1.0 holds 32 skills (live-verified 2026-10-05):

Each skill is at https://skills.plungeai.com/<name>/SKILL.md and https://skills.plungeai.com/<name>.zip; all of them are in https://skills.plungeai.com/plungeai-agent-skills.zip. /index.json lists every skill with its group, skill_md_url, zip_url and install_command; /llms.txt is the same for LLM tools:

curl -s https://skills.plungeai.com/index.json

Install today: download a zip and unzip it into your client's skills folder — each zip holds one folder named after the skill (Claude Code: .claude/skills/ or ~/.claude/skills/; claude.ai: upload one single-skill zip at a time under Customize → Skills, not the two plungeai-in-claude-* skills and not the bundle, 3.3).

Install once the public repository is published. The catalog also shows one-command installs from PlungeAI/plungeai-agent-skills. That repository is not public yet (live check 2026-09-24); these commands work once it is:

npx skills add PlungeAI/plungeai-agent-skills --all --global             # every skill, user-level
npx skills add PlungeAI/plungeai-agent-skills --skill plungeai-in-cursor # one skill

• Claude Code: /plugin marketplace add PlungeAI/plungeai-agent-skills, then /plugin install plungeai@plungeai. The plugin brings its own plungeai MCP server (header Bearer ${PLUNGEAI_API_KEY}): use it instead of claude mcp add, not next to it (3.2).
• OpenAI Codex: $skill-installer PlungeAI/plungeai-agent-skills.

Which skill matches which chapter of this guide:

3.17 The Ocean CLI

The Ocean CLI (ocean-cli) is a terminal client for the same platform, built for scripts, CI and other agents: every capability is a verb with flags (ocean-cli workflows run <id>, ocean-cli missions run, ocean-cli executions list, …), --json on every verb and stable exit codes. ocean-cli login signs you in through the browser and stores your ozk_ key (--no-browser asks for it at a hidden prompt instead); ocean-cli whoami shows the identity behind the key and ocean-cli doctor checks connectivity. The bot surface is there too: workflows permissions|files|inbox|bindings|save-version, bot-groups, executions steer|files, schedules create --at/--ends-at, wake, triggers webhook|email|hooks and missions run --sync. It is not an MCP client you configure: it calls this server's /v1 and the One API with the same key. Its npm package @plungeai/ocean is not published yet. ocean-cli --help (at every level) lists the commands and flags.

3.18 When a client won't connect

More in Troubleshooting & gotchas.