> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP guide

> 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 …


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](#02-the-two-endpoints).

## 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:

```bash
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](/mcp/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.

| | `https://mcp.plungeai.com/v1` | `https://api.plungeai.com/v1/mcp` |
|---|---|---|
| What it is | The MCP gateway itself | A One API route that forwards each request to the gateway together with your own key |
| Methods | `POST` (JSON-RPC). `GET`/`DELETE` without a session → `405` | `POST` only |
| Credentials | `Authorization: Bearer ozk_…` or `X-API-Key: ozk_…` | the same two headers; the value must start with `ozk_` |
| `401` body | JSON-RPC: `{"jsonrpc":"2.0","error":{"code":-32001,"message":"No valid authentication provided. …"},"id":null}` plus `WWW-Authenticate: Bearer` | One API envelope: `{"error":{"code":"unauthorized","message":"Bearer ozk_ key required"}}` plus `X-Error-Code: unauthorized` |
| What counts toward your rate limit | `tools/call` only | `tools/call` only, counted by the gateway |
| `plungeai_whoami` shows | `api-key`, your key's tier and label | the same (the One API forwards your key) |
| Extra routes | public install, docs and skill routes (below) | `GET /v1/mcp/tools` (a plain `GET` that returns the server's `tools/list` answer as the JSON-RPC envelope `{"jsonrpc":"2.0","id":1,"result":{"tools":[…]}}`, without you sending JSON-RPC) and the outbound MCP runs — see `https://api.plungeai.com/docs#11-mcp-plane` |

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):

| Route | What it returns |
|---|---|
| `GET /health` | dependency probes (`d1`, `kv_keys`, `registry`), server version, protocol; `200 healthy` or `503 degraded` |
| `GET /v1/info` | server name `plungeai.com`, version, protocol version `2025-11-25`, capabilities |
| `GET /install`, `/install.json`, `/install/:tool` | the one-click install page and its data — [3.15](/mcp/connecting-clients#315-one-click-installs) |
| `GET /connect/<tool>/SKILL.md`, `/lovable/SETUP.md` | per-client setup skills — [3.15](/mcp/connecting-clients#315-one-click-installs) |
| `GET /llms.txt`, `/llms-full.txt`, `/skill.zip`, `/skill/<file>` | the CNL workflow-authoring skill for LLM tools |
| `GET /docs`, `/docs.md` | this guide, as a web page and as one Markdown file (paste the `.md` URL into an AI client) |

`GET /log` (your own activity trail) needs your key — see [Errors, feedback & limits](/mcp/errors-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](/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](/mcp/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.

| Family | Tools | Chapter |
|---|---|---|
| Discover | `plungeai_list_agents` (search the registry), `plungeai_get_tool_contract` (one agent's exact contract), `plungeai_templates` list/get | [Discovery](/mcp/discovery) |
| Run a tool | `plungeai_execute_tool` (one structured tool-agent, typed params, behind the trust fence) | [Tools](/mcp/tools) |
| Run an agent | `plungeai_execute_agent` (one prompt-driven agent), `plungeai_run_mission` (bounded autonomous mission) | [Agents & missions](/mcp/agents-missions) |
| Workflows | `plungeai_list_workflows`, `plungeai_execute_workflow`, `plungeai_workflow` (create / update / versions), `plungeai_build_workflow`, `plungeai_templates` use | [Workflows](/mcp/workflows) |
| Runs and results | `plungeai_get_result`, `plungeai_get_workflow_status`, `plungeai_executions`, `plungeai_followup`, `plungeai_continue` | [Runs, results & follow-ups](/mcp/runs-results) |
| Chat, memory, skills | `plungeai_chat`, `plungeai_memory`, `plungeai_learn` | [Chat, memory & skills](/mcp/chat-memory-skills) |
| Scheduling | `plungeai_schedule` | [Scheduling](/mcp/scheduling) |
| Identity | `plungeai_whoami` | [Authentication & keys](/mcp/authentication) |
| Companies | `plungeai_companies` (campuses compiled from your saved documents: items, gates, the clock) | [Companies](/mcp/companies) |
| Connections | `plungeai_connections` (your connected accounts and your customers': list, add a key, remove, send a connect link) | [Connections](/mcp/connections) |

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](/mcp/prompts-resources). Every tool's parameters are in the [Tool reference](/mcp/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](/mcp/protocol)).
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](/mcp/errors-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](/mcp/authentication#28-identity-and-scoping)).

**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](/mcp/protocol).

**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](/mcp/connecting-clients#31-before-you-start)).

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

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

| Surface | What it is | Use it when |
|---|---|---|
| **MCP server** — `https://mcp.plungeai.com/v1` | the 22 `plungeai_*` tools over MCP | an AI client operates PlungeAI live: discover, run, save, schedule, remember, with approvals and continuations |
| **One API** — `https://api.plungeai.com` | REST routes, OpenAPI at `GET /v1/openapi.json` | you write or generate code that calls PlungeAI (apps, scripts, backends, CI) — `https://api.plungeai.com/docs` |
| **Skills** — `https://skills.plungeai.com` | 32 instruction packs your AI client loads (setup per client, capability guides, CNL authoring) | you want your client to already know PlungeAI's conventions; skills complement a connection, they are not one — [3.16](/mcp/connecting-clients#316-the-skills-catalog) |
| **Ocean Studio** — `https://studio.plungeai.com` | the browser app | a human builds visually, connects accounts (Connectors), saves bring-your-own keys, reviews runs |

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](/mcp/errors-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](https://www.plungeai.com/request/new?kind=question).

## 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](/mcp/protocol#45-stateless-by-default-opt-in-sessions)). 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](/mcp/connecting-clients#33-claudeai-and-claude-desktop)).
- **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](/mcp/connecting-clients#315-one-click-installs), [3.16](/mcp/connecting-clients#316-the-skills-catalog)).
- **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](/mcp/connecting-clients#317-the-ocean-cli)).
- **Protocol.** The server implements `2025-11-25`; the old raw-HTTP example asked for `2025-06-18`, which still negotiates ([4.3](/mcp/protocol#43-protocol-version-and-initialize)).
- **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](/mcp/tools#66-the-trust-fence--needs-approval)).
- **`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](/mcp/workflows#83-ad-hoc-cnl-yaml)).
- **Tool behaviour.** `plungeai_list_workflows` `search` matches workflow names only, not descriptions ([8.1](/mcp/workflows#81-find-your-workflows--plungeai_list_workflows)), and the `plungeai_chat` assistant cannot save a workflow: ask for `plungeai_build_workflow` ([10.1](/mcp/chat-memory-skills#101-chat-plungeai_chat)).
- **Key fences.** Keys you create in the Dashboard carry no fences; `allowed_ips` and `allowed_tools` are set by PlungeAI ([2.5](/mcp/authentication#25-key-fences)).