Python: Add origin-scoped headers for MCP connect authentication

[Shivani . (Shivani767)]

Motivation & Context

MCPStreamableHTTPTool.connect() can still reach servers that authenticate the initialize handshake without credentials when auth comes only from a kwargs-dependent header_provider. Per-call kwargs are not available until call_tool(), so those servers get a 401 (or hang) before any tool call runs.

#7305 already delivers header_provider headers across transport tasks and authenticates ambient requests for static providers. This PR covers the remaining connect-time gap for servers that require handshake auth.

Description & Review Guide

• What are the major changes?

  • Add an origin-scoped headers= constructor argument on MCPStreamableHTTPTool.
  • Apply those static headers to initialize, discovery, pings, reconnects, and tool calls.
  • Keep header_provider as a per-call overlay on top of headers=.
  • Strip previously injected header keys on cross-origin redirects (covers secrets like X-API-Key that HTTPX would otherwise copy).
  • Route SecureMCPToolProxy URL mode through headers= instead of baking tokens into AsyncClient.
  • Document the connect vs per-call split in AGENTS.md and the API-key sample.
  • Add regression tests for ambient injection, call overlay, cross-origin strip, and end-to-end initialize auth.

• What is the impact of these changes?

  • Callers can authenticate MCP connect() without baking tokens into a custom httpx.AsyncClient.
  • Kwargs-only header_provider setups can still authenticate the handshake via headers= while using dynamic tokens for tool calls.
  • Existing header_provider / custom-client behavior is unchanged for callers that already worked.

• What do you want reviewers to focus on?

  • Whether headers= is the right connect-time contract vs changing ambient header_provider({}) behavior.
  • Origin-scoped injection and cross-origin stripping for non-Authorization secrets.

Related Issue

Fixes #7841

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Pull request overview

Adds origin-scoped static headers to authenticate MCP initialization while retaining per-call header overlays.

Changes:

• Adds headers= support and header resolution.
• Adds ambient, overlay, redirect, and initialize tests.
• Documents connect-time versus per-call authentication.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_mcp.py	Implements static header injection.
python/packages/core/tests/core/test_mcp.py	Adds authentication regression tests.
python/packages/core/agent_framework/security.py	Updates proxy guidance.
python/packages/core/AGENTS.md	Documents header behavior.
python/samples/02-agents/mcp/mcp_api_key_auth.py	Explains handshake authentication.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Evan Mattson (moonbox3)]

Following up on the redirect thread: could we track these keys on the request rather than on the tool? _injected_header_keys is the last same-origin request's global set, so an independent request through a shared http_client to another origin loses its own same-named header; concurrent ambient and call traffic can also replace the set before a redirect, leaving the earlier secret attached. A marker in request.extensions would follow the HTTPX redirect chain without affecting unrelated requests.

[Evan Mattson (moonbox3)]

Should the client created here be owned and closed by the tool? Passing this AsyncClient into streamable_http_client makes the SDK treat it as caller-owned, so _exit_stack never closes it; every MCPStreamableHTTPTool(headers=...) or URL-mode SecureMCPToolProxy lifecycle leaves its connection pool open. Could the tool register http_client.aclose on _exit_stack only when it creates the client?

[Evan Mattson (moonbox3)]

Shivani . (@Shivani767) please fix the file conflicts as well, thanks.

[Evan Mattson (moonbox3)]

Re-open when wanting to take this forward.