Hermes.Server.Transport.SSE.Plug (hermes_mcp v0.9.0)

A Plug implementation for the SSE (Server-Sent Events) transport.

This plug handles the MCP HTTP+SSE protocol as specified in MCP 2024-11-05. It provides two separate endpoints:

• SSE endpoint: Opens an SSE stream and sends "endpoint" event
• POST endpoint: Handles JSON-RPC messages from client to server

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", "event-stream"]
end

scope "/mcp" do
  pipe_through :mcp

  # SSE endpoint
  get "/sse", Hermes.Server.Transport.SSE.Plug, 
    server: :your_server_name, mode: :sse

  # POST endpoint
  post "/messages", Hermes.Server.Transport.SSE.Plug,
    server: :your_server_name, mode: :post
end

Usage in Plug Router (Standalone)

# When using in a standalone Plug.Router app
plug Hermes.Server.Transport.SSE.Plug,
  server: :your_server_name,
  mode: :sse,
  at: "/sse",
  method_whitelist: ["GET"]

plug Hermes.Server.Transport.SSE.Plug,
  server: :your_server_name,
  mode: :post,
  at: "/messages",
  method_whitelist: ["POST"]

Configuration Options

• :server - The server process name (required)
• :mode - Either :sse or :post to determine endpoint behavior (required)
• :timeout - Request timeout in milliseconds (default: 30000)

Security Features

• Origin header validation for DNS rebinding protection
• Session-based request validation
• Automatic session cleanup on connection loss

HTTP Response Codes

• 200: Successful request or SSE stream established
• 202: Accepted (for notifications)
• 400: Bad request (malformed JSON-RPC)
• 405: Method not allowed
• 500: Internal server error