> ## 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 plane > The MCP plane is bidirectional: inbound, the platform *is* an MCP server you point a client at; outbound, you connect the platform to *other* MCP servers and call their tools during a run. Both use an ozk_ key (Authentication). Base URL is https://api.plungeai.com. Source: … The MCP plane is bidirectional: **inbound**, the platform *is* an MCP server you point a client at; **outbound**, you connect the platform to *other* MCP servers and call their tools during a run. Both use an `ozk_` key ([Authentication](/one-api/authentication)). Base URL is `https://api.plungeai.com`. Source: `orchestration/api-gateway/routes/mcp.ts`, `orchestration/mcp-gateway/`, `orchestration/mcp-executor/`. ## 11.1 Inbound — the platform as an MCP server `POST /v1/mcp` is a Streamable-HTTP MCP endpoint that forwards your `ozk_` key to the mcp-gateway, which validates it again (the key's `allowed_tools`, `rate_limit` and `allowed_ips` apply). It is **stateless** — no `Mcp-Session-Id` is required (send one and it is forwarded). Authenticate with an `ozk_` bearer. It speaks plain JSON-RPC: `initialize`, then `tools/list` / `tools/call`. Protocol version `2025-11-25`; the older revisions `2025-06-18`, `2025-03-26`, `2024-11-05` and `2024-10-07` are negotiated ([MCP developer guide](https://mcp.plungeai.com/docs#43-protocol-version-and-initialize)). `https://mcp.plungeai.com/v1` is the **same** MCP server (the gateway's own hostname); `https://api.plungeai.com/v1/mcp` is the One API route to it with an `ozk_` bearer. Use whichever your client makes easiest. A convenience listing: a plain `GET`, no JSON-RPC to write. The answer is still the JSON-RPC `tools/list` envelope, so the tools are under `result.tools`: ```bash curl -s "https://api.plungeai.com/v1/mcp/tools" \ -H "Authorization: Bearer $PLUNGE_API_KEY" \ -H 'Accept: application/json' ``` The same over JSON-RPC (what an MCP client sends): ```bash curl -s "https://api.plungeai.com/v1/mcp" \ -H "Authorization: Bearer $PLUNGE_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' ``` ### The 20 `plungeai_*` tools `tools/list` returns 20 tools (live-verified 2026-09-18), in this order (`orchestration/mcp-gateway/server.ts`): | Tool | One line | |---|---| | `plungeai_execute_workflow` | run a CNL workflow (saved id or ad-hoc YAML); `mode:"async"` for long runs | | `plungeai_execute_agent` | run one prompt-driven agent (e.g. `one-agent`), optionally with a `session_id` | | `plungeai_get_tool_contract` | the exact invocation contract for one agent (params schema, operations, live credential status) | | `plungeai_execute_tool` | run one structured tool-agent with typed `{agent_id, operation?, params}` | | `plungeai_run_mission` | run a bounded autonomous mission (goal + optional fence/iteration cap); async by default | | `plungeai_learn` | manage your private skill library — `learn` / `list` / `forget` | | `plungeai_list_agents` | discover platform building-block agents (the capability registry) | | `plungeai_list_workflows` | list **your saved workflows** (what users call "my agents") | | `plungeai_get_result` | fetch one execution's result (full conversation thread for chat runs) | | `plungeai_get_workflow_status` | check an execution's status; returns a `continuation` when paused | | `plungeai_workflow` | manage workflows — create/get/update/delete/versions | | `plungeai_executions` | browse execution history — list/get/output/conversation/delete | | `plungeai_followup` | ask a follow-up about a completed execution | | `plungeai_continue` | continue a paused run — answer (`message`) or approve (`approve:true`) | | `plungeai_chat` | persistent chat with the platform assistant — send/new/list_sessions/history | | `plungeai_build_workflow` | generate or refine a saved workflow from a goal | | `plungeai_memory` | long-term memory scoped to you — recall/remember/search_runs/get_run | | `plungeai_templates` | workflow templates — list/get/use | | `plungeai_schedule` | scheduled (cron) jobs — stats/list/get/create/update/pause/resume/delete/run_now/runs | | `plungeai_whoami` | the authenticated identity — user id, tier, key label, rate-limit window | Every parameter of every tool, with a `tools/call` example: [Tool reference](https://mcp.plungeai.com/docs#14-tool-reference). Outcomes, JSON-RPC errors, HTTP statuses and limits: [Errors, feedback & limits](https://mcp.plungeai.com/docs#13-errors-feedback--limits). ### Connecting a client - **Claude Code** (one command): `claude mcp add --transport http plungeai https://mcp.plungeai.com/v1 --header "Authorization: Bearer "` - **Cursor / VS Code / JSON-configured clients** — an `.mcp.json` server entry with `"url": "https://mcp.plungeai.com/v1"` and an `Authorization: Bearer` header. - **Claude Desktop** — the connector UI cannot set a bearer header, so bridge with `mcp-remote https://mcp.plungeai.com/v1 --header "Authorization: Bearer "`. **claude.ai (web)** gets a PlungeAI skill upload only, with no live tools ([Connecting clients](https://mcp.plungeai.com/docs#33-claudeai-and-claude-desktop)). - **Any client** — point it at either URL; it is plain JSON-RPC over Streamable HTTP. The install page `https://www.plungeai.com/install` generates ready-made config. - **Every supported client**, with its config and how to verify it: [Connecting clients](https://mcp.plungeai.com/docs#3-connecting-clients). ## 11.2 Outbound — MCP runs against other servers The outbound surface connects the platform to registry MCP servers, lists their tools, calls them, and tears the run down. Secrets are resolved **server-side** in the mcp-executor (never in your request): `${VAR}` → a platform secret; `${{ credentials. }}` → the acting user's BYOK key / OAuth token, a miss becoming a structured `needs_connection` (`orchestration/mcp-executor/CLAUDE.md`). Each run is a per-tenant Durable Object keyed `customerUuid:runId`; background runs are held in resumable ~10-minute legs (the Ten-Minute Relay). Discover connectable servers with `GET /v1/discovery/search?kind=mcp-servers` ([Discovery](/one-api/discovery)). | Route | Body | Returns | |---|---|---| | `POST /v1/mcp/runs` | `{ "server_ids": ["", …] }` (non-empty string array) | `201 { run_id, tools, connected, failed, warnings, skipped }` | | `GET /v1/mcp/runs/:id/tools` | — | `{ tools, count }` | | `POST /v1/mcp/runs/:id/call` | `{ "name": "mcp____", "args"?: {…}, "timeout_ms"?: n }` | `{ content }` | | `DELETE /v1/mcp/runs/:id` | — | `{ success: true }` | Notes: - `server_ids` are registry `mcp-server` catalog ids — **not** arbitrary URLs; the executor resolves each server's manifest and credentials. No `url`/`auth` is accepted in the body. - Tool names are namespaced `mcp____` so the loop's fence and per-tool permissions apply to MCP tools like native ones. - A server that just failed is skipped for the next run for 60s (per-tenant cooldown → `skipped`). If none connect → `502 no_servers_connected` with `failed`/`warnings`/`skipped`. A tool call that fails → `502 tool_call_failed`; a missing `name` → `400 invalid_body`. - Always `DELETE` the run when done (the DO also self-cleans a stale run). A full cycle against the credential-free `cloudflare-docs` server — create, list tools, delete: ```bash RID=$(curl -s "https://api.plungeai.com/v1/mcp/runs" \ -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \ -d '{"server_ids":["cloudflare-docs"]}' \ | sed -n 's/.*"run_id":"\([^"]*\)".*/\1/p') echo "run_id=$RID" curl -s "https://api.plungeai.com/v1/mcp/runs/$RID/tools" \ -H "Authorization: Bearer $PLUNGE_API_KEY" echo curl -s -X DELETE "https://api.plungeai.com/v1/mcp/runs/$RID" \ -H "Authorization: Bearer $PLUNGE_API_KEY" ``` To **call** a tool on the run (not run here — it does real work): ```bash # not run here curl -s "https://api.plungeai.com/v1/mcp/runs//call" \ -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \ -d '{"name":"mcp__cloudflare-docs__search_cloudflare_documentation","args":{"query":"durable objects"}}' ``` ## 11.3 MCP servers inside a harness mission Outbound runs are the *manual* surface. Inside a bounded mission, list the servers on the task's `mcp:` field and the loop host connects them for the run (through the same mcp-executor), exposing their tools to the agent under the fence. See [Skills, plugins & capability injection](/one-api/skills-plugins-capabilities) for the `mcp:` field and a full `type: harness` example, and the [Workflows plane](/one-api/workflows) for running it. In-loop MCP is the inbound path for our agents; the `POST /v1/mcp` endpoint above is the outbound control plane for external clients — the two never cross.