kb/openspec/changes/archive/2026-04-04-mcp-allowed-hosts/proposal.md

Why

The MCP server uses the Python MCP SDK's built-in DNS rebinding protection, which validates the Host header on every request. By default it only allows localhost, 127.0.0.1, and [::1]. When clients connect remotely — using an IP address or FQDN — the server returns 421 "Invalid Host header" and the connection fails. There is no way to configure allowed hosts without changing code.

What Changes

• Add a new environment variable KB_MCP_ALLOWED_HOSTS that accepts a comma-separated list of additional allowed hosts (IPs and/or FQDNs).
• The MCP server passes these hosts (plus the existing localhost defaults) to the MCP SDK's TransportSecuritySettings when constructing the ASGI app.
• Both bare hosts and wildcard-port patterns are supported (e.g. 192.168.1.50 and kb.example.com both work, with any port).
• When KB_MCP_ALLOWED_HOSTS is empty or unset, behaviour is unchanged (localhost-only).

Capabilities

New Capabilities

None — this is configuration of an existing component, not a new capability.

Modified Capabilities

• docker-deployment: Add KB_MCP_ALLOWED_HOSTS to the MCP container's environment variables in Compose files and document its usage.

Impact

• mcp/config.py — new KB_MCP_ALLOWED_HOSTS env var.
• mcp/server.py — construct TransportSecuritySettings with merged allowed hosts/origins and pass to the FastMCP app.
• engine/compose.*.yaml — add KB_MCP_ALLOWED_HOSTS to the kb-mcp service environment block.