fix(mcp): make the streamable-HTTP endpoint reachable across the LAN

[jaymeklein]

What

The embedded MCP streamable-HTTP endpoint (/api/mcp/) was unreachable from any machine other than the server host. This makes it reachable across the LAN.

Why it was broken

FastMCP defaults its host to 127.0.0.1. When no transport_security is passed and the host is loopback, the MCP SDK auto-enables DNS-rebinding protection with a loopback-only Host allowlist (mcp/server/fastmcp/server.py). So:

Request Host	Result
localhost:3636 / 127.0.0.1:3636	✅ 200
192.168.x.y:3636 (LAN IP)	❌ 421 Invalid Host header

Every LAN client sends the server's own address as its Host, so the endpoint 421'd for everyone off-box — even though the client config, token, and network path were all correct.

The fix

build_mcp_server() now passes an explicit TransportSecuritySettings(enable_dns_rebinding_protection=False), disabling the Host allowlist so any Host is accepted.

Why this is safe

Authorization on the MCP endpoint has never depended on network position — every request is authenticated by an API key (Authorization: Bearer / X-API-Key) in api/services/mcp/middleware.py, ahead of the transport. DNS-rebinding protection guards unauthenticated, network-position-trusting services; here:

• A DNS-rebinding request from a victim's browser carries no key (the token isn't a cookie, so the browser won't attach it) → 401 before any tool runs.
• The Content-Type: application/json check on POST is unaffected (it runs before the disabled gate).
• This also matches the SDK's own default when no settings are passed (protection off).

The API key is now the sole boundary — operators exposing this on a shared network should keep a strong MASTER_API_KEY, prefer scoped user keys over sharing the master, and set EMBEDBASE_SECURE_HEADERS=true (as the README already advises for LAN).

⚠️ Load-bearing invariant: this is safe because MCP auth is header-based and wraps every request. If MCP ever gains cookie/session auth, DNS-rebinding protection must come back.

Testing

• tests/unit/test_mcp_transport_security.py: asserts the built server disables protection; that the disabled setting reaches the live session_manager (the wiring FastMCP feeds to the request-path middleware — not just the settings object, so an SDK change that stopped forwarding it fails here instead of silently 421'ing LAN clients); plus a non-tautological check that the same LAN Host is rejected (421) under a loopback-only allowlist but accepted under our settings — exercised over the POST path real tool calls use.
• Gate green on the merged branch: ruff ✅ · mypy ✅ (123 files) · pytest ✅ (973 passed, 13 skipped).
• Verified end-to-end on a running stack: direct to the api with an arbitrary non-loopback Host → HTTP 200 (protection off), and the live session_manager.security_settings carries enable_dns_rebinding_protection=False.

Deploying / client impact

• Server (the box running EmbedBase): rebuild/restart the API. No new env required — LAN_HOST is not needed for MCP (it only affects the console's advertised address).
• Clients: no config change — an existing http://<host-ip>:3636/api/mcp/ URL now works directly (no SSH tunnel needed).

---

Merged onto current main (conflicts resolved)

This branch was based on an older main; it's now merged up to current main (db18cfa, PR #78 — self-service MCP tools, get_checksum, migrations 0010–0012). Two conflicts, both resolved:

• api/requirements.txt — main independently pinned mcp==1.28.1 (6f5372d); resolved to that exact pin and dropped this branch's now-redundant mcp>=1.28.1,<2. The PR therefore no longer changes requirements vs main.
• api/services/mcp/server.py — main split tool registration into per-domain groups and added the tool catalogue; that rework is combined with the transport fix, so both coexist: the TransportSecuritySettings import, the _transport_security() helper, the transport_security= arg on the FastMCP(...) constructor, and main's _DOMAIN_REGISTRARS registration loop.

Also — LAN file downloads (docs)

S3/MinIO file downloads hit the same class of bug: presigned URLs are signed against storage.public_endpoint_url, which defaults to localhost:9000, so the API 302's the browser to its own localhost from any other machine (both the parse download and the "download original" button). The real fix is per-deployment runtime config in the gitignored config.yaml/.env, so this PR documents it in the tracked templates:

• .env.example — S3__MINIO__PUBLIC_ENDPOINT_URL (the browser-facing presign host → set to the LAN IP) plus a CORS_ORIGINS note (add the LAN console origin so the cross-origin presigned GET passes CORS).
• config.example.yaml — a note on public_endpoint_url for multi-machine access.

Pre-existing and out of scope (flagged separately): tests/smoke/test_smoke.py asserts stale Celery limits (600/540) vs worker/celery_app.py's current 14460 default. That suite isn't run by CI or the gate, so the drift went unnoticed.