refactor(examples): migrate all HTTP examples to streamable_http_app()

[maxisbey]

Migrates all 9 HTTP example servers (plus docs/experimental/tasks-server.md) to use Server.streamable_http_app() instead of manually wiring SseServerTransport / StreamableHTTPSessionManager + lifespan + Starlette routes.

Motivation and Context

GHSA-9h52-p55h-vw2f added DNS rebinding auto-enable for localhost binds, but only at the high-level API layer. The advisory notes:

Users with custom low-level server configurations using StreamableHTTPSessionManager or SseServerTransport directly should explicitly configure TransportSecuritySettings.

Our examples were using those low-level APIs without explicit security settings — so they ran unprotected despite binding to 127.0.0.1. Rather than demo the footgun (passing explicit allowlists everywhere), this PR migrates every example to the high-level API where auto-enable lives.

What changed

Examples	Before	After
simple-streamablehttp, -stateless	Manual StreamableHTTPSessionManager + @asynccontextmanager lifespan + Starlette(routes=[Mount])	app.streamable_http_app(...). CORS still wraps the returned app.
simple-task, -task-interactive, sse-polling-demo	Same manual wiring	server.streamable_http_app(...)
simple-tool, -prompt, -resource, -pagination	--transport sse branch with 30 lines of SseServerTransport wiring	--transport streamable-http branch: uvicorn.run(app.streamable_http_app(), ...)
docs/experimental/tasks-server.md	Manual wiring	server.streamable_http_app()

Net: −289 lines. Zero TransportSecuritySettings references remain in examples/.

Related: #2269 (closed — already addressed in v1.23.0 for high-level API), #2275/#2287 (closed — naive middleware flip would reject all requests with empty allowlists).

How Has This Been Tested?

Static checks

• uv run --frozen pytest tests/test_examples.py — 45 passed
• uv run --frozen pyright examples/servers/... — 0 errors
• uv run --frozen ruff check examples/servers/ — all checks passed

Live end-to-end verification — 45/45 probes passed

Each server started, probed with curl, killed. All 9 now use streamable_http_app() with Route("/mcp", ...) (no trailing slash).

Probe	Host	Origin	Response	Meaning
valid localhost	127.0.0.1:PORT	—	400	past security gate → reached MCP handling (rejects empty {} as invalid JSON-RPC)
valid localhost	localhost:PORT	—	400	localhost:* allowlist entry works
attack: bad host	evil.com	—	421	DNS rebinding protection blocks it
attack: bad origin	127.0.0.1:PORT	http://evil.com	403	Origin validation blocks it
valid origin	127.0.0.1:PORT	http://localhost:PORT	400	both gates passed

Full results (45/45)

── simple-streamablehttp (port 9001)
PASS valid Host 127.0.0.1 got=400
PASS valid Host localhost got=400
PASS evil Host got=421
PASS evil Origin (valid Host) got=403
PASS valid Origin got=400
── simple-streamablehttp-stateless (port 9002)
PASS valid Host 127.0.0.1 got=400
PASS valid Host localhost got=400
PASS evil Host got=421
PASS evil Origin (valid Host) got=403
PASS valid Origin got=400
── simple-task (port 9003)
PASS valid Host 127.0.0.1 got=400
PASS valid Host localhost got=400
PASS evil Host got=421
PASS evil Origin (valid Host) got=403
PASS valid Origin got=400
── simple-task-interactive (port 9004)
PASS valid Host 127.0.0.1 got=400
PASS valid Host localhost got=400
PASS evil Host got=421
PASS evil Origin (valid Host) got=403
PASS valid Origin got=400
── sse-polling-demo (port 9005)
PASS valid Host 127.0.0.1 got=400
PASS valid Host localhost got=400
PASS evil Host got=421
PASS evil Origin (valid Host) got=403
PASS valid Origin got=400
── simple-tool (port 9006)
PASS valid Host 127.0.0.1 got=400
PASS valid Host localhost got=400
PASS evil Host got=421
PASS evil Origin (valid Host) got=403
PASS valid Origin got=400
── simple-prompt (port 9007)
PASS valid Host 127.0.0.1 got=400
PASS valid Host localhost got=400
PASS evil Host got=421
PASS evil Origin (valid Host) got=403
PASS valid Origin got=400
── simple-resource (port 9008)
PASS valid Host 127.0.0.1 got=400
PASS valid Host localhost got=400
PASS evil Host got=421
PASS evil Origin (valid Host) got=403
PASS valid Origin got=400
── simple-pagination (port 9009)
PASS valid Host 127.0.0.1 got=400
PASS valid Host localhost got=400
PASS evil Host got=421
PASS evil Origin (valid Host) got=403
PASS valid Origin got=400

Test script

