Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
6 changes: 3 additions & 3 deletions docs/HTTP_DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -70,7 +70,7 @@ Optional variables:
- `SENTRY_DSN` — sends one transaction per tool call (`tools/call <tool>`) 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

Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/MCP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
12 changes: 5 additions & 7 deletions src/late/mcp/constants.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand Down
120 changes: 72 additions & 48 deletions src/late/mcp/http_server.py
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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 (
Expand All @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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("/"),
)

Expand All @@ -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.
Expand All @@ -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/<path>, 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.

Expand All @@ -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
Expand Down
91 changes: 91 additions & 0 deletions tests/test_mcp_sse_retired.py
Original file line number Diff line number Diff line change
@@ -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
Loading