Skip to content

Commit 12b2893

Browse files
giles17Copilotmoonbox3
authored
Python: Apply header_provider headers to the MCP initialize handshake and other ambient requests (#7305)
* Python: Apply header_provider headers to ambient MCP requests MCPStreamableHTTPTool.header_provider was only invoked from call_tool(), so the initialize handshake, load_tools/load_prompts discovery, and background pings all went out with no headers. MCP servers that require auth on initialize (e.g. Azure AI Search knowledge-base MCP endpoints) therefore returned 401 before any tool call could run. Add an ambient fallback in the _inject_headers httpx request hook: when neither the per-call ContextVar nor the active-call snapshot is set, the hook invokes header_provider({}) so every ambient request is authenticated. Providers that require per-call kwargs raise on the empty dict; that is caught, logged, and the request proceeds unauthenticated, preserving prior behavior. Calling the provider on demand also keeps dynamic token refresh working for post-connect requests. Co-authored-by: Copilot <[email protected]> Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a * Python: address review - distinguish unset vs empty headers, warn once Review feedback on the ambient header_provider fallback: - Distinguish 'unset' (no active call) from 'set but empty' (call_tool produced no headers). Use _mcp_call_headers.get(None) and the None-ness of the snapshot instead of a truthiness check, so a provider that legitimately returns {} during a real call is no longer re-invoked by the ambient fallback mid-call. - A kwargs-dependent provider raises on every ambient request (initialize, discovery, recurring pings). Warn once per tool instance with a traceback via _ambient_header_warning_emitted and drop subsequent occurrences to DEBUG to avoid log spam. Add regression tests for both behaviors. Co-authored-by: Copilot <[email protected]> Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a * Python: narrow ambient header_provider catch to KeyError Only the missing-per-call-kwargs case (KeyError, e.g. the mcp_api_key_auth.py sample indexing kwargs['mcp_api_key']) is tolerated during ambient requests. Any other exception - a token-refresh failure or a provider bug - now propagates instead of being silently converted into unauthenticated traffic, matching the call_tool path which does not catch header_provider exceptions. Add a regression test asserting a non-KeyError provider failure surfaces from the request hook. Co-authored-by: Copilot <[email protected]> Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a * Python: address review - raise instead of assert, simplify ambient logging - Reword the ambient-fallback comment to describe the kwargs-dependent provider pattern generically instead of naming a sample file, which would go stale if the sample is renamed (also in a test docstring). - Replace the type-narrowing assert with a RuntimeError carrying a concise message for the unreachable no-provider state. - Drop the warn-once/_ambient_header_warning_emitted machinery; the KeyError ambient case is expected and benign, so log a single DEBUG line and proceed without headers. Update the corresponding test to assert behavior (request proceeds without an Authorization header and no WARNING is emitted) instead of log-count. Co-authored-by: Copilot <[email protected]> Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Evan Mattson <[email protected]> Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a
1 parent 93e8cb2 commit 12b2893

2 files changed

Lines changed: 211 additions & 2 deletions

File tree

‎python/packages/core/agent_framework/_mcp.py‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3126,8 +3126,36 @@ async def _inject_headers(request: Request) -> None: # ruff:ignore[unused-async
31263126
return
31273127
# The transport may send this request from a task whose context was
31283128
# captured before call_tool set the ContextVar; fall back to the
3129-
# instance-level snapshot of the active call's headers.
3130-
headers = _mcp_call_headers.get({}) or self._active_call_headers or {}
3129+
# instance-level snapshot of the active call's headers. Both are None
3130+
# only when this is an ambient request outside call_tool; an active
3131+
# call that legitimately produced no headers yields an empty dict and
3132+
# must not trigger the ambient fallback below.
3133+
headers = _mcp_call_headers.get(None)
3134+
if headers is None:
3135+
headers = self._active_call_headers
3136+
if headers is None:
3137+
# Ambient request made outside call_tool (the initialize handshake,
3138+
# load_tools/load_prompts discovery, or background pings). Invoke the
3139+
# provider with empty kwargs so static providers can authenticate these
3140+
# requests too. A provider that indexes a required per-call kwarg (e.g.
3141+
# kwargs["api_key"]) raises KeyError on the empty dict; that specific
3142+
# case is tolerated so connect still succeeds. Any other error is a
3143+
# genuine provider failure and is left to propagate, matching the
3144+
# call_tool path which does not catch header_provider exceptions.
3145+
if self._header_provider is None:
3146+
raise RuntimeError("Header injection hook invoked without a header_provider.")
3147+
try:
3148+
headers = self._header_provider({})
3149+
except KeyError:
3150+
# A kwargs-dependent provider raises on every ambient request
3151+
# (initialize, discovery, and recurring pings).
3152+
logger.debug(
3153+
"header_provider raised KeyError for MCP server %r on an ambient "
3154+
"request (missing per-call kwargs); proceeding without headers.",
3155+
self.name,
3156+
exc_info=True,
3157+
)
3158+
headers = {}
31313159
for key, value in headers.items():
31323160
request.headers[key] = value
31333161

‎python/packages/core/tests/core/test_mcp.py‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6027,6 +6027,187 @@ async def test_mcp_streamable_http_tool_header_provider_with_httpx_event_hook():
60276027
await tool._httpx_client.aclose() # type: ignore[union-attr]
60286028

60296029

6030+
async def test_mcp_streamable_http_tool_header_provider_injects_on_ambient_request():
6031+
"""Regression test for #7079: static header_provider must authenticate ambient requests.
6032+
6033+
The initialize handshake, load_tools/load_prompts discovery, and background pings run
6034+
outside call_tool, so the contextvar/snapshot are unset. A static header_provider should
6035+
still be invoked (with empty kwargs) so these requests carry auth headers.
6036+
"""
6037+
import httpx
6038+
6039+
tool = MCPStreamableHTTPTool(
6040+
name="test",
6041+
url="http://example.com/mcp",
6042+
header_provider=lambda kw: {"Authorization": "******"},
6043+
)
6044+
6045+
try:
6046+
with patch("agent_framework._mcp.streamable_http_client"):
6047+
tool.get_mcp_client()
6048+
6049+
assert tool._httpx_client is not None
6050+
hooks = tool._httpx_client.event_hooks.get("request", [])
6051+
assert len(hooks) == 1
6052+
6053+
# No contextvar set and no active call snapshot: simulates the initialize handshake.
6054+
request = httpx.Request("POST", "http://example.com/mcp")
6055+
await hooks[0](request)
6056+
assert request.headers.get("Authorization") == "******"
6057+
finally:
6058+
if getattr(tool, "_httpx_client", None) is not None:
6059+
await tool._httpx_client.aclose() # type: ignore[union-attr]
6060+
6061+
6062+
async def test_mcp_streamable_http_tool_header_provider_ambient_request_tolerates_kwargs_provider():
6063+
"""A header_provider that requires per-call kwargs must not crash ambient requests.
6064+
6065+
Providers that index runtime kwargs (e.g. kw["mcp_api_key"]) which are absent at connect
6066+
time raise KeyError. The hook should swallow that specific error and proceed without headers
6067+
rather than failing the initialize handshake.
6068+
"""
6069+
import httpx
6070+
6071+
tool = MCPStreamableHTTPTool(
6072+
name="test",
6073+
url="http://example.com/mcp",
6074+
header_provider=lambda kw: {"Authorization": f"Bearer {kw['mcp_api_key']}"},
6075+
)
6076+
6077+
try:
6078+
with patch("agent_framework._mcp.streamable_http_client"):
6079+
tool.get_mcp_client()
6080+
6081+
assert tool._httpx_client is not None
6082+
hooks = tool._httpx_client.event_hooks.get("request", [])
6083+
assert len(hooks) == 1
6084+
6085+
# No kwargs available at connect time -> provider raises KeyError -> hook swallows it.
6086+
request = httpx.Request("POST", "http://example.com/mcp")
6087+
await hooks[0](request)
6088+
assert "Authorization" not in request.headers
6089+
finally:
6090+
if getattr(tool, "_httpx_client", None) is not None:
6091+
await tool._httpx_client.aclose() # type: ignore[union-attr]
6092+
6093+
6094+
async def test_mcp_streamable_http_tool_header_provider_empty_active_call_skips_ambient_fallback():
6095+
"""Regression test: an active call that yields no headers must not trigger the ambient fallback.
6096+
6097+
When header_provider legitimately returns {} for a real call_tool invocation, the empty dict
6098+
is a valid "set" value. The hook must treat it as set-but-empty (leave the request unchanged)
6099+
rather than as "unset", which would re-invoke header_provider({}) mid-call and inject headers
6100+
the caller deliberately omitted.
6101+
"""
6102+
import httpx
6103+
6104+
from agent_framework._mcp import _mcp_call_headers
6105+
6106+
call_count = 0
6107+
6108+
def provider(kw: dict[str, Any]) -> dict[str, str]:
6109+
nonlocal call_count
6110+
call_count += 1
6111+
# Non-empty for ambient ({}), empty for the active call below.
6112+
return {} if kw.get("suppress") else {"Authorization": "******"}
6113+
6114+
tool = MCPStreamableHTTPTool(name="test", url="http://example.com/mcp", header_provider=provider)
6115+
6116+
try:
6117+
with patch("agent_framework._mcp.streamable_http_client"):
6118+
tool.get_mcp_client()
6119+
6120+
assert tool._httpx_client is not None
6121+
hooks = tool._httpx_client.event_hooks.get("request", [])
6122+
assert len(hooks) == 1
6123+
6124+
# Simulate an active call whose provider returned {} (both ContextVar and snapshot set).
6125+
token = _mcp_call_headers.set({})
6126+
tool._active_call_headers = {}
6127+
try:
6128+
call_count = 0
6129+
request = httpx.Request("POST", "http://example.com/mcp")
6130+
await hooks[0](request)
6131+
assert "Authorization" not in request.headers
6132+
assert call_count == 0, "ambient fallback must not run during a set-but-empty call"
6133+
finally:
6134+
tool._active_call_headers = None
6135+
_mcp_call_headers.reset(token)
6136+
finally:
6137+
if getattr(tool, "_httpx_client", None) is not None:
6138+
await tool._httpx_client.aclose() # type: ignore[union-attr]
6139+
6140+
6141+
async def test_mcp_streamable_http_tool_header_provider_ambient_kwarg_error_is_benign(caplog):
6142+
"""A kwargs-dependent provider that raises KeyError on ambient requests must not fail them.
6143+
6144+
Ambient requests (initialize/discovery plus recurring pings) call the provider with empty
6145+
kwargs, so a provider indexing a required per-call kwarg raises KeyError. That is tolerated:
6146+
the request proceeds without headers and only a DEBUG line is logged (no WARNING spam).
6147+
"""
6148+
import logging
6149+
6150+
import httpx
6151+
6152+
tool = MCPStreamableHTTPTool(
6153+
name="test",
6154+
url="http://example.com/mcp",
6155+
header_provider=lambda kw: {"Authorization": "Bearer " + kw["mcp_api_key"]},
6156+
)
6157+
6158+
try:
6159+
with patch("agent_framework._mcp.streamable_http_client"):
6160+
tool.get_mcp_client()
6161+
6162+
assert tool._httpx_client is not None
6163+
hooks = tool._httpx_client.event_hooks.get("request", [])
6164+
assert len(hooks) == 1
6165+
6166+
with caplog.at_level(logging.DEBUG, logger="agent_framework._mcp"):
6167+
for _ in range(3):
6168+
request = httpx.Request("POST", "http://example.com/mcp")
6169+
await hooks[0](request)
6170+
assert "Authorization" not in request.headers
6171+
6172+
# The benign kwargs case must not escalate to WARNING/ERROR.
6173+
assert not [r for r in caplog.records if r.levelno >= logging.WARNING]
6174+
finally:
6175+
if getattr(tool, "_httpx_client", None) is not None:
6176+
await tool._httpx_client.aclose() # type: ignore[union-attr]
6177+
6178+
6179+
async def test_mcp_streamable_http_tool_header_provider_ambient_non_keyerror_propagates():
6180+
"""A genuine header_provider failure on an ambient request must surface, not be swallowed.
6181+
6182+
Only the missing-kwargs case (KeyError) is tolerated. Any other error - e.g. a token-refresh
6183+
failure or a provider bug - propagates so it is not silently converted into unauthenticated
6184+
traffic, matching the call_tool path which does not catch header_provider exceptions.
6185+
"""
6186+
import httpx
6187+
6188+
class TokenRefreshError(RuntimeError):
6189+
pass
6190+
6191+
def failing_provider(kw: dict[str, Any]) -> dict[str, str]:
6192+
raise TokenRefreshError("token endpoint unreachable")
6193+
6194+
tool = MCPStreamableHTTPTool(name="test", url="http://example.com/mcp", header_provider=failing_provider)
6195+
6196+
try:
6197+
with patch("agent_framework._mcp.streamable_http_client"):
6198+
tool.get_mcp_client()
6199+
6200+
assert tool._httpx_client is not None
6201+
hooks = tool._httpx_client.event_hooks.get("request", [])
6202+
assert len(hooks) == 1
6203+
6204+
with pytest.raises(TokenRefreshError):
6205+
await hooks[0](httpx.Request("POST", "http://example.com/mcp"))
6206+
finally:
6207+
if getattr(tool, "_httpx_client", None) is not None:
6208+
await tool._httpx_client.aclose() # type: ignore[union-attr]
6209+
6210+
60306211
async def test_mcp_streamable_http_tool_header_provider_skips_cross_origin_redirect():
60316212
"""The request hook must not re-add caller headers after a cross-origin redirect."""
60326213
import httpx

0 commit comments

Comments
 (0)