Streamable HTTP

Start the server with HTTP selected explicitly:

npx mcp-failure-lab serve --transport http

The default endpoint is http://127.0.0.1:3000/mcp.

Configuration

Option	Default	Purpose
--transport	stdio	Select stdio or http.
--host	127.0.0.1	HTTP bind host.
--port	3000	HTTP listener port.
--path	/mcp	Streamable HTTP endpoint.

HTTP-specific options require --transport http. The host, port, and path are validated before the listener starts.

Protocol behavior

The endpoint serves MCP 2026-07-28 and 2025-11-25. Initialized legacy clients receive a server-issued session ID. Claimless legacy requests without initialization remain stateless for compatibility. Both paths use the same server factory and expose ping, delay, hang, disconnect, malformed_message, and duplicate_response.

The current working tree also registers protocol_ping_liveness. Server-to-client ping requires legacy 2025-11-25; modern calls report unsupported. Its optional failure closure interrupts the activating HTTP response stream using the same request context as disconnect. This does not invoke the session_loss controller. See protocol liveness for timing and reporting limits.

malformed_message changes only the activating request’s response. Modern JSON responses and legacy SSE response events use the same fault rules. Unrelated SSE events remain unchanged. See Fault Tools for variants and validation steps.

duplicate_response emits two SSE message events containing identical JSON-RPC payloads and the same request ID. This applies to modern and legacy HTTP requests. See Fault Tools for expected client behavior.

The current working-tree invalid_progress tool sends at most two request-scoped progress notifications. For after-completion, the notification follows the matching response event in the HTTP response stream, including for initialized legacy sessions. See Fault Tools for variants and cleanup limits.

Calling disconnect terminates its active HTTP request instead of returning a normal tool result. The listener remains available for later requests.

Legacy sessions also expose session_loss. It can invalidate the current session during its active request or after returning its result. Modern HTTP and stateless legacy requests do not expose it. See Fault Tools for activation modes and expected outcomes.

Local security boundary

The default loopback bind is intentional. Failure Lab validates the request path and the Host and Origin headers. Wildcard bind addresses are rejected because the server does not provide authentication or TLS.

Use a trusted reverse proxy if you need authentication, TLS termination, or access from another machine. Do not expose the endpoint directly to an untrusted network.

MCP Inspector

Run the HTTP server and Inspector in separate terminals:

npx mcp-failure-lab serve --transport http

npx @modelcontextprotocol/inspector@latest

Add a Streamable HTTP server with URL http://127.0.0.1:3000/mcp. If Inspector 2.4 times out while calling tools in Modern mode, use Legacy mode for manual UI checks. Modern 2026-07-28 remains covered through the direct HTTP integration path.

Press Ctrl+C in the server terminal for graceful shutdown.