Server
MCP server overview
Endpoint, versions, auth and sessions.
The PlungeAI MCP server exposes 20 plungeai_* tools, one prompt, five resources and three resource templates to any MCP client. This tab documents every tool, resource and protocol method: the tool, resource and prompt pages are generated from the server code; this overview and the protocol pages are written from the MCP guide.
Endpoint
| Item | Value |
|---|---|
| URL | https://mcp.plungeai.com/v1 (/v1/ answers the same) |
| Legacy path | /mcp on the same host still answers with the same handler; configure /v1 |
| Methods | POST with JSON-RPC 2.0. GET and DELETE without a session answer 405 |
| Request headers | Authorization: Bearer $PLUNGE_API_KEY or X-API-Key: $PLUNGE_API_KEY, Content-Type: application/json, Accept: application/json, text/event-stream |
| Responses | application/json; tools/call answers as text/event-stream; a notification alone answers 202 with no body |
The docs site's own MCP server (docs.plungeai.com/mcp, planned as TI-35) is a different server. Its resources use the plungeai-docs:// scheme, so they never collide with this server's plungeai:// URIs.
Versions
The server version is 2.5.1 and it implements MCP revision 2025-11-25. It negotiates down to 2024-11-05: a client that sends 2025-06-18, 2025-03-26, 2024-11-05 or 2024-10-07 in initialize gets that version back, and any other value gets 2025-11-25. After initialize you may send MCP-Protocol-Version; an unsupported value answers 400, and leaving the header out is fine. See initialize.
Authentication and key fences
Every request needs an ozk_ key, tools/list included; create one at Dashboard → One API → Keys. Key fences are set by PlungeAI on request. A key fenced to some tools does not see the others in tools/list, and a tools/call to one of them answers JSON-RPC -32602 Tool not permitted for this key: <name>. Check your identity and tier with plungeai_whoami.
Stateless requests and sessions
Each POST gets a fresh server instance and stands alone: no Mcp-Session-Id is issued and none is needed. Because nothing is kept between requests, notifications/tools/list_changed is never sent, logging/setLevel is not persisted and a dropped tools/call stream is not replayed (the run keeps going; read it with plungeai_get_result). Stateful sessions exist only on keys PlungeAI issues with sessions enabled: initialize then returns an Mcp-Session-Id header to send on every later request, and a session expires after 10 minutes without a request.
Batches
A JSON array of messages is answered as an array, one answer per message:
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":"ping"},{"jsonrpc":"2.0","id":2,"method":"prompts/list"}]'A batch that contains initialize with other messages answers 400 -32600, and a batch with a tools/call is answered as SSE.
Ignored and rejected methods
| Method | What happens |
|---|---|
notifications/cancelled | Ignored: 202. To stop a run, call plungeai_executions with {"action":"cancel"} |
resources/subscribe, resources/unsubscribe, completion/complete | Rejected: -32601 Method not found |
| Any other method | Rejected: -32601 Method not found |
The server never sends requests to your client: no sampling, elicitation or roots.
Errors
Protocol errors mean the request never reached a tool. The body is always {"jsonrpc":"2.0","error":{"code":…,"message":"…"},"id":…}.
| HTTP | Code | When |
|---|---|---|
| 400 | -32700 | The body is not valid JSON, or not a JSON-RPC message |
| 400 | -32600 | A batch holding initialize plus other messages |
| 400 | -32000 | An unsupported MCP-Protocol-Version header after initialize |
| 401 | -32001 | No key, or a wrong, revoked or expired key, or a bearer that does not start with ozk_ |
| 404 | -32001 | An Mcp-Session-Id that is unknown or expired |
| 405 | -32000 | GET or DELETE without a session |
| 413 | -32600 | A body over 1 MiB |
| 415 | -32000 | A complete Accept header with a non-JSON Content-Type |
| 429 | -32000 | Rate limit reached; Retry-After and error.data.retryAfter give the seconds |
| 200 | -32602 | Unknown tool, a tool your key is fenced from, malformed initialize params, or an unknown prompt |
| 200 | -32002 | resources/read for an unknown resource, workflow or execution |
| 200 | -32601 | A method the server does not implement |
| 500 | -32603 | An unhandled server error |
Tool failures are not protocol errors: execution tools answer with an outcome (ok, needs_input, needs_connection, needs_api_key, needs_approval, unavailable or error) inside a normal result.
Helper routes
| Route | Key | Returns |
|---|---|---|
GET https://mcp.plungeai.com/v1/info | no | Server name plungeai.com, version, protocol version and capabilities |
GET https://mcp.plungeai.com/health | no | Dependency probes; 200 when healthy, 503 when one fails |
Recurring parameters
Two arguments appear on many tool pages and mean the same thing everywhere:
| Argument | On | Meaning |
|---|---|---|
user_request | Every tool | The user's request in their own words, up to 4,000 characters, optional. Always send it: the platform uses it for context and routing |
format | Nine tools | markdown (the default) or json; json returns the same answer as a JSON document and as structuredContent |