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

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

<Note>
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.
</Note>

## 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](/mcp-reference/protocol/initialize).

<!-- SERVER_VERSION and PROTOCOL_VERSION: orchestration/mcp-gateway/server.ts:75-80. -->

## 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](/mcp-reference/tools/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:

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