Sessionplan

npx add-mcp 'https://sessionplan.de/mcp'

Sessionplan MCP Interface

Endpoint: https://sessionplan.de/mcp/

The server creates and decodes immutable Sessionplan snapshot links. It processes session data in memory and does not persist it as a server-side workshop. No account or authentication is required. Snapshot analytics record the endpoint and operation; snapshot input and referrers are excluded from those events.

Workflow and data contract

• New plan: call create_session_link with a complete session.
• Existing snapshot: call decode_session_link before reading, summarizing or editing it. Use structuredContent.session as the source of truth.
• Changes: submit the complete updated session to create_session_link. Patches and partial updates are not supported.
• Return structuredContent.link verbatim. Do not reconstruct, shorten, normalize or edit the snapshot URL.
• Dynamic server links and legacy pre-v2 snapshot codes are not supported by these tools; supply a #data=v2:... snapshot link instead.

The canonical JSON Schema is embedded in the create_session_link input schema. The import guide describes its fields and provides complete examples. The HTTP API guide explains the equivalent REST operations.

Top-level items may be blocks, groups or breakouts. Groups contain blocks or breakouts; breakouts contain blocks. Blocks have no children field. Containers include a children array. Do not generate other container nesting.

IDs must be unique within their collection; item IDs must be unique across the complete tree. Declare every referenced block type and person in blockTypes and persons, including persons assigned through lanePersons. Child lane indices must fit the parent breakout (lanes ranges from 1 to 10 and defaults to 2, laneIndex defaults to 0). With sameInAllBreakouts: true, children must use lane zero. lanePersons is always a JSON object, including {}. Always include version, workshop, blockTypes, persons and items. Use empty arrays for unused category/person lists and empty strings for unused description, notes and material fields. Use blockTypeId: null when no category is assigned. Workshop date and startTime are optional; use null when unset. Only generate documented fields and valid dates/times.

The server handles older documents tolerantly. This compatibility behavior is not the format to target when generating new documents. The decoder response schema accommodates preserved legacy data; use the canonical input schema when creating or revising a session.

Transport and limits

• JSON-RPC 2.0 over Streamable HTTP. Send each message in its own POST.
• Use Content-Type: application/json and Accept: application/json, text/event-stream.
• This server answers synchronously with JSON; it does not open SSE streams.
• Accepted notifications receive HTTP 202 with an empty body.
• GET without an SSE Accept header returns a health response. A GET requesting text/event-stream receives 405.
• OPTIONS receives 204; invalid origins receive 403.
• Responses use Content-Type: application/json; charset=utf-8, Cache-Control: no-store, and X-Content-Type-Options: nosniff.
• POST requests are limited to 60 per 60-second window per IP for this endpoint. A 429 response includes Retry-After: 60.
• Request bodies and uncompressed session JSON are each limited to 2,000,000 bytes.
• The compressed payload after v2: is limited to 750,000 characters.
• The complete tree may contain at most 500 items, including containers and all children, not just top-level items.
• The codec additionally bounds its UTF-16 working output to 4,000,000 bytes and its dictionary to 65,536 entries / 8,000,000 bytes of entry content. Exceeding a codec budget produces a controlled size error. Passing a byte limit alone does not guarantee that an input fits all budgets or a client's URL/message limits.

Allowed browser origin: https://sessionplan.de. With SP_ENV=development, HTTP(S) localhost and 127.0.0.1 origins with optional ports are also allowed. Clients without an Origin header are accepted.

Protocol versions

Supported revisions:

• 2026-07-28: per-request metadata and server/discover.
• 2025-11-25, 2025-06-18, 2025-03-26: legacy initialize handshake.

The document's version: "1.0", link prefix v2:, MCP protocol revision and server implementation version are separate version identifiers.

Modern requests: 2026-07-28

Every request must carry the protocol version in both the HTTP header and params._meta. The values must agree. Required headers:

Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list

Matching request body:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

For tools/call, set Mcp-Method: tools/call and Mcp-Name to params.name. Use the same _meta on discovery and tool calls. Missing or mismatched headers produce HTTP 400, JSON-RPC code -32020 (HeaderMismatch).

