Skip to content

Commit c47da07

Browse files
Python: scope Secure MCP URL headers to origin (#8285)
* Python: scope Secure MCP URL headers to origin Co-authored-by: Copilot App <[email protected]>\nCopilot-Session: bf1fc8c4-eff7-42e7-9342-d385036223be * Python: preserve concurrent Secure MCP calls Co-authored-by: Copilot App <[email protected]>\nCopilot-Session: bf1fc8c4-eff7-42e7-9342-d385036223be
1 parent e0162ab commit c47da07

4 files changed

Lines changed: 204 additions & 43 deletions

File tree

‎python/packages/core/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID
164164
- **`allowed_tools`** (constructor arg on all `MCPTool` subclasses) - Restricts exposed MCP tools by raw remote MCP tool identity. Prefixed local names remain accepted only when the raw remote name already matches its normalized form; normalized/local aliases do not authorize a different raw remote name. If multiple raw remote tool names map to the same local function name, tool loading raises `ToolExecutionException` instead of first-one-wins shadowing.
165165
- **Progressive MCP disclosure** (`use_progressive_disclosure`, `always_load`) - When enabled on any `MCPTool` subclass, the initial model-facing surface is loader tools (`list_mcp_tools` / `load_tool` / `unload_tool`, prefixed by `tool_name_prefix` when configured) plus allowed tools selected by `always_load` and tools loaded earlier on the same `MCPTool` instance. `list_mcp_tools` only reports tools that pass `allowed_tools`; filtered tools are not listed or loadable. Loader tool names are reserved in progressive mode: remote MCP tools whose local generated name collides with a loader name are omitted from the initial/listed surface, and explicit `load_tool` calls return a model-visible message pointing callers to `tool_name_prefix` or excluding the colliding tool. `load_tool` accepts one tool name or a list of tool names and uses `FunctionInvocationContext.add_tools(...)` so the selected generated MCP `FunctionTool`s become available on the next function-calling iteration while keeping existing approval mode, argument filtering, header-provider runtime kwargs, result parsing, OTel, and task behavior. `unload_tool` accepts one dynamically loaded tool name or a list of names and removes them from the live tool list and persisted progressive surface, but it does not remove tools configured in `always_load`. Invalid `always_load` entries are ignored like unmatched `allowed_tools` entries.
166166
- **`additional_tool_argument_names`** (constructor arg on all `MCPTool` subclasses) - Opt extra argument names back into the allowlist. Accepts a `Sequence[str]` (applied to every tool) or a `Mapping[str, Sequence[str]]` keyed by **remote tool name**, where the reserved key `"*"` denotes global extras. It is configured only in user code at construction; there is **no per-call/runtime override**, so a model-issued tool call cannot change which names pass through — but note this constrains the *model*, not the *server*, which still widens the effective allowlist through its schema. To use a server that accepts `additionalProperties: true`, list the extra names here and then either (1) manually extend that tool's `inputSchema` (via the `.functions` list after connecting) so the model is prompted to supply them, or (2) supply the values yourself via `function_invocation_kwargs`. If a normal forwarded argument name is supplied by both the model and `function_invocation_kwargs`, the model-supplied value wins; `_meta` is the exception and only trusted runtime/caller metadata is used.
167-
- **`header_provider` request scoping** - When sharing an `http_client`, keep provider processing scoped to the originating `MCPStreamableHTTPTool` and strip injected headers from cross-origin redirects. The session exit stack removes its request hook after transport shutdown, including failed initialization or discovery, and closes framework-created HTTP clients. Failed discovery resets the connection and discovery flags and rolls back partial function/metadata additions. Framework-created sessions are discarded; constructor-supplied sessions remain caller-owned and reusable across cleanup, close, and reset.
167+
- **MCP HTTP header request scoping** - `static_headers` supplies fixed, origin-scoped headers without serializing concurrent calls; `header_provider` resolves dynamic per-call headers under the instance call lock. When both are configured, dynamic values override fixed values with the same name. With a shared `http_client`, processing stays scoped to the originating `MCPStreamableHTTPTool`, and every injected header is stripped from cross-origin redirects. The session exit stack removes its request hook after transport shutdown, including failed initialization or discovery, and closes framework-created HTTP clients. Failed discovery resets the connection and discovery flags and rolls back partial function/metadata additions. Framework-created sessions are discarded; constructor-supplied sessions remain caller-owned and reusable across cleanup, close, and reset.
168168
- **MCP lifecycle caller cancellation** - The lifecycle owner skips cancelled queued connect requests and waits for the caller to acknowledge successful setup. If the caller cancels before accepting a newly established connection, the owner tears it down before processing the next request. Cancelling a close waiter does not interrupt teardown, and cancelling a redundant connect does not discard a previously established session.
169169
- **`function_invocation_kwargs` and MCP servers** - That dict is shared across every tool in the run, including every attached `MCPTool`, and any name in it reaches a server that declares a matching `inputSchema` property. `header_provider` does not mitigate this — it reads the kwargs without consuming them. To keep a credential out of tool arguments, source it outside `function_invocation_kwargs`: read a `ContextVar` inside the provider (this still allows a different value per request), configure a custom `http_client`, or use `env` for `MCPStdioTool`.
170170
- **Sampling guardrails** (`sampling_callback`) - Passing `client=` advertises `SamplingCapability` so the server can send `sampling/createMessage`. Because remote servers are untrusted (confused-deputy risk), the default `sampling_callback` is **deny-by-default** and applies, in order: a per-session rate limit (`sampling_max_requests`, default `_DEFAULT_SAMPLING_MAX_REQUESTS`), an approval gate (`sampling_approval_callback`), and a `maxTokens` cap (`sampling_max_tokens`, default `_DEFAULT_SAMPLING_MAX_TOKENS`). The approval callback (constructor arg on all subclasses; exported type alias `SamplingApprovalCallback`) receives the raw `CreateMessageRequestParams`, may be sync or async, and must return truthy to approve. When it is `None` (the default) every sampling request is denied; pass `lambda params: True` to restore legacy auto-approve as an explicit opt-in. Requests and denials are logged at WARNING (content is not logged). The per-session counter resets in `_reset_session_state`.

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

Lines changed: 35 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -642,11 +642,13 @@ def _inject_otel_into_mcp_meta(
642642
return meta
643643

644644

645-
def _url_origin(url: Any) -> tuple[str, str, int | None]:
645+
def _url_origin(url: Any) -> tuple[str, str, int]:
646+
if url.scheme not in {"http", "https"} or not url.host:
647+
raise ValueError("MCP URL must be an absolute HTTP(S) URL with a host.")
646648
port = url.port
647649
if port is None:
648-
port = 443 if url.scheme == "https" else 80 if url.scheme == "http" else None
649-
return (url.scheme, url.host or "", port)
650+
port = 443 if url.scheme == "https" else 80
651+
return (url.scheme, url.host, port)
650652

651653

652654
# Internal polling bounds for MCP long-running tasks. Not user-tunable today;
@@ -3479,6 +3481,7 @@ def __init__(
34793481
sampling_max_requests: int | None = _DEFAULT_SAMPLING_MAX_REQUESTS,
34803482
additional_properties: dict[str, Any] | None = None,
34813483
http_client: AsyncClient | None = None,
3484+
static_headers: Mapping[str, str] | None = None,
34823485
header_provider: Callable[[dict[str, Any]], dict[str, str]] | None = None,
34833486
task_options: MCPTaskOptions | None = None,
34843487
additional_tool_argument_names: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
@@ -3550,8 +3553,8 @@ def __init__(
35503553
requests are rejected. Resets on reconnect. ``None`` disables it.
35513554
http_client: Optional asyncClient to use. If not provided, the
35523555
``streamable_http_client`` API will create and manage a default client.
3553-
To configure headers, timeouts, or other HTTP client settings, create
3554-
and pass your own ``asyncClient`` instance.
3556+
Use ``static_headers`` for fixed headers. To configure timeouts or other
3557+
HTTP client settings, create and pass your own ``asyncClient`` instance.
35553558
Security: when you attach sensitive headers (e.g. authentication tokens)
35563559
via a custom ``http_client``, you are responsible for enforcing the same
35573560
origin-scoped header policy that the built-in ``header_provider`` hook
@@ -3561,6 +3564,13 @@ def __init__(
35613564
client that sets headers unconditionally (e.g. via ``AsyncClient(headers=...)``
35623565
or ``follow_redirects=True`` without an origin check) can leak those headers
35633566
to other origins; scope them to the target origin yourself.
3567+
static_headers: Optional fixed HTTP headers to inject into requests to the
3568+
configured ``url`` origin. The headers are copied at construction, included
3569+
on connection-lifetime requests and tool calls, retained across same-origin
3570+
redirects, and removed on cross-origin redirects. Unlike ``header_provider``,
3571+
fixed headers do not serialize concurrent tool calls. Use ``header_provider``
3572+
instead when header values depend on runtime invocation arguments. When both
3573+
are provided, dynamic headers override fixed headers with the same name.
35643574
header_provider: Optional callable that receives the runtime keyword arguments
35653575
(from ``FunctionInvocationContext.kwargs``) and returns a ``dict[str, str]``
35663576
of HTTP headers to inject into every outbound request to the MCP server.
@@ -3647,6 +3657,7 @@ def __init__(
36473657
self.url = url
36483658
self.terminate_on_close = terminate_on_close
36493659
self._httpx_client: AsyncClient | None = http_client
3660+
self._static_headers = dict(static_headers or {})
36503661
self._header_provider = header_provider
36513662
# Headers for the in-flight call_tool invocation. The streamable HTTP transport
36523663
# sends requests from tasks spawned at connect time, whose contexts never observe
@@ -3689,7 +3700,7 @@ def get_mcp_client(self) -> _AsyncGeneratorContextManager[Any, None]:
36893700
from httpx import URL, AsyncClient, Timeout
36903701

36913702
http_client = self._httpx_client
3692-
if self._header_provider is not None:
3703+
if self._static_headers or self._header_provider is not None:
36933704
target_origin = _url_origin(URL(self.url))
36943705
if http_client is None:
36953706
http_client = AsyncClient(
@@ -3709,26 +3720,28 @@ async def _inject_headers(request: Request) -> None: # ruff:ignore[unused-async
37093720
for key in request.extensions.pop(_MCP_INJECTED_HEADER_KEYS_EXTENSION, ()):
37103721
request.headers.pop(key, None)
37113722
return
3712-
# The transport may send this request from a task whose context was
3713-
# captured before call_tool set the ContextVar; fall back to the
3714-
# instance-level snapshot of the active call's headers. Both are None
3715-
# only when this is an ambient request outside call_tool; an active
3716-
# call that legitimately produced no headers yields an empty dict and
3717-
# must not trigger the ambient fallback below.
3718-
headers = _mcp_call_headers.get(None)
3719-
if headers is None:
3720-
headers = self._active_call_headers
3721-
if headers is None:
3723+
headers = self._static_headers.copy()
3724+
if self._header_provider is not None:
3725+
# The transport may send this request from a task whose context was
3726+
# captured before call_tool set the ContextVar; fall back to the
3727+
# instance-level snapshot of the active call's headers. Both are None
3728+
# only when this is an ambient request outside call_tool; an active
3729+
# call that legitimately produced no headers yields an empty dict and
3730+
# must not trigger the ambient fallback below.
3731+
dynamic_headers = _mcp_call_headers.get(None)
3732+
if dynamic_headers is None:
3733+
dynamic_headers = self._active_call_headers
3734+
else:
3735+
dynamic_headers = None
3736+
if dynamic_headers is None and self._header_provider is not None:
37223737
# Ambient request made outside call_tool (the initialize handshake,
37233738
# load_tools/load_prompts discovery, or background pings). Invoke the
37243739
# provider with the kwargs seeded by the run that established this
37253740
# connection, so static providers and run-supplied credentials both
37263741
# authenticate these requests. Provider failures propagate, matching the
37273742
# call_tool path, except the one case below that no caller can avoid.
3728-
if self._header_provider is None:
3729-
raise RuntimeError("Header injection hook invoked without a header_provider.")
37303743
try:
3731-
headers = self._header_provider(self._connection_kwargs or {})
3744+
dynamic_headers = self._header_provider(self._connection_kwargs or {})
37323745
except KeyError:
37333746
# Unavoidable only when no run seeded this connection: the provider
37343747
# wants per-call values a connection-lifetime request cannot have. Once
@@ -3742,7 +3755,9 @@ async def _inject_headers(request: Request) -> None: # ruff:ignore[unused-async
37423755
self.name,
37433756
exc_info=True,
37443757
)
3745-
headers = {}
3758+
dynamic_headers = {}
3759+
if dynamic_headers is not None:
3760+
headers.update(dynamic_headers)
37463761
for key in request.extensions.pop(_MCP_INJECTED_HEADER_KEYS_EXTENSION, ()):
37473762
request.headers.pop(key, None)
37483763
for key, value in headers.items():

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

Lines changed: 6 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -3968,8 +3968,8 @@ class SecureMCPToolProxy:
39683968
url: URL of a remote MCP server. When provided, the proxy creates
39693969
an ``MCPStreamableHTTPTool`` internally. Mutually exclusive with
39703970
*mcp_tool*.
3971-
headers: HTTP headers (e.g. auth tokens) sent with every request
3972-
when using *url* mode.
3971+
headers: HTTP headers (e.g. auth tokens) sent with requests to the
3972+
configured origin when using *url* mode.
39733973
name: Tool name used when creating the internal
39743974
``MCPStreamableHTTPTool`` (defaults to ``"mcp"``).
39753975
description: Tool description for the internal tool.
@@ -4007,8 +4007,8 @@ def __init__(
40074007
Keyword Args:
40084008
url: URL of a remote MCP server. When provided, the proxy creates an
40094009
``MCPStreamableHTTPTool`` internally. Mutually exclusive with ``mcp_tool``.
4010-
headers: HTTP headers (e.g. auth tokens) sent with every request when using
4011-
``url`` mode.
4010+
headers: HTTP headers (e.g. auth tokens) sent with requests to the configured
4011+
origin when using ``url`` mode.
40124012
name: Tool name used when creating the internal ``MCPStreamableHTTPTool``
40134013
(defaults to ``"mcp"``).
40144014
description: Tool description for the internal tool.
@@ -4031,30 +4031,14 @@ def __init__(
40314031
raise ValueError("Provide either 'mcp_tool' (an MCPTool instance) or 'url' (a remote MCP server URL).")
40324032

40334033
if url is not None:
4034-
from httpx import AsyncClient, Timeout
4035-
4036-
from ._mcp import MCP_DEFAULT_SSE_READ_TIMEOUT, MCP_DEFAULT_TIMEOUT, MCPStreamableHTTPTool
4034+
from ._mcp import MCPStreamableHTTPTool
40374035

40384036
static_headers = dict(headers or {})
4039-
# Pass headers via an AsyncClient so they are included on ALL requests
4040-
# (including session.initialize()), not just tool calls. Using
4041-
# header_provider alone only sets headers via a ContextVar that is
4042-
# populated during call_tool() and would be empty during initialization,
4043-
# causing 401s that silently manifest as anyio cancel-scope errors.
4044-
http_client = (
4045-
AsyncClient(
4046-
headers=static_headers,
4047-
follow_redirects=True,
4048-
timeout=Timeout(MCP_DEFAULT_TIMEOUT, read=MCP_DEFAULT_SSE_READ_TIMEOUT),
4049-
)
4050-
if static_headers
4051-
else None
4052-
)
40534037
mcp_tool = MCPStreamableHTTPTool(
40544038
name=name or "mcp",
40554039
url=url,
4056-
http_client=http_client,
40574040
description=description,
4041+
static_headers=static_headers,
40584042
)
40594043

40604044
# The validation above guarantees a tool is set (passed directly or built

0 commit comments

Comments
 (0)