haproxy.cfg

# SCALE-002 / SCALE-003 — Sticky-Session Load Balancing for Streamable HTTP
#
# Streamable-HTTP MCP sessions are stateful: follow-up requests carry an
# `Mcp-Session-Id` header and MUST reach the backend instance that created the
# session. Phase 1 runs as a SINGLE instance (no LB needed). This config is the
# reference for the multi-instance scaling path: it routes by `Mcp-Session-Id`
# via a stick-table so a session always lands on the same backend, with an
# explicit TTL aligned to the session lifetime.

global
    log stdout format raw local0
    maxconn 4096

defaults
    mode http
    log global
    option httplog
    timeout connect 5s
    timeout client  120s          # SSE/streamable responses are long-lived
    timeout server  120s
    timeout tunnel  1h            # keep streaming connections open

frontend mcp_in
    bind *:8080
    default_backend mcp_backends

backend mcp_backends
    balance roundrobin

    # Stick-table keyed on the Mcp-Session-Id header.
    # expire == session TTL (keep in sync with the server's session lifetime);
    # size 100k supports ~100k concurrent sessions (SCALE-003).
    stick-table type string len 64 size 100k expire 30m
    stick on req.hdr(Mcp-Session-Id)

    # Health check hits the dedicated /healthz endpoint (see SCALE-004).
    option httpchk GET /healthz

    server mcp1 10.0.0.11:8000 check
    server mcp2 10.0.0.12:8000 check
    # add further replicas here; sticky routing keeps each session on one backend