π The fast, Pythonic way to build MCP servers and clients.
fix: Make proxy HTTP header forwarding configurable (#5462)
Jeremiah Lowin3191f5cd1ed1
diff --git a/docs/servers/providers/proxy.mdx b/docs/servers/providers/proxy.mdxindex 883b5c728..c5e30a71c 100644--- a/docs/servers/providers/proxy.mdx+++ b/docs/servers/providers/proxy.mdx@@ -133,6 +133,25 @@ async with Client(Path("backend_server.py")) as connected_client:Shared sessions may cause context mixing in concurrent scenarios. Use only in single-threaded situations or with explicit synchronization.</Warning>+## HTTP Header Forwarding++Proxies forward eligible incoming HTTP headers, including `Authorization` and custom headers, to HTTP and SSE backends by default. Headers configured on the backend transport take precedence. Cookies and connection-specific headers are excluded.++When your backend uses its own configured headers or authentication, set `forward_incoming_headers=False` on its `ProxyClient`. The setting also applies to every backend in an MCP configuration.++```python+from fastmcp.client.transports import StreamableHttpTransport+from fastmcp.server import create_proxy+from fastmcp.server.providers.proxy import ProxyClient++transport = StreamableHttpTransport(+ "http://backend:8000/mcp",+ headers={"x-api-key": "backend-api-key"},+)+backend = ProxyClient(transport, forward_incoming_headers=False)+proxy = create_proxy(backend)+```+## MCP Feature Forwarding<VersionBadge version="2.10.3" />diff --git a/fastmcp_slim/fastmcp/client/transports/config.py b/fastmcp_slim/fastmcp/client/transports/config.pyindex 4afa43b82..c8134642a 100644--- a/fastmcp_slim/fastmcp/client/transports/config.py+++ b/fastmcp_slim/fastmcp/client/transports/config.py@@ -176,6 +176,7 @@ class MCPConfigTransport(ClientTransport):stack,requested_mode,prepared_transports=prepared_transports,+ transport_options=transport_options,)# `auto` is an aggregate negotiation: the composite can only expose@@ -195,7 +196,11 @@ class MCPConfigTransport(ClientTransport):stack = contextlib.AsyncExitStack()await stack.__aenter__()composite, _ = await self._build_composite(- FastMCP, timeout, stack, "legacy"+ FastMCP,+ timeout,+ stack,+ "legacy",+ transport_options=transport_options,)self._resolved_legacy_only = Trueelse:@@ -218,6 +223,7 @@ class MCPConfigTransport(ClientTransport):stack: contextlib.AsyncExitStack,backend_mode: str,prepared_transports: dict[str, ClientTransport] | None = None,+ transport_options: TransportOptions | None = None,) -> tuple["FastMCP[Any]", list[str]]:"""Connect configured backends and mount their proxies on one router."""composite = fastmcp_type(@@ -256,6 +262,7 @@ class MCPConfigTransport(ClientTransport):stack,current_mode,transport=transport,+ transport_options=transport_options,)except Exception: # Broad catch is intentional: failure modes# are diverse (OSError, TimeoutError, RuntimeError, etc.) and@@ -318,6 +325,7 @@ class MCPConfigTransport(ClientTransport):stack: contextlib.AsyncExitStack,backend_mode: str | None = None,transport: ClientTransport | None = None,+ transport_options: TransportOptions | None = None,) -> tuple[ClientTransport, Any, "FastMCP[Any]"]:"""Create underlying transport, proxy client, and proxy server for a single backend.@@ -352,6 +360,10 @@ class MCPConfigTransport(ClientTransport):client_kwargs: dict[str, Any] = {}if backend_mode is not None:client_kwargs["mode"] = backend_mode+ if transport_options is not None:+ client_kwargs["forward_incoming_headers"] = (+ transport_options.forward_incoming_headers+ )client = StatefulProxyClient(transport=transport, timeout=timeout, **client_kwargs)diff --git a/fastmcp_slim/fastmcp/server/providers/proxy.py b/fastmcp_slim/fastmcp/server/providers/proxy.pyindex 967c4858a..1e3b5c611 100644--- a/fastmcp_slim/fastmcp/server/providers/proxy.py+++ b/fastmcp_slim/fastmcp/server/providers/proxy.py@@ -96,7 +96,7 @@ class _ForwardingClientSession(ClientSession):return None-# Settings every proxy-backend connection uses: relay results without policing+# Default proxy-backend connection settings: relay results without policing# the backend's output schema, and forward eligible caller headers upstream# without inheriting frontend-owned MCP transport state.PROXY_TRANSPORT_OPTIONS = TransportOptions(@@ -110,9 +110,8 @@ def _with_proxy_transport_options() -> TransportOptions:"""Layer proxy-owned settings onto options supplied by another client layer."""return replace(- options or TransportOptions(),+ options or PROXY_TRANSPORT_OPTIONS,session_class=PROXY_TRANSPORT_OPTIONS.session_class,- forward_incoming_headers=PROXY_TRANSPORT_OPTIONS.forward_incoming_headers,)@@ -1670,6 +1669,10 @@ class ProxyClient(Client[ClientTransportT]):"""A proxy client that forwards advanced interactions between a remote MCP server and the proxy's connected clients.Supports forwarding roots, sampling, elicitation, logging, and progress.+ Eligible inbound HTTP headers are forwarded by default; set+ `forward_incoming_headers=False` to use only the backend transport's+ configured headers and authentication. Applies to HTTP and SSE backends,+ including backends in an MCP configuration.The default forwarding handlers must resolve the *proxy's* request context sothey relay server-initiated requests (roots/sampling/elicitation) back to the@@ -1707,6 +1710,8 @@ class ProxyClient(Client[ClientTransportT]):| MCPConfig| dict[str, Any]| str,+ *,+ forward_incoming_headers: bool = True,**kwargs,):if "name" not in kwargs:@@ -1744,7 +1749,10 @@ class ProxyClient(Client[ClientTransportT]):self._proxy_restoring_handler_keys.add(key)super().__init__(transport=transport, **kwargs) # ty: ignore[no-matching-overload]- self._transport_options = _with_proxy_transport_options(self._transport_options)+ self._transport_options = replace(+ _with_proxy_transport_options(self._transport_options),+ forward_incoming_headers=forward_incoming_headers,+ )def _bind_restoring_handlers(self) -> None:if "roots" in self._proxy_restoring_handler_keys:diff --git a/tests/server/providers/proxy/test_header_options.py b/tests/server/providers/proxy/test_header_options.pynew file mode 100644index 000000000..af5e9da08--- /dev/null+++ b/tests/server/providers/proxy/test_header_options.py@@ -0,0 +1,112 @@+import json++import pytest++from fastmcp import Client, FastMCP+from fastmcp.client.transports import (+ ClientTransport,+ SSETransport,+ StreamableHttpTransport,+)+from fastmcp.server import create_proxy+from fastmcp.server.dependencies import get_http_headers+from fastmcp.server.providers.proxy import ProxyClient+from fastmcp.utilities.tests import run_server_async++[email protected]("forward", [None, True, False])[email protected]("kind", ["http", "sse", "single", "multiple"])+async def test_proxy_header_forwarding_can_be_selected(kind: str, forward: bool | None):+ backend = FastMCP("Backend")++ @backend.tool+ def headers() -> dict[str, str]:+ return get_http_headers(include_all=True)++ @backend.resource("headers://fixed")+ def resource_headers() -> str:+ return json.dumps(get_http_headers(include_all=True))++ @backend.resource("headers://{name}")+ def template_headers(name: str) -> str:+ return json.dumps(get_http_headers(include_all=True))++ @backend.prompt+ def prompt_headers() -> str:+ return json.dumps(get_http_headers(include_all=True))++ backend_transport = "sse" if kind == "sse" else "http"+ async with run_server_async(backend, transport=backend_transport) as url:+ configured = {"x-backend": "configured", "x-shared": "backend"}+ if kind == "http":+ target = StreamableHttpTransport(url, headers=configured)+ elif kind == "sse":+ target = SSETransport(url, headers=configured)+ else:+ names = ["first", "second"] if kind == "multiple" else ["first"]+ target = {+ "mcpServers": {+ name: {"url": url, "headers": configured} for name in names+ }+ }+ proxy_client = (+ ProxyClient[ClientTransport](target)+ if forward is None+ else ProxyClient[ClientTransport](target, forward_incoming_headers=forward)+ )+ proxy = create_proxy(proxy_client)+ async with run_server_async(proxy) as proxy_url:+ transport = StreamableHttpTransport(+ proxy_url,+ headers={+ "authorization": "Bearer caller",+ "x-caller": "inbound",+ "x-shared": "caller",+ "cookie": "local=value",+ },+ )+ async with Client(transport, mode="legacy") as client:+ tools = await client.list_tools()+ assert len(tools) == (2 if kind == "multiple" else 1)+ received_headers = []+ for tool in tools:+ result = await client.call_tool(tool.name, {})+ received_headers.append(result.data)+ resources = await client.list_resources()+ for resource in resources:+ result = await client.read_resource(resource.uri)+ received_headers.append(json.loads(result[0].text))+ templates = await client.list_resource_templates()+ for template in templates:+ uri = template.uri_template.replace("{name}", "daily")+ result = await client.read_resource(uri)+ received_headers.append(json.loads(result[0].text))+ prompts = await client.list_prompts()+ for prompt in prompts:+ result = await client.get_prompt(prompt.name)+ received_headers.append(json.loads(result.messages[0].content.text))+ for received in received_headers:+ assert received["x-backend"] == "configured"+ assert received["x-shared"] == "backend"+ assert "cookie" not in received+ if forward is not False:+ assert received["authorization"] == "Bearer caller"+ assert received["x-caller"] == "inbound"+ else:+ assert "authorization" not in received+ assert "x-caller" not in received+++def test_proxy_copies_keep_independent_forwarding_options():+ transport = StreamableHttpTransport("http://backend/mcp")+ forwarding = ProxyClient(transport)+ configured_only = ProxyClient(transport, forward_incoming_headers=False)++ assert forwarding._transport_options is not None+ assert forwarding._transport_options.forward_incoming_headers is True+ assert configured_only._transport_options is not None+ assert (+ configured_only.new()._transport_options is configured_only._transport_options+ )+ assert configured_only._transport_options.forward_incoming_headers is False+ assert Client(transport)._transport_options is None