Accept a header provider on MCPClient and scope headers to the server origin

[shibayan]

MCPClient took headers as a static record and handed it to the transport once, when the
connection opened. A credential that has to be refreshed could not be expressed that way, and a
connection shared across users would keep sending whatever was captured when it opened — which is
why FoundryToolbox already bypassed the option with a fetch wrapper of its own, attaching the
token and the call id of the request in flight.

What changes

• McpConnection gains a url form: give it url — and optionally headers and fetch —
  and it builds its own Streamable HTTP transport, a fresh one per connection attempt, so the
  reconnect behaviour matches the url form of MCPClient.
• headers accepts a record, or a function called once per request, so an expiring token is
  refreshed without writing a transport. Both forms are injected through a fetch wrapper placed
  around the caller's own fetch, so replacing it cannot drop them. The wrapper itself is
  internal to the package: consumers configure headers on MCPClient or McpConnection rather
  than assembling a fetch of their own.
• Headers are attached only to requests whose origin matches the configured url, so a bearer
  token, a call id or W3C trace context is not handed to a host the caller never named. Python
  applies the same rule to its header provider.
• A configured header never overrides one the transport already set — the content type, the
  session id, an authorization from the SDK's own auth support all stay the SDK's, which is the
  precedence the static requestInit route always had.
• A custom transport owns its own fetch, so combining it with headers or fetch on
  McpConnection is refused rather than silently ignored — a credential that never reaches the
  wire should not look configured.
• MCPClient's url form and FoundryToolbox both delegate to the connection. The toolbox drops
  its hand-built transport wiring and gains the origin scoping it did not have; its per-call
  authorization and platform headers are unchanged.

Redirects, hop by hop

The platform fetch follows redirects internally, which would make the origin check a decision
about the first URL only: fetch strips Authorization and Cookie when a redirect leaves the
origin, but forwards every custom header — an API key, a platform identity header — to wherever
the server pointed. So when headers are configured, redirects are followed here instead, with
redirect: 'manual', one hop at a time. A hop on the configured origin gets fresh headers from
the provider, a hop off it gets none, and what fetch itself strips cross-origin is stripped the
same way. That is the per-hop behaviour of the httpx event hook Python uses for the same job.
The spec's method rewrites (303 → GET, and 301/302 for a POST), the 20-hop ceiling, and the
refusal to replay a consumed stream body all match what fetch itself does. A caller who passed
redirect: 'manual' or 'error' keeps that behaviour untouched.

The wrapper is unit-tested directly (static and provider headers, per-request refresh, transport
headers preserved and protected, cross-origin cases, a Request first argument, and live
two-origin redirect servers under the real fetch), with connection- and client-level tests that
the header actually reaches the wire, and configuration errors for the refused combinations.

Closes #63

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the MCP client/connection layer to support per-request header injection (including async providers) and scopes injected headers to the configured server origin, then rebases FoundryToolbox onto the shared implementation.

Changes:

• Add McpHeaderProvider + headerInjectingFetch to inject headers per request (without overriding transport-owned headers) and scope them to a single origin.
• Extend McpConnection with a URL-driven construction path that builds a fresh StreamableHTTPClientTransport per connection attempt and rejects incompatible config combinations.
• Update MCPClient and FoundryToolbox to delegate transport/header behavior through McpConnection, with new unit tests covering header behavior and configuration errors.

Reviewed changes

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

Show a summary per file

File	Description
packages/mcp/src/skills.ts	Updates documentation example to use McpConnection({ url }) now that URL-driven construction exists.
packages/mcp/src/index.ts	Exposes McpHeaderProvider type while keeping header injection implementation internal.
packages/mcp/src/headers.ts	Introduces origin-scoped header injection wrapper and redirect behavior for injected-header requests.
packages/mcp/src/headers.test.ts	Adds direct unit tests for header injection behavior (static/provider, origin scoping, redirect cases).
packages/mcp/src/connection.ts	Adds URL form + header/fetch options, builds transport internally, and validates incompatible config.
packages/mcp/src/connection.test.ts	Adds tests for URL-driven construction, per-request headers, and rejected option combinations.
packages/mcp/src/client.ts	Wires MCPClient URL form through McpConnection and updates header option to accept a provider.
packages/mcp/src/client.test.ts	Adds a test ensuring configured headers reach the underlying fetch/transport wire path.
packages/foundry/src/hosting/toolbox.ts	Replaces custom transport/fetch wrapper with McpConnection header provider + optional fetch override.

Suppressed comments (1)

packages/mcp/src/headers.test.ts:204

• Similarly, this test can pass the Request directly instead of casting, once headerInjectingFetch’s signature includes Request.

    const send = headerInjectingFetch(SERVER, { authorization: 'Bearer t' }, fetch);

    await send(new Request('https://elsewhere.example.com/mcp') as unknown as URL);

---

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

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (3)

packages/mcp/src/headers.ts:80

• PR description says redirects are followed hop-by-hop with per-hop origin scoping when headers are configured, but headerInjectingFetch currently sets redirect: 'manual' and then throws on any redirect response. This is a behavioral change vs native fetch (redirects will now fail) and doesn’t match the described redirect-handling design; either implement the hop-by-hop follow logic or update the PR description/acceptance criteria to reflect the deliberate refusal.

    const response = await inner(target, { ...init, headers: outgoing, redirect: 'manual' });
    if (response.type === 'opaqueredirect') {
      // A runtime that hides redirect responses cannot even say where the server pointed.
      throw new Error(
        `The MCP endpoint at ${initialUrl.href} redirected. Requests carrying injected headers ` +
          'are not followed across redirects; configure `url` as the endpoint the server redirects to.',
      );

packages/foundry/src/hosting/toolbox.ts:111

• The injected authorization header value appears to be corrupted (authorization: ****** getToken()}`), which will send an invalid bearer token to Foundry and break authentication.

      // Per-request rather than per-connection: see the class note on why this cannot be a
      // static header set.
      headers: async () => ({
        authorization: `Bearer ${await getToken()}`,
        ...platformHeaders(),
      }),

packages/mcp/src/index.ts:14

• This comment says headers.ts is internal, but McpHeaderProvider is exported from the package entrypoint here. Either stop exporting the type, or adjust the comment to clarify that only the helper functions are internal while the type is part of the public config surface.

// headers.ts (origin-scoped header injection) is internal: consumers configure `headers` on
// MCPClient or McpConnection rather than building the fetch wrapper themselves.
export type { McpHeaderProvider } from './headers.js';