fix(gunicorn): warn at startup when GUNICORN_WORKERS>1 breaks MCP sessions

MCP sessions live in a per-process in-memory dict on whatever worker
handled the initialize request (StreamableHTTPSessionManager._server_instances).
gunicorn round-robins HTTP requests across workers, so the same
mcp-session-id frequently lands on a different worker and returns
'Session not found' / 'Invalid or expired session ID'. fastapi-mcp
hardcodes stateless=False, and gunicorn has no built-in sticky-session
support, so there is no in-process workaround.

This change keeps the existing workers=2 default (the project does not
want to give up the modest parallelism it gives) but adds:

  * A comment block above workers= explaining the constraint, the
    workers=1 fix, and the nginx sticky-session escape hatch.
  * An on_starting(server) hook that logs a WARNING whenever
    workers > 1, naming the symptom and the fix so the misconfig is
    loud at deploy time rather than silent at request time.
  * Three regression tests in tests/unit/test_gunicorn_config.py
    asserting the hook exists, is silent for workers=1, and warns
    (with the expected text) for workers>1.
  * A 'MCP session affinity' note in CLAUDE.md key conventions so
    the constraint is recorded for future maintainers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

gunicorn.conf.py

@@ -22,11 +22,52 @@ bind = os.environ.get("GUNICORN_BIND", "0.0.0.0:8000")
 # 2 is a sensible default for a small containerized MCP server: lets a slow
 # yarn logs request run in parallel with a status check. Scale up by
 # setting GUNICORN_WORKERS at deploy time.
+#
+# ⚠️  MCP SESSION AFFINITY CONSTRAINT  ⚠️
+# ----------------------------------------
+# The official `mcp` library (used under fastapi-mcp) keeps each MCP
+# session's state in a per-process in-memory dict
+# (`StreamableHTTPSessionManager._server_instances`). gunicorn round-robins
+# HTTP requests across worker processes, so a client that does:
+#     1) POST /initialize     → worker A creates session_id=xyz
+#     2) POST /tools/list     → worker B has no record of xyz
+#     3) → "Session not found" / "Invalid or expired session ID"
+# gunicorn has no built-in sticky-session support, and fastapi-mcp hardcodes
+# `stateless=False`, so there is no in-process way to share sessions across
+# workers without an external store (Redis, etc.).
+#
+# Trade-off: `workers=1` eliminates the bug entirely. A single uvicorn-based
+# worker still handles many concurrent connections via the asyncio event
+# loop — the lost capacity is parallel CPU work, which this I/O-bound MCP
+# service rarely needs. If you ever need true multi-core parallelism, you
+# MUST front gunicorn with a sticky-session reverse proxy (nginx
+# `ip_hash` / `hash $mcp_session_id consistent`) AND give every session
+# a shared backing store — do NOT just bump GUNICORN_WORKERS.
+#
+# The `on_starting` hook below makes this footgun loud rather than silent.
 workers = int(os.environ.get("GUNICORN_WORKERS", "2"))
 worker_class = "uvicorn.workers.UvicornWorker"
 # 1 thread per worker is enough for ASGI handlers (no blocking I/O).
 threads = int(os.environ.get("GUNICORN_THREADS", "1"))
 
+
+def on_starting(server):
+    """Master-process hook: gunicorn calls this once before forking workers.
+
+    We use it to scream at anyone who raises GUNICORN_WORKERS above 1 without
+    putting a sticky-session LB in front — see the workers= comment above for
+    why MCP sessions cannot survive worker-local storage across processes.
+    """
+    if workers > 1:
+        server.log.warning(
+            "GUNICORN_WORKERS=%d — MCP sessions are stored in per-process "
+            "memory, so the same mcp-session-id will frequently land on a "
+            "different worker and return 'Session not found'. Either set "
+            "GUNICORN_WORKERS=1 or front this service with a sticky-session "
+            "reverse proxy (see gunicorn.conf.py for details).",
+            workers,
+        )
+
 # --- Lifecycle ---
 # Generous timeout because the slowest tool call here is yarn logs (which
 # can take 30+ seconds on a busy cluster). uvicorn standalone defaults to