MCP guide

Source: orchestration/mcp-gateway/index.ts, server.ts, auth-middleware.ts, execution.ts, prompts.ts, resources.ts, docs-routes.ts, orchestration/api-gateway/routes/mcp.ts, orchestration/api-gateway/lib/auth.ts; live GET /health, GET /v1/info and unauthenticated POST /v1 (live-verified 2026-09-24).

The PlungeAI MCP server puts the PlungeAI platform behind the Model Context Protocol. You connect an MCP client (Claude Code, Cursor, VS Code, Codex, Lovable, Replit, …) once, then ask for things in plain language. The client picks one of the server's 20 plungeai_* tools, fills in the arguments, and the platform does the work: it searches the agent registry, runs agents, CNL workflows and bounded missions, schedules jobs, keeps memory, and returns the finished result as Markdown.

https://mcp.plungeai.com/v1

It is one server with one catalog. The same server is also reachable through the One API at https://api.plungeai.com/v1/mcp; the differences are listed in 0.2.

0.1 Start here — one call

Get an ozk_ key at Dashboard → One API → Keys (https://dashboard.plungeai.com), export it as PLUNGE_API_KEY, then ask the server who you are:

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":"who am I"}}}'

The answer is a server-sent event whose data: line carries your identity card (user id, tier, key label, rate-limit window). Connecting a real client takes one command — see the Quickstart.

0.2 The two endpoints

Both URLs reach the same server code, the same 22 tools, the same prompt and the same resources. Use whichever your client makes easiest; https://mcp.plungeai.com/v1 is the canonical one and the one this guide uses.

Two more facts about the canonical host:

• The pre-2026-09-20 path https://mcp.plungeai.com/mcp still answers with the same handler, so client configs that point at it keep working. New configs use /v1.
• The server answers only on its own hostname. A request that arrives with any other Host header (for example from a reverse proxy that rewrites it) is refused with 403 Invalid Host header: <host>.

Public routes on https://mcp.plungeai.com (no key needed):

GET /log (your own activity trail) needs your key — see Errors, feedback & limits.

0.3 Who it is for

• People working in an AI client — a coding agent (Claude Code, Cursor, VS Code, Codex, Gemini CLI, OpenCode, Windsurf) or a chat app (Claude Desktop). You ask; the client calls the tools.
• App builders — Lovable, Bolt, v0 and Replit connect the server to their builder chat, so the builder can discover and test PlungeAI agents while it writes your app. The app it ships calls the One API, not MCP (Connecting clients covers the split per builder).
• Developers who want a JSON-RPC surface over the whole platform with structured outcomes, approvals and continuations — plain curl works, no SDK needed (Quickstart).

0.4 Tool families

tools/list returns 22 tools. You rarely name them yourself: your client reads their descriptions and chooses. This is the map of what the server can do and where each tool is documented.

Besides tools, the server offers one prompt (plungeai; in Claude Code it is /plungeai:plungeai (MCP) in the slash menu) and five plungeai:// resources plus three resource templates — see Prompts & resources. Every tool's parameters are in the Tool reference.

Two words you will meet everywhere:

• A registry agent is a platform building block in the catalog (brave-agent, sec-agent, weather-agent, …). About 90 are active; plungeai_list_agents returns the live set.
• Your workflows are your saved CNL workflows. In everyday speech users call these "my agents": "show me my agents" means your workflows (plungeai_list_workflows), not the registry. Say "agents in the registry" or "what can the platform do" when you mean building blocks. The server tells every client this at connect time.

0.5 How a request flows

1. Your client sends a JSON-RPC message with POST to /v1. Each request stands alone: no session id is needed (sessions are opt-in per key — Protocol & transport).
2. The edge checks run in this order (index.ts): method (GET/DELETE → 405), Host (→ 403), a declared body over 1 MiB (→ 413; the body is also capped while it is read), then your key (→ 401; failed attempts are metered per IP). A tools/call is then counted against your rate limit (→ 429), checked against the tool catalog and your key's tool fence (→ JSON-RPC -32602), and its arguments are checked against the tool's schema — bad arguments come back as a needs_input answer and nothing runs.
3. A fresh server instance is built for the request with only the tools your key may use. Cheap methods (initialize, tools/list, resources/*, prompts/*) answer with plain JSON.
4. The tool runs. Discovery tools read the live registry. Execution tools refuse any agent that is not status:active before dispatch, then hand the work to the CNL engine over an internal service binding; the engine runs the agents (in parallel where the workflow says so) and stores the result.
5. A tools/call answers as a server-sent-event stream: live progress notifications while it works, then one final result. The result is platform-rendered Markdown by default, or JSON with structuredContent when you pass format: "json". Execution tools answer with a structured outcome (ok | needs_input | needs_connection | needs_api_key | needs_approval | unavailable | error), never a bare error (Errors, feedback & limits).
6. Every authenticated request is written to your per-user activity trail, and every run is a row in the same execution history that Ocean Studio and the dashboard read.

Through https://api.plungeai.com/v1/mcp, the One API authenticates your ozk_ key then forwards it to the same gateway, which validates it again and applies the key's restrictions and rate limit; steps 3–6 are identical.

0.6 What using it feels like

One account, everywhere. A workflow you save here is the same workflow you see in Studio. There is no separate "MCP workspace": workflows, runs and chat conversations you create through MCP appear in the other PlungeAI apps, and the other way round. Everything you can see or run is scoped to the account behind your key (2.8).

You don't name tools. Describe what you want ("find my due-diligence workflow and run it for Adobe"). The client chooses between the 22 tools and fills in the arguments. The server's connect-time instructions tell clients to discover agent ids with a live search rather than from memory, to relay results verbatim, and to never approve a paused action on their own.

Nothing runs silently. While a tool works, the server streams status lines such as:

⚙️ Agents working — 5/18 agents complete · ✓ brave-agent · 13 active (tavily-agent, exa-agent…)
✍️ Writing (3516 chars) — …the agent's answer as it is produced
✅ Complete — 18 agents in 24.6s

A long, quiet step sends a heartbeat every 15 seconds (⏳ Working — 45s elapsed). The feed goes out on the MCP progress channel when your client sends a progressToken, and on the logging channel when it does not, so any client can receive it. Whether it is shown is up to the client: some render it under the running tool, some ignore it. The work and the result are identical either way. Runs started with mode: "async" return an execution id at once and finish in the background, so they have no live feed — poll plungeai_get_workflow_status instead. Details: Protocol & transport.

Clients read the tool list once. Most clients call tools/list when they connect. If a tool you expect is missing after a platform update, restart or reconnect the client (3.1).

0.7 MCP, the One API, skills — which one?

All of them use the same ozk_ key, the same account and the same data.

A common split, used by the app builders: the builder's AI uses MCP to find and test the right agent, then writes app code that calls the One API with a server-side key.

0.8 What "live-verified" means in this guide

Examples that carry a hidden # verify / # expect: marker are read-only and free (initialize, tools/list, plungeai_whoami, the list/get/contract tools, public routes). The docs build strips the markers; node orchestration/api-gateway/docs/guide-3.0/verify-examples.mjs <chapter.md> re-runs them with PLUNGE_API_KEY. The unauthenticated behaviour (401 shapes, /health, /install*, /connect/*, the skills catalog) was run live on 2026-09-24. Examples that need a key were checked against the server code on 2026-09-24; examples that run a model, spend credits or change state carry no marker and say so in the text.

0.9 Where to get help

• This guide: https://www.plungeai.com/docs/mcp, one page per chapter (Markdown: https://mcp.plungeai.com/docs.md; the old address https://mcp.plungeai.com/docs answers 301 here).
• Health, no key: https://mcp.plungeai.com/health.
• One API guide: https://www.plungeai.com/docs/one-api. Skills catalog: https://www.plungeai.com/docs/skills. Install page: https://www.plungeai.com/install.
• Your own request history: https://mcp.plungeai.com/log?date=YYYY-MM-DD with your key (Errors, feedback & limits). A tool that fails on a platform fault answers with a request id — include it when you report a problem.
• Keys: self-service at Dashboard → One API → Keys. Support: Requests (opens in a new tab).

0.10 Versions and what changed

How the server is versioned. The version is the build's serverInfo.version in the initialize result (SERVER_VERSION in server.ts, 2.7.0 on 2026-10-13; the same value is server.version on GET /v1/info and version on GET /health). The tool surface itself is the tools/list catalog. Tools and parameters have no version of their own: they change in place when the server is deployed, and the stateless server sends no list_changed notice (4.5). When the version changes, re-read tools/list (reconnect your client).

This guide replaces the earlier single-page MCP user guide, at the same URL (https://mcp.plungeai.com/docs). Notable corrections against that page:

• claude.ai (web) has no live tools. The mcp-remote bridge is for Claude Desktop; claude.ai gets a skill upload only (3.3).
• Skills. The per-client skills are plungeai-in-<tool> (the old --skill plungeai-<tool> names never existed). The skills plungeai, plungeai-api, plungeai-cli, plungeai-connect and plungeai-mcp were replaced by the 32-skill catalog (plungeai-mcp-setup, plungeai-api-setup, plungeai-cli-setup, …). /connect/api/SKILL.md answers 404; REST setup is plungeai-api-setup. The PlungeAI/plungeai-agent-skills repository is not public yet, so the zips are the working install (3.15, 3.16).
• Ocean CLI. The terminal client is ocean-cli (package @plungeai/ocean). npm i -g @plungeai/ocean does not work yet: the package is not published (3.17).
• Protocol. The server implements 2025-11-25; the old raw-HTTP example asked for 2025-06-18, which still negotiates (4.3).
• Approvals. Only an agent's staged action (⏸ AWAITING USER APPROVAL) continues with plungeai_continue. A trust-fence ⏸ NEEDS APPROVAL cannot be continued over MCP; it runs only from Ocean Studio (6.6).
• provider: google on a one-agent task is accepted, not refused: it maps to gemini. Pass model explicitly, because the default model applies only when provider is omitted or gemini (8.3).
• Tool behaviour. plungeai_list_workflows search matches workflow names only, not descriptions (8.1), and the plungeai_chat assistant cannot save a workflow: ask for plungeai_build_workflow (10.1).
• Key fences. Keys you create in the Dashboard carry no fences; allowed_ips and allowed_tools are set by PlungeAI (2.5).