Skip to content

πŸš€ 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.mdx
index 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.py
index 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 = True
else:
@@ -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.py
index 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 so
they 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.py
new file mode 100644
index 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