Model Context Protocol (MCP) server (REQ-MCP-01..REQ-MCP-04), over stdio here and over
Streamable HTTP in SuperPi.MCP.HTTPPlug.
Allows any MCP-compliant host (OpenCode, Claude Desktop, Cursor, Zed, Continue.dev) to connect to Super-Pi-BEAM as a standard tool and context provider.
handle_mcp_line/2 is pure: it takes one JSON-RPC message and the connection state and returns
the reply and the next state. The transports only move lines (stdio) or request bodies (HTTP).
Protocol versions
initialize answers the client's protocolVersion when the server speaks it (2025-06-18,
2025-03-26, 2024-11-05), else the newest. The requested version is logged at debug level,
which is how to find out what a host asks for. 2026-07-28 is not supported: it replaces
elicitation, sampling and roots with a different round trip.
Supported Methods
initialize- Handshake declaring tool, resource, and prompt capabilities.notifications/initialized- Post-handshake acknowledgment.ping- Heartbeat check.tools/list- The eight tools with JSON Schema and annotations (readOnlyHint,destructiveHint,idempotentHint,openWorldHint), which hosts use to decide what to approve without asking.tools/call- Runs a tool through the permission policy of the connection's harness. The result carriescontent(text) and, when the tool returns structured data,structuredContent.prompts/list&prompts/get- One prompt per harness (SuperPi.Harness.list/0), plus theplan_architecturealias.resources/list,resources/read- The workspace context, the tool loadout and the conversations that this connection started.resources/templates/list-superpi://conversation/{id}/transcript, whichresources/readanswers with the conversation transcript as JSON lines (the compact form thatSuperPi.Plugins.TranscriptLoggerwrites). A conversation of another principal is not found.
Choosing a harness
harness_task takes a harness argument (an id from Harness.list/0) and runs the task in
that harness. Direct tool calls (read, bash ...) run under the connection's harness: the
state key :harness, else config :super_pi, :mcp_harness, else Harness.default/0. The
workspace is the first of SuperPi.Discovery.default_workspace_paths/0.
Tools run in the mode that SuperPi.Plugins.Permissions.apply_remote_mode/2 allows a remote
caller. State keys: :harness, :principal (an SuperPi.Auth principal, default anonymous).
Summary
Functions
Handles a single raw MCP JSON-RPC 2.0 payload string. Pure handler suitable for unit tests and property testing.
The version to answer initialize with: the client's when supported, else the newest supported.
The client then decides whether it can speak that version (MCP lifecycle, version negotiation).
Runs the MCP server over standard input and output in a blocking loop.
Protocol versions this server speaks, newest first.
The eight tools with their input schema and annotations. harness_task lists the harness ids.
Functions
Handles a single raw MCP JSON-RPC 2.0 payload string. Pure handler suitable for unit tests and property testing.
The version to answer initialize with: the client's when supported, else the newest supported.
The client then decides whether it can speak that version (MCP lifecycle, version negotiation).
Runs the MCP server over standard input and output in a blocking loop.
Protocol versions this server speaks, newest first.
The eight tools with their input schema and annotations. harness_task lists the harness ids.