server/discover returns resultType: "complete", supportedVersions: ["2026-07-28"], capabilities: {"tools": {}}, workflow instructions, and server identity in _meta["io.modelcontextprotocol/serverInfo"]. Server icons use mimeType: "image/png" and sizes: ["512x512"].

Modern discovery and tool-list results include ttlMs: 3600000 and cacheScope: "public" as MCP application-level cache hints. HTTP responses still use no-store. Tool success and tool error results include resultType: "complete". initialize is unavailable in the modern revision and returns HTTP 404.

Legacy requests

Start with initialize:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}

The server returns the requested supported legacy version, otherwise 2025-11-25. Send notifications/initialized without an id, then call tools. Use the negotiated MCP-Protocol-Version header on subsequent requests. The server is stateless and issues no Mcp-Session-Id. Legacy requests without a version header are accepted for backward compatibility; modern body metadata still requires matching modern headers.

Legacy ping receives {"jsonrpc":"2.0","id":1,"result":{}} for request ID 1. server/discover is unavailable for legacy requests.

Tools

tools/list returns these tools, each with an English description, input schema, output schema and explicit boolean annotations:

Tool	readOnlyHint	destructiveHint	idempotentHint	openWorldHint
create_session_link	true	false	true	false
decode_session_link	true	false	true	false

• Both tools only transform or read the supplied snapshot in memory. They do not persist or modify a workshop, and identical valid input produces the same result without creating a server-side resource. Decoding never fetches a user-supplied URL; it reads only the snapshot embedded in the supplied string.
• Neither tool deletes, overwrites, or changes an existing Sessionplan snapshot: snapshots are immutable URL fragments and no workshop document is persisted by the MCP service. destructiveHint is consequently false for both tools.

create_session_link

Arguments: { "session": <complete Sessionplan document> }.

On success, result.structuredContent contains:

{
  "link": "https://sessionplan.de/#data=v2:...",
  "summary": { "title": "Workshop", "blockCount": 3, "totalDuration": 90 }
}

The link above is a placeholder, not an executable example. blockCount counts all block items recursively, excluding containers. totalDuration sums the explicit durations of top-level items once. It does not recalculate container durations from children and does not include gaps caused by fixedStartTime.

decode_session_link

Arguments: { "link": <complete snapshot URL, #data=v2:... hash, or v2:... code> }.

On success, result.structuredContent.session contains the complete validated session. Decoding does not fetch the supplied URL; it reads the embedded snapshot.

Both tools also serialize the structured result into the first text content block for clients without structured-result support. A second text block explains how to use the result. The structured result conforms to the advertised output schema.

Errors

JSON-RPC errors contain jsonrpc, the request id when known, and error: {code, message}. Unsupported-version errors additionally include error.data: {supported: [...], requested: "..."}. Modern errors without a known request ID omit id.

Situation	HTTP	Error
Invalid Origin	403	JSON-RPC -32600
Unsupported protocol version	400	JSON-RPC -32022
Missing/mismatched modern headers	400	JSON-RPC -32020
Unknown modern RPC method	404	JSON-RPC -32601
Unknown legacy RPC method or unknown tool	200	JSON-RPC -32601
Malformed JSON	200	JSON-RPC -32700
Invalid JSON-RPC envelope or request ID	200	JSON-RPC -32600
Invalid params, metadata or tool arguments	200	JSON-RPC -32602
Unexpected processing failure	200	JSON-RPC -32603
Request body too large	413	JSON-RPC -32600
Rate limit exceeded	429	JSON-RPC -32000, plus Retry-After: 60
Wrong HTTP method	405	{ "error": "Method not allowed" }
Wrong content type	415	{ "error": "Content-Type must be application/json" }
Rate-limit storage unavailable	503	JSON-RPC -32603

Validation, encoding and decoding failures are tool errors: HTTP 200 with result.isError: true and a text content block. They do not include a successful structuredContent result.

• SESSION_VALIDATION_FAILED: correct the indicated field or reduce the plan when a size limit was reached, then submit the complete session again.
• SESSION_DECODE_FAILED: check that the complete unmodified snapshot was supplied. A size-limit failure requires a smaller source plan.

Tool error details are whitespace-normalized and limited to 800 characters; stack traces are not returned. Structural errors identify the affected field.

Protocol reference: MCP 2026-07-28 Streamable HTTP.