Hermes.Server.Transport.StreamableHTTP.Plug (hermes_mcp v0.10.1)

A Plug implementation for the Streamable HTTP transport.

This plug handles the MCP Streamable HTTP protocol as specified in MCP 2025-03-26. It provides a single endpoint that supports both GET and POST methods:

  • GET: Opens an SSE stream for server-to-client communication
  • POST: Handles JSON-RPC messages from client to server
  • DELETE: Closes a session

SSE Streaming Architecture

This Plug delegates SSE streaming to Hermes.SSE.Streaming which keeps the request process alive and handles the streaming loop.

Usage in Phoenix Router

pipeline :mcp do
  plug :accepts, ["json"]
end

scope "/mcp" do
  pipe_through :mcp
  forward "/", to: Hermes.Server.Transport.StreamableHTTP.Plug, server: :your_server_name
end

Usage in Plug Router

forward "/mcp", to: Hermes.Server.Transport.StreamableHTTP.Plug, init_opts: [server: :your_server_name]

Configuration Options

  • :server - The server process name (required)
  • :session_header - Custom header name for session ID (default: "mcp-session-id")
  • :timeout - Request timeout in milliseconds (default: 30000)
  • :registry - The registry to use. See Hermes.Server.Registry.Adapter for more information (default: Hermes.Server.Registry)

Security Features

  • Origin header validation for DNS rebinding protection
  • Session-based request validation
  • Automatic session cleanup on connection loss
  • Rate limiting support (when configured)

HTTP Response Codes

  • 200: Successful request
  • 202: Accepted (for notifications and responses)
  • 400: Bad request (malformed JSON-RPC)
  • 404: Session not found
  • 405: Method not allowed
  • 500: Internal server error