---
name: plungeai-mcp-setup
description: "Connect and operate the PlungeAI MCP server (https://mcp.plungeai.com/v1) — 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`."
---

# PlungeAI MCP — connect and operate

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](https://www.npmjs.com/package/mcp-remote)
   (Node 18+):

   ```json
   { "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:

```bash
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.

| Tool | One-line purpose | Capability skill |
|---|---|---|
| `plungeai_whoami` | The authenticated identity, tier, key label, rate window | this skill |
| `plungeai_list_agents` | Search the live agent registry (semantic); fetch one full card | `plungeai-discovery` |
| `plungeai_get_tool_contract` | Exact invocation contract for one agent: schema, operations, credential status | `plungeai-discovery` |
| `plungeai_execute_agent` | Run one prompt-driven agent once | `plungeai-agents` |
| `plungeai_execute_tool` | Run one structured tool-agent with typed `{agent_id, operation, params}` | `plungeai-tools-connectors` |
| `plungeai_get_result` | Fetch a run's output by execution id; `task_id` reads a single step | `plungeai-results-traces` |
| `plungeai_execute_workflow` | Run a saved workflow or ad-hoc CNL YAML; sync streams, async polls | `plungeai-workflows` |
| `plungeai_get_workflow_status` | Poll a run: status, error, duration, `continuation` when paused | `plungeai-workflows` |
| `plungeai_list_workflows` | The user's saved workflows | `plungeai-workflows` |
| `plungeai_workflow` | Workflow CRUD + versioning | `plungeai-workflows` |
| `plungeai_build_workflow` | Generate a workflow from a goal, or refine one | `plungeai-workflows` |
| `plungeai_executions` | Execution history: list/get/output/conversation/delete | `plungeai-results-traces` |
| `plungeai_chat` | Persistent chat with the platform assistant | `plungeai-results-traces` |
| `plungeai_followup` | Ask a follow-up on a completed run | `plungeai-results-traces` |
| `plungeai_continue` | Resume a paused run: answer a question or deliver approval | this skill (above) |
| `plungeai_run_mission` | Bounded autonomous agent mission (tool fence, iteration cap) | `plungeai-missions` |
| `plungeai_learn` | Distill a URL/text/session into a reusable private skill | `plungeai-memory` |
| `plungeai_schedule` | Cron jobs: stats/list/get/create/update/pause/resume/delete/run_now/runs | `plungeai-scheduling` |
| `plungeai_memory` | Long-term memory: recall/remember/search_runs/get_run | `plungeai-memory` |
| `plungeai_templates` | Workflow templates: list/get/use | `plungeai-workflows` |

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

| Symptom | Cause → fix |
|---|---|
| 401 (`Bearer ozk_ key required`) | Key typo'd, pasted with whitespace, or header never sent → fix the header in the client's config |
| Connected, no `plungeai_*` tools — or fewer than expected | Client not reloaded after the config edit, or the key is fenced to a subset (`allowed_tools`): policy, not a bug |
| 405 or an immediate connect error | Client is SSE-only or stdio-only (`GET /mcp` answers 405 at once) → use the mcp-remote bridge |
| Bridge "never appears" / times out | npx cold start exceeded the client's startup timeout, or Node.js is missing |
| 401 only through the bridge | Client mangled the spaces in `--header` → use `Authorization:${AUTH_HEADER}` + `env` (above) |
| Works for one teammate, not another | Separate keys, separate fences — per-machine config |
| 403 `refused` / 409 `approval_required` | Trust fence, not a connection problem — relay to the user |

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

- `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.