#!/bin/bashset -u
wait_for_port() {
local port=$1foriin {1..50};do
lsof -ti:$port -sTCP:LISTEN >/dev/null 2>&1&&return 0
sleep 0.1
donereturn 1
}
probe() {
local name="$1" port="$2" host="$3" origin="$4" expect="$5"local args=(-s -o /dev/null -w '%{http_code}' --max-time 3)
args+=(-X POST -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{}')
[[ -n"$host" ]] && args+=(-H "Host: $host")
[[ -n"$origin" ]] && args+=(-H "Origin: $origin")
local got; got=$(curl "${args[@]}""http://127.0.0.1:$port/mcp"2>/dev/null)
[[ "$got"=="$expect" ]] &&echo" PASS $name got=$got"||echo" FAIL $name got=$got expected=$expect"
}
test_server() {
local pkg="$1" port="$2" extra_args="$3"echo"── $pkg (port $port)"
uv run --frozen --directory "examples/servers/$pkg" \
python -c "from mcp_${pkg//-/_}.server import main; main(['--port','$port'$extra_args])"&local pid=$!; wait_for_port "$port"
probe "valid Host 127.0.0.1""$port""127.0.0.1:$port""" 400
probe "valid Host localhost""$port""localhost:$port""" 400
probe "evil Host""$port""evil.com""" 421
probe "evil Origin (valid Host)""$port""127.0.0.1:$port""http://evil.com" 403
probe "valid Origin""$port""127.0.0.1:$port""http://localhost:$port" 400
kill$pid2>/dev/null;wait$pid2>/dev/null
}
test_server simple-streamablehttp 9001 ""
test_server simple-streamablehttp-stateless 9002 ""
test_server simple-task 9003 ""
test_server simple-task-interactive 9004 ""
test_server sse-polling-demo 9005 ""
test_server simple-tool 9006 ",'--transport','streamable-http'"
test_server simple-prompt 9007 ",'--transport','streamable-http'"
test_server simple-resource 9008 ",'--transport','streamable-http'"
test_server simple-pagination 9009 ",'--transport','streamable-http'"

Breaking Changes

None — examples only.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[claude]

LGTM — mechanical documentation change that applies the same TransportSecuritySettings allowlist (matching what lowlevel/server.py auto-configures) across all low-level transport examples.

Extended reasoning...

Overview

This PR adds explicit TransportSecuritySettings to 9 example servers and 1 doc page that use SseServerTransport or StreamableHTTPSessionManager directly. Each change is identical: import TransportSecuritySettings and pass allowed_hosts=["127.0.0.1:*", "localhost:*", "[::1]:*"] plus matching allowed_origins. The values exactly match what lowlevel/server.py:533-534 auto-configures for localhost binds.

Security risks

None — this change adds DNS rebinding protection rather than removing or weakening anything. The allowlist is appropriately restrictive (localhost-only) and correct for these examples, all of which bind uvicorn to 127.0.0.1. The PR correctly omits enable_dns_rebinding_protection=True since that is the field default (confirmed at transport_security.py:19).

Level of scrutiny

Low — this is examples and documentation only, with no library code changes. The pattern is mechanical and repeated identically across all 10 files. I verified that both SseServerTransport.__init__ (sse.py:78) and StreamableHTTPSessionManager.__init__ (streamable_http_manager.py:72) accept the security_settings parameter with the correct type.

Other factors

No CODEOWNERS file exists in the repo. The PR description reports passing tests (pytest tests/test_examples.py), type checks (pyright), and lint (ruff). No bugs were found by the automated review. The change brings the examples into compliance with guidance from GHSA-9h52-p55h-vw2f.

[claude]

LGTM — examples-only change applying a consistent mechanical pattern, with the refactored task/polling servers correctly delegating to streamable_http_app()'s auto-enable logic.

Extended reasoning...

Overview

This PR touches 9 example servers + 1 docs page (no src/ changes). Two mechanical patterns are applied:

1. Six files: add a security_settings=TransportSecuritySettings(...) kwarg to existing SseServerTransport(...) / StreamableHTTPSessionManager(...) constructor calls. The allowlist is byte-identical to what lowlevel/server.py:530-535 auto-configures. I verified the kwarg exists on both constructors (sse.py:78, streamable_http_manager.py:72) and that enable_dns_rebinding_protection defaults to True (transport_security.py:19), so omitting it is correct.

2. Three files (simple-task, simple-task-interactive, sse-polling-demo): replace ~15 lines of StreamableHTTPSessionManager + Starlette + lifespan boilerplate with server.streamable_http_app(). I verified this method accepts event_store, retry_interval, and debug (lines 518–526), so sse-polling-demo's refactor preserves all behavior. The auto-enable path at line 530 fires because host defaults to "127.0.0.1".

Security risks

None — this PR only adds security gating to localhost-bound example servers. The allowlists are strictly localhost-scoped. There is no way for this change to widen the attack surface; at worst it would overly restrict (which the probe results disprove for the 6 unchanged-architecture servers).

Level of scrutiny

Low. These are demo/example servers, not library code. Every change is either (a) passing a hardening kwarg with the same value the high-level API already uses, or (b) replacing bespoke Starlette wiring with the canonical helper. No logic was invented; all building blocks already exist and are tested.

Other factors

• No CODEOWNERS file in the repo.
• No prior reviews or comments to address.
• Static checks (pytest, pyright, ruff) reported green in the PR description.
• The single nit flagged (inline comment) concerns PR-description accuracy for the 3 refactored servers' probe results — a Route vs Mount routing detail that would yield 307 redirects on the test script's trailing-slash /mcp/ path. The code itself is correct: streamable_http_app() registers Route("/mcp", ...) (line 598–601) and the security gate still fires on the canonical /mcp path. This does not affect mergeability.