Hermes.Server.Supervisor (hermes_mcp v0.10.0)

Supervisor for MCP server processes.

This supervisor manages the lifecycle of an MCP server, including:

  • The Base server process that handles MCP protocol
  • The transport layer (STDIO, StreamableHTTP, or SSE)
  • Session supervisors for StreamableHTTP transport

The supervision strategy is :one_for_all, meaning if any child process crashes, all processes are restarted to maintain consistency.

Conditional Startup

The supervisor intelligently handles startup based on transport type:

  • STDIO transport: Always starts
  • StreamableHTTP/SSE transport: Conditional startup based on:
    1. Explicit :start option in transport config (highest priority)
    2. HERMES_MCP_SERVER environment variable present
    3. PHX_SERVER environment variable present, for phoenix apps using releases
    4. Phoenix :serve_endpoints internalr runtime config (usage with mix phx.server)
    5. Default: true (starts by default in production releases)

This ensures MCP servers start correctly in all environments:

  • Mix releases: Use PHX_SERVER=true or HERMES_MCP_SERVER=true
  • Development: Use mix phx.server
  • Tests/Tasks: Servers don't start unless explicitly configured

Configuration Examples

# Force start with transport option (highest priority)
{MyServer, transport: {:streamable_http, start: true}}

# Control via environment variables (works in releases)
PHX_SERVER=true ./my_app start

Supervision Tree

For STDIO transport:

Supervisor
├── Base Server
└── STDIO Transport

For StreamableHTTP transport:

Supervisor
├── Session.Supervisor
├── Base Server
└── StreamableHTTP Transport

Summary

Types

sse()
start_option()
stream_http()
transport()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

start_link(server, init_arg, opts)

Starts the server supervisor.

Types

sse()

@type sse() :: {:sse, keyword()}

start_option()

@type start_option() :: {:transport, transport()} | {:name, Supervisor.name()}

stream_http()

@type stream_http() :: {:streamable_http, keyword()}

transport()

@type transport() :: :stdio | stream_http() | sse() | StubTransport

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

start_link(server, init_arg, opts)

@spec start_link(server :: module(), init_arg :: term(), [start_option()]) ::
  Supervisor.on_start()

Starts the server supervisor.

Parameters

  • server - The module implementing Hermes.Server.Behaviour
  • init_arg - Argument passed to the server's init/1 callback
  • opts - Options including:
    • :transport - Transport configuration (required)
    • :name - Supervisor name (optional, defaults to registered name)
    • :registry - The custom registry to use to manage processes names (defaults to Hermes.Server.Registry)

Examples

# Start with STDIO transport
Hermes.Server.Supervisor.start_link(MyServer, [], transport: :stdio)

# Start with StreamableHTTP transport
Hermes.Server.Supervisor.start_link(MyServer, [],
  transport: {:streamable_http, port: 8080}
)