From 9746c77fbb390710402a52a74898cf278911f607 Mon Sep 17 00:00:00 2001 From: Oscar Perez Date: Wed, 18 Nov 2026 14:36:28 +0100 Subject: [PATCH] feat(mcp)!: retire the legacy SSE transport; /sse serves Streamable HTTP The SSE transport kept each session in one worker's memory, so with 4 workers 72% of POST /messages/ reached a worker without the session and got a 404. It was already failing for the clients still on it. - GET /sse (the SSE handshake) and /messages/ answer 410 with the /mcp URL and the Claude Code and mcp-remote commands to switch. - /sse serves Streamable HTTP with its own protected-resource metadata, so clients that saved the old URL and try Streamable HTTP there first (Claude.ai: 11.9k such attempts in 48 h) keep working unchanged. - A Streamable HTTP GET on /sse (MCP-Protocol-Version set) gets the same 405 /mcp gives. - The /chatgpt graft is generalised and reused for /sse. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 + docs/HTTP_DEPLOYMENT.md | 6 +- docs/MCP.md | 2 +- src/late/mcp/constants.py | 12 ++-- src/late/mcp/http_server.py | 120 ++++++++++++++++++++-------------- tests/test_mcp_sse_retired.py | 91 ++++++++++++++++++++++++++ 6 files changed, 175 insertions(+), 59 deletions(-) create mode 100644 tests/test_mcp_sse_retired.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 41788522..20920726 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Removed +- **The hosted MCP server's legacy SSE transport (`GET /sse` + `POST /messages/`).** It kept each session in one worker's memory, so with 4 workers 72% of `POST /messages/` reached a worker without the session and got a 404: the transport was already failing for the clients still on it. Connect with Streamable HTTP at `https://mcp.zernio.com/mcp` (Claude Code: `claude mcp add --transport http zernio https://mcp.zernio.com/mcp`). The `/sse` URL now serves Streamable HTTP, so clients that saved it and try Streamable HTTP there first, Claude.ai among them, keep working with nothing to change. A legacy SSE handshake on `GET /sse` and any request to `/messages/` get a 410 whose body names the `/mcp` URL. + ### Changed - **The MCP server runs on FastMCP 4 and MCP SDK 2.** The `mcp` extra now needs Python 3.11 or later, as FastMCP 4 does: on Python 3.10 it installs without FastMCP and the MCP server cannot run. The SDK itself still supports 3.10. Behavior FastMCP 4 changed is kept: guessed tool names sent through `call_tool` get the closest tools again, a result holding half an emoji is repaired instead of failing the call, and a pydantic error inside a tool logs where and why it failed, never the response values. The protected-resource metadata override is gone, since MCP SDK 2 renders the issuer without a trailing slash. diff --git a/docs/HTTP_DEPLOYMENT.md b/docs/HTTP_DEPLOYMENT.md index 2adb5880..552019fe 100644 --- a/docs/HTTP_DEPLOYMENT.md +++ b/docs/HTTP_DEPLOYMENT.md @@ -4,7 +4,7 @@ The Zernio MCP server can be deployed over HTTP, allowing remote access from any MCP client. Each user provides their own Zernio API key when connecting. -The server's primary transport is **Streamable HTTP** (`POST /mcp`), the modern MCP transport supported by all current clients. Each request/response is self-contained (with optional chunked streaming), so it survives proxies and bridges that drop idle connections. The legacy SSE transport (`GET /sse` + `POST /messages/`) is kept for backward compatibility. +The server's primary transport is **Streamable HTTP** (`POST /mcp`), the modern MCP transport supported by all current clients. Each request/response is self-contained (with optional chunked streaming), so it survives proxies and bridges that drop idle connections. The legacy SSE transport (`GET /sse` + `POST /messages/`) is retired and answers 410 with the `/mcp` URL. `/sse` still serves Streamable HTTP, so clients that saved the old URL and speak Streamable HTTP there keep working. ## Quick Start @@ -70,7 +70,7 @@ Optional variables: - `SENTRY_DSN` — sends one transaction per tool call (`tools/call `) and unexpected errors to Sentry. Unset, nothing is sent. - `SENTRY_TRACES_SAMPLE_RATE` (default: 1.0) — share of tool calls traced in Sentry. - `AXIOM_TOKEN` and `AXIOM_DATASET` — with both set, every `mcp_tool_call` line below is also sent to that Axiom dataset, in batches every 5 s from a background thread, with `release` (commit), `environment` and `worker` (process id) added. Unset, nothing is sent. The token needs ingest permission on that dataset only. A failed batch is dropped and logged, never retried, and never slows a tool call; when more than 20,000 lines wait, new ones are dropped and counted in an `mcp_axiom_dropped` event. -- `WEB_CONCURRENCY` (default: 1) — number of server processes. One process uses one CPU core at most. Above 1, `/health` returns 503 until every process is up, and legacy `/sse` breaks: its `/messages` POSTs can reach a process that does not hold the stream. +- `WEB_CONCURRENCY` (default: 1) — number of server processes. One process uses one CPU core at most. Above 1, `/health` returns 503 until every process is up. ## Logging @@ -146,7 +146,7 @@ The server is an OAuth 2.0 **resource server** (FastMCP's resource-server model) - No shared credentials or server-wide API keys - Browser requests are checked against an Origin allowlist for DNS-rebinding protection (extend with `MCP_ALLOWED_ORIGINS`) - Health check, server info, and OAuth discovery endpoints are public (no auth required) -- The MCP and legacy SSE endpoints require authentication +- The MCP endpoints (`/mcp`, `/sse`, `/chatgpt`) require authentication ## Get Your Zernio API Key diff --git a/docs/MCP.md b/docs/MCP.md index dc33d871..0db6450d 100644 --- a/docs/MCP.md +++ b/docs/MCP.md @@ -106,6 +106,6 @@ An unknown name in `?tools=` makes `tools/list` fail with the closest real names ## Remote Access (HTTP) -The remote MCP server speaks **Streamable HTTP** (`POST /mcp`) — the modern single-endpoint transport supported by all current MCP clients. It survives idle timeouts on proxies and bridges like `mcp-remote`. The legacy SSE transport (`GET /sse`) is kept for backward compatibility. +The remote MCP server speaks **Streamable HTTP** (`POST /mcp`) — the modern single-endpoint transport supported by all current MCP clients. It survives idle timeouts on proxies and bridges like `mcp-remote`. The legacy SSE transport is retired: `GET /sse` answers 410 with the `/mcp` URL, and `/sse` serves Streamable HTTP for clients that saved the old URL. For deployment and client setup, see the [HTTP Deployment Guide](HTTP_DEPLOYMENT.md). diff --git a/src/late/mcp/constants.py b/src/late/mcp/constants.py index 3898a59b..80437f74 100644 --- a/src/late/mcp/constants.py +++ b/src/late/mcp/constants.py @@ -5,12 +5,10 @@ # Server information SERVICE_NAME = "Zernio MCP Server" SERVICE_VERSION = "1.2.9" -# Streamable HTTP is the primary transport (single endpoint, request/response +# Streamable HTTP is the only transport (single endpoint, request/response # with optional chunked streaming — no long-idle connection for proxies or -# bridges like mcp-remote to kill). Legacy SSE is still served for backwards -# compatibility: production continues to receive GET /sse connections from -# older client configs. New clients should use Streamable HTTP. -TRANSPORT_TYPE = "sse+streamable-http" +# bridges like mcp-remote to kill). The legacy SSE transport is retired. +TRANSPORT_TYPE = "streamable-http" # Default server configuration DEFAULT_HOST = "0.0.0.0" @@ -24,8 +22,8 @@ ENDPOINT_ROOT = "/" ENDPOINT_HEALTH = "/health" ENDPOINT_MCP = "/mcp" -# Legacy SSE transport (two-endpoint protocol: GET /sse + POST /messages/), -# deprecated but kept for backwards compatibility with older client configs. +# The retired SSE transport's paths. /sse serves Streamable HTTP for clients +# that saved the old URL; the SSE handshake and /messages/ answer 410. ENDPOINT_SSE = "/sse" ENDPOINT_MESSAGES = "/messages/" # ChatGPT plugin surface (late.mcp.chatgpt_server): a curated tool set on its diff --git a/src/late/mcp/http_server.py b/src/late/mcp/http_server.py index 6085dc12..ace1b523 100644 --- a/src/late/mcp/http_server.py +++ b/src/late/mcp/http_server.py @@ -1,4 +1,4 @@ -"""HTTP server for Zernio MCP — Streamable HTTP (+ legacy SSE) on FastMCP. +"""HTTP server for Zernio MCP — Streamable HTTP on FastMCP. Serves the FastMCP application (tool-search transform + OAuth resource-server auth) over Streamable HTTP at /mcp. Authentication, the RFC 9728 @@ -7,11 +7,12 @@ Origin protection is layered on as a lightweight ASGI middleware, scoped to the transport endpoints so the public /health, / and discovery routes stay open. -The legacy SSE transport (GET /sse + POST /messages/) is deprecated but still -served for backwards compatibility — production continues to receive SSE -connections from older client configs. Its routes come from the same FastMCP -instance (mcp.http_app(transport="sse")), so tools and auth are identical to -the Streamable HTTP endpoint. +The legacy SSE transport (GET /sse + POST /messages/) is retired: its sessions +lived in one worker's memory, so with several workers most POST /messages/ +reached a worker without the session and got a 404. /sse now serves +Streamable HTTP, for clients that saved the old URL and try Streamable HTTP +there first (Claude.ai does), and a legacy SSE handshake gets a 410 naming +the /mcp URL. """ import argparse @@ -28,6 +29,7 @@ import anyio import uvicorn +from fastmcp import FastMCP from starlette.applications import Starlette from starlette.requests import ClientDisconnect, Request from starlette.responses import ( @@ -36,6 +38,7 @@ PlainTextResponse, RedirectResponse, ) +from starlette.routing import Route from starlette.types import ASGIApp, Receive, Scope, Send from late.mcp.auth import is_allowed_origin @@ -167,8 +170,6 @@ async def handle_root(request: Request) -> HTMLResponse | JSONResponse: "transport": TRANSPORT_TYPE, "endpoints": { "mcp": f"{ENDPOINT_MCP} (POST) - Streamable HTTP transport (recommended)", - "sse": f"{ENDPOINT_SSE} (GET) - SSE connection endpoint (legacy, deprecated)", - "messages": f"{ENDPOINT_MESSAGES} (POST) - SSE message handler (legacy, deprecated)", "health": f"{ENDPOINT_HEALTH} (GET) - Health check", }, "documentation": DOCS_URL, @@ -325,7 +326,6 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: _ORIGIN_GUARDED_PATHS = ( ENDPOINT_MCP.rstrip("/"), ENDPOINT_SSE.rstrip("/"), - ENDPOINT_MESSAGES.rstrip("/"), ENDPOINT_CHATGPT.rstrip("/"), ) @@ -334,9 +334,9 @@ class OriginGuardMiddleware: """DNS-rebinding protection, scoped to the transport endpoints. Browsers attach an Origin header to cross-site requests; native MCP clients - and server-to-server callers send none (and are allowed). Only the MCP, - SSE, and SSE-message endpoints are gated — /health, / and the OAuth - discovery docs stay public. + and server-to-server callers send none (and are allowed). Only the MCP + transport endpoints are gated — /health, / and the OAuth discovery docs + stay public. Implemented as a pure ASGI middleware (not BaseHTTPMiddleware) so it never buffers the Streamable HTTP response body. @@ -359,41 +359,76 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: await self.app(scope, receive, send) -def _graft_chatgpt_endpoint(app: Starlette) -> None: - """Serve the ChatGPT plugin server at /chatgpt inside the main app. +def _graft_streamable_endpoint(app: Starlette, server: FastMCP, path: str) -> None: + """Serve `server` over Streamable HTTP at `path` inside the main app. - A second FastMCP instance gets its own Streamable HTTP route and its own - path-inserted discovery document (/.well-known/oauth-protected-resource/ - chatgpt, whose `resource` is the /chatgpt URL ChatGPT connects to). Unlike - the SSE graft, a Streamable HTTP session manager only works inside its - lifespan, so the main app's lifespan is wrapped to run both. + The endpoint gets its own route and its own path-inserted discovery + document (/.well-known/oauth-protected-resource/, whose `resource` + is the URL the client connected to; MCP clients reject metadata naming + another resource). A Streamable HTTP session manager only works inside + its lifespan, so the main app's lifespan is wrapped to run both. """ - chatgpt_app = chatgpt_mcp.http_app( - path=ENDPOINT_CHATGPT, + endpoint_app = server.http_app( + path=path, transport="http", stateless_http=True, allowed_hosts=["*"], allowed_origins=["*"], ) - chatgpt_paths = ( - ENDPOINT_CHATGPT.rstrip("/"), - f"{ENDPOINT_OAUTH_PROTECTED_RESOURCE}{ENDPOINT_CHATGPT}", + endpoint_paths = ( + path.rstrip("/"), + f"{ENDPOINT_OAUTH_PROTECTED_RESOURCE}{path}", ) app.router.routes.extend( - r for r in chatgpt_app.routes if getattr(r, "path", "") in chatgpt_paths + r for r in endpoint_app.routes if getattr(r, "path", "") in endpoint_paths ) main_lifespan = app.router.lifespan_context - chatgpt_lifespan = chatgpt_app.router.lifespan_context + endpoint_lifespan = endpoint_app.router.lifespan_context @asynccontextmanager async def combined_lifespan(starlette_app: Starlette): - async with main_lifespan(starlette_app), chatgpt_lifespan(chatgpt_app): + async with main_lifespan(starlette_app), endpoint_lifespan(endpoint_app): yield app.router.lifespan_context = combined_lifespan +_SSE_RETIRED_BODY = { + "error": "sse_transport_removed", + "message": ( + "The legacy SSE transport (GET /sse + POST /messages/) has been removed. " + f"Connect with Streamable HTTP at {MCP_PUBLIC_URL}{ENDPOINT_MCP} instead. " + f"Claude Code: claude mcp add --transport http zernio {MCP_PUBLIC_URL}{ENDPOINT_MCP}. " + f"mcp-remote: npx -y mcp-remote {MCP_PUBLIC_URL}{ENDPOINT_MCP}." + ), + "endpoint": f"{MCP_PUBLIC_URL}{ENDPOINT_MCP}", + "documentation": DOCS_URL, +} + + +async def handle_sse_get(request: Request) -> JSONResponse: + """GET /sse: 410 for the legacy SSE handshake, 405 for Streamable HTTP. + + A Streamable HTTP client sends MCP-Protocol-Version on every request after + initialize, including the GET it opens for server messages, and gets the + 405 /mcp gives it (stateless, no server stream). A legacy SSE client opens + with a bare GET and gets the migration message. + """ + if "mcp-protocol-version" in request.headers: + return JSONResponse( + {"error": "Method Not Allowed"}, + status_code=405, + headers={"Allow": "POST, DELETE"}, + ) + return JSONResponse(_SSE_RETIRED_BODY, status_code=410) + + +async def handle_sse_messages(_request: Request) -> JSONResponse: + """POST /messages/: the legacy SSE message endpoint, removed.""" + return JSONResponse(_SSE_RETIRED_BODY, status_code=410) + + def build_app() -> Starlette: """Build the FastMCP Streamable HTTP ASGI app with Origin protection. @@ -410,29 +445,18 @@ def build_app() -> Starlette: allowed_origins=["*"], ) - # Legacy SSE transport, deprecated but kept for backwards compatibility - # (production still receives GET /sse from older client configs). Built - # from the same FastMCP instance so tools and auth are identical; only the - # /sse and /messages routes are grafted onto the main app, where they run - # under its middleware stack and shared server lifespan. - sse_app = mcp.http_app( - path=ENDPOINT_SSE, - transport="sse", - allowed_hosts=["*"], - allowed_origins=["*"], - ) - # Graft /sse, /messages, and the SSE discovery doc (the /sse 401 challenge - # advertises the path-inserted metadata for its own endpoint). - sse_paths = ( - ENDPOINT_SSE.rstrip("/"), - ENDPOINT_MESSAGES.rstrip("/"), - f"{ENDPOINT_OAUTH_PROTECTED_RESOURCE}{ENDPOINT_SSE}", - ) + # /sse keeps working for clients that saved the old URL and speak + # Streamable HTTP there (Claude.ai tries it before falling back to SSE). + # GET routes are matched first, so a legacy SSE handshake gets the 410. app.router.routes.extend( - r for r in sse_app.routes if getattr(r, "path", "") in sse_paths + [ + Route(ENDPOINT_SSE, handle_sse_get, methods=["GET", "HEAD"]), + Route(ENDPOINT_MESSAGES.rstrip("/"), handle_sse_messages, methods=["GET", "POST"]), + Route(ENDPOINT_MESSAGES, handle_sse_messages, methods=["GET", "POST"]), + ] ) - - _graft_chatgpt_endpoint(app) + _graft_streamable_endpoint(app, mcp, ENDPOINT_SSE) + _graft_streamable_endpoint(app, chatgpt_mcp, ENDPOINT_CHATGPT) # add_middleware order: last added runs first. RootAlias must rewrite the # path before OriginGuard matches on it. FastMCP authenticates all MCP diff --git a/tests/test_mcp_sse_retired.py b/tests/test_mcp_sse_retired.py new file mode 100644 index 00000000..5e1b4982 --- /dev/null +++ b/tests/test_mcp_sse_retired.py @@ -0,0 +1,91 @@ +"""The legacy SSE transport is retired; the /sse URL serves Streamable HTTP.""" + +from collections import OrderedDict + +import httpx +import pytest + +from late.mcp import auth +from late.mcp.constants import MCP_PUBLIC_URL +from late.mcp.http_server import build_app + +pytestmark = pytest.mark.anyio + + +@pytest.fixture +def anyio_backend(): + return "asyncio" + + +STREAMABLE = {"Accept": "application/json, text/event-stream"} +INITIALIZE = { + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-06-18", + "capabilities": {}, + "clientInfo": {"name": "probe", "version": "1.0.0"}, + }, +} + + +async def request(method, path, **kwargs): + app = build_app() + async with ( + app.router.lifespan_context(app), + httpx.AsyncClient( + transport=httpx.ASGITransport(app=app), base_url="http://test" + ) as client, + ): + return await client.request(method, path, **kwargs) + + +@pytest.mark.parametrize( + "method,path", + [("GET", "/sse"), ("POST", "/messages/"), ("POST", "/messages")], +) +async def test_the_sse_handshake_gets_a_410_naming_the_mcp_url(method, path): + response = await request( + method, path, headers={"Accept": "text/event-stream"}, json={} + ) + assert response.status_code == 410 + assert response.json()["error"] == "sse_transport_removed" + assert response.json()["endpoint"] == f"{MCP_PUBLIC_URL}/mcp" + assert "claude mcp add --transport http" in response.json()["message"] + + +async def test_a_streamable_http_get_on_sse_gets_the_405_mcp_gives(): + response = await request( + "GET", "/sse", headers={"MCP-Protocol-Version": "2025-06-18"} + ) + assert response.status_code == 405 + + +async def test_streamable_http_on_sse_is_challenged_with_its_own_metadata(): + response = await request("POST", "/sse", json=INITIALIZE, headers=STREAMABLE) + assert response.status_code == 401 + assert ( + f'resource_metadata="{MCP_PUBLIC_URL}/.well-known/oauth-protected-resource/sse"' + in response.headers["www-authenticate"] + ) + + metadata = await request("GET", "/.well-known/oauth-protected-resource/sse") + assert metadata.status_code == 200 + assert metadata.json()["resource"] == f"{MCP_PUBLIC_URL}/sse" + + +async def test_streamable_http_on_sse_serves_the_mcp_server(monkeypatch): + async def verify(_candidate, **_kwargs): + return auth.Verification.VALID + + monkeypatch.setattr(auth, "verify_late_api_key", verify) + monkeypatch.setattr(auth, "_VERIFIED_AT", OrderedDict()) + response = await request( + "POST", + "/sse", + json=INITIALIZE, + headers={**STREAMABLE, "Authorization": "Bearer valid-test-key"}, + ) + assert response.status_code == 200 + assert '"serverInfo"' in response.text