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: 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 (opens in a new tab)).

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:

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

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 (opens in a new tab). Outcomes, JSON-RPC errors, HTTP statuses and limits: Errors, feedback & limits (opens in a new tab).

Connecting a client

Claude Code (one command): claude mcp add --transport http plungeai https://mcp.plungeai.com/v1 --header "Authorization: Bearer <ozk key>"
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 <ozk key>". claude.ai (web) gets a PlungeAI skill upload only, with no live tools (Connecting clients (opens in a new tab)).
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 (opens in a new tab).

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.<provider> }} → 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).

Route	Body	Returns
`POST /v1/mcp/runs`	`{ "server_ids": ["<id>", …] }` (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__<server>__<tool>", "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__<serverId>__<tool> 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:

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

# not run here
curl -s "https://api.plungeai.com/v1/mcp/runs/<run_id>/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 for the mcp: field and a full type: harness example, and the Workflows plane 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.

11.1 Inbound — the platform as an MCP server

The 20 plungeai_* tools

Connecting a client

11.2 Outbound — MCP runs against other servers

11.3 MCP servers inside a harness mission

The 20 `plungeai_*` tools