plungeai-mcp-setup

Connect and operate the PlungeAI MCP server (https://mcp.plungeai.com/v1 (opens in a new tab)) — endpoint and Bearer ozk_/X-API-Key auth, a generic MCP client config (native remote/HTTP, or the mcp-remote stdio bridge), plungeai_whoami, the structured-outcome envelope and trust fences, the full plungeai_* tool index pointing to the capability skill for each tool, and connection troubleshooting. Use when connecting ANY MCP client to PlungeAI, calling or planning plungeai_* tool calls, polling an execution, resuming a paused run (plungeai_continue), or debugging a 401, a short tool list, or a fenced key. Triggers: "plungeai MCP", "mcp.plungeai.com", "connect an MCP client", "plungeai_whoami", "needs_approval", "execution id". Per-editor install steps live in plungeai-in-<tool> — load that instead. REST/codegen is plungeai-api-setup; terminal is plungeai-cli-setup; CNL authoring is plungeai-workflows.

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

The PlungeAI MCP server turns the whole platform into a control plane for any MCP client: discover and run agents, execute and build CNL workflows, run typed tool calls, bounded autonomous missions, schedules, persistent chat, human-in-the-loop approvals, and long-term memory. Everything it creates uses the same storage as Ocean Studio, so workflows, executions, and conversations cross-appear in every app and door.

Prerequisites

Self-service ozk_ key: Dashboard → One API → Keys (https://dashboard.plungeai.com) → create → copy it once. Ask the account owner only for a shared/team key minted under someone else's account.

Connect

Endpoint https://mcp.plungeai.com/v1 (Streamable HTTP), auth header Authorization: Bearer ozk_YOUR_KEY (or X-API-Key: ozk_YOUR_KEY). POST https://api.plungeai.com/v1/mcp is the identical server on the API host, for a client that can only reach one host. One-click install page: https://mcp.plungeai.com/install (machine form: /install.json) — type the key into the box before clicking a button, so the deeplink is rewritten with the Authorization header baked in; clicked without a key the server installs auth-less and you add the header by hand afterward.

Generic client config (any MCP client not covered by a plungeai-in-<tool> skill):

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

2. stdio-only client: bridge with mcp-remote (opens in a new tab) (Node 18+):

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

   Clients that mangle 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. The bridge is an npx process — a cold start can exceed a client's default startup timeout (Codex default: 10s); raise it where the client has one.

3. Neither → skip MCP and use the One API instead (plungeai-api-setup) — every capability is reachable over plain HTTPS.

Key handling. User-level config, never committed: the literal key lives only in the tool's home config or its secret store, never in a repo file. A project-level config may only reference an env var. Before the first commit in any repo you just configured:

git grep -n "ozk_"                                     # tracked files
grep -rn "ozk_" . --exclude-dir=.git --exclude-dir=node_modules   # untracked too

Both must print nothing.

Verify

plungeai_whoami {user_request: "verify my plungeai connection"}

Expect: user id, auth type + tier, key label, rate-limit window (used/minute, used/day), and the server identity (mcp.plungeai.com). A 401 means the key is missing/invalid — fix the header, don't retry blind. There is no permissions field on the card — fencing shows up as which tools tools/list returns, not on whoami. One real call proves the catalog too: plungeai_list_agents {search: "web search"} → live results.

The five rules that prevent most failures

1. Discovery first, ids never from memory. The agent catalog is live and active-only. plungeai_list_agents {search: "<capability in plain words>"} is a hybrid semantic+keyword search — take agent ids verbatim from its results. An unknown or non-active id is REFUSED at execution (nothing runs); re-discover, never guess or reuse an id from an earlier session.
2. Relay results verbatim. Every successful tool output is final, platform-rendered, user-ready markdown. Present it in full — do not re-write, shorten, or summarize unless asked. The parts addressed to you are the guidance tails: execution-id footers, poll hints, and ⏸ continuation blocks — act on those.
3. Structured outcomes, never blind retries. Execution tools answer with a status envelope (ok | needs_input | needs_connection | needs_api_key | needs_approval | unavailable | error), never a raw error. Follow the remediation; never retry the identical call.
4. ⏸ approval fences are the user's, not yours. A run pausing with ⏸ AWAITING USER APPROVAL: <action> (cost) or ⏸ AWAITING USER: <question> must be relayed verbatim. Only after the user decides do you call plungeai_continue (approve: true ONLY for an explicit yes; message: "<their words>" for an answer, denial, or change of course). NEVER approve on your own.
5. Pass user_request on every call — the user's original ask, verbatim, before you translated it into arguments. Every tool accepts it; the platform uses it for routing and support diagnostics.

Terminology trap: users call their saved workflows "agents" too. An unqualified "show me my agents" means their SAVED WORKFLOWS → plungeai_list_workflows, not the registry (plungeai_list_agents).

Sync vs async, and continuation

• Sync (default on most tools): streams progress, returns the finished result. Typical workflows finish in seconds (parallel RPC fan-out).
• Async (mode: "async"): returns an execution_id immediately; the run continues server-side. Use it for anything that could exceed ~3 minutes (Claude Desktop hard-caps a tool call at ~4 minutes). Poll plungeai_get_workflow_status, fetch with plungeai_get_result. Ceiling: ~15-minute wall cap per attempt. plungeai_run_mission/plungeai_learn default to async; plungeai_execute_agent has no mode — always sync.
• ⏸ Continuation: the pause appears as a tail on the result, on plungeai_get_result, and in plungeai_get_workflow_status.structuredContent.continuation. Relay it verbatim → ask the user → plungeai_continue {execution_id, approve: true} (yes) or {execution_id, message: "<their words>"} (no/change). The execution id doubles as the conversation session id.

Tool map

The catalog is served live by tools/list (20 tools at last sync — tools/list is authoritative; a fenced key sees fewer). Full parameter-level detail for each lives in the capability skill named below.

Beyond tools, the server also serves 8 MCP resources (registry or the caller's own data, ownership-checked): plungeai://agents/list, /agents/categories, /agents/{category}, /personas/list, /workflows/list, /workflows/{id}, /executions/{id}, /docs/workflow-authoring — plus one prompt, /plungeai, that primes a client with the platform operating instructions.

Auth model, outcome envelope, trust fences

An API key IS a user identity — the key resolves to a user id, and every read/write on every tool is scoped to what that user owns, the same view they have in Studio. A foreign id answers "not found," not "forbidden."

Execution tools never return a raw error: the answer is text plus structuredContent with status: ok | needs_input | needs_connection | needs_api_key | needs_approval | unavailable | error, summary, and typed remediation.actions (connect_provider, provide_api_key, provide_field, approve_via/respond_via, retry_with, use_alternative). isError is true ONLY for terminal error outcomes — every other status is guidance, not a crash.

Trust fences (surface, never retry, never bypass): the active-only fence refuses an unknown/inactive agent id before dispatch — re-discover, never retry the same id. The approval fence (needs_approval / ⏸) is a deliberate human boundary — only the user decides. Connection fences (needs_connection/needs_api_key) need the user's browser (Studio → Connectors) — relay instructions, wait, then retry the identical call once they confirm (the one case where repeating the same call is correct). Full protocol-error table, rate limits (free 30/min·1k/day, pro 100/min·10k/day, enterprise 300/min·100k/day), per-key fences (allowed_ips, allowed_tools), and the failure-classification table: references/identity-and-errors.md.

Troubleshooting

Per-tool reload steps and config paths (Cursor, VS Code, Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, Windsurf, Replit, Lovable, Bolt, v0): plungeai-in-<tool>.

References

• Full guide: https://mcp.plungeai.com/docs#1-quickstart (opens in a new tab) — every tool's parameters and a tools/call example at https://mcp.plungeai.com/docs#14-tool-reference (opens in a new tab).
• references/identity-and-errors.md — plungeai_whoami in full, the auth model, the two error planes (protocol vs tool-outcome), rate limits, per-key fences, and the failure classification table.

Related skills

• plungeai-in-<tool> — exact per-editor connect steps and quirks.
• plungeai-api-setup — the same platform over REST instead of MCP.
• plungeai-cli-setup — operate PlungeAI from a terminal.
• plungeai-workflows — CNL YAML authoring deep-dive.
• plungeai-discovery, plungeai-agents, plungeai-tools-connectors, plungeai-missions, plungeai-scheduling, plungeai-memory, plungeai-results-traces — per-tool capability detail.

Reference pages