vMCP: add header_passthrough outgoing auth strategy to forward dynamic incoming headers to backends

[juancarlosm]

Problem

When a client calls vMCP with dynamic request headers (e.g. x-mcp-api-key, x-mcp-auth), those headers are silently dropped. The vMCP creates a new HTTP client per backend call and only forwards pre-configured static auth headers — the original incoming headers never reach the backend.

This breaks use cases where the backend MCP server requires per-user/per-session headers for authentication (e.g. an external API that is API-key filtered and the key varies per client).

Observed: Backend receives requests with only vMCP-generated headers.
Expected: Backend receives selected incoming headers forwarded transparently.

Current workarounds

• header_injection: Only supports static pre-configured values — unusable for dynamic per-client keys.
• token_exchange: Requires an OAuth IdP; not applicable for simple API key forwarding.

Proposed solution

Add a new outgoing auth strategy: header_passthrough.

Configuration example:

outgoingAuth:
  type: header_passthrough
  headerPassthrough:
    headers:
      - x-mcp-api-key
      - x-mcp-auth

Implementation touch points:

1. pkg/vmcp/auth/types/types.go — add StrategyTypeHeaderPassthrough + HeaderPassthroughConfig struct
2. pkg/vmcp/auth/strategies/header_passthrough.go — new strategy reads specified headers from context
3. Incoming middleware / server — store raw incoming request headers in context (currently only Identity is stored)
4. pkg/vmcp/client/client.go — identityPropagatingRoundTripper pattern can be extended to carry selected headers

Security considerations

• Only explicitly listed headers should be forwarded (allowlist, not passthrough-all)
• Header names should be validated (CRLF injection prevention, same as header_injection)
• Sensitive headers (e.g. authorization) should be allowed but documented as requiring care

[jerm-dro]

Thanks for creating the issue @juancarlosm!

This new header_passthrough mechanism seems very similar to header_injection. It seems reasonable to me to slightly expand header_injection to support this functionality rather than creating a brand new auth type:

  outgoingAuth:
    type: header_injection
    headerInjection:
      headersFromIncoming: 
       - x-mcp-api-key  
       - x-mcp-auth

The proposed implementation touch points are largely the same.

Incoming middleware / server — store raw incoming request headers in context (currently only Identity is stored)
pkg/vmcp/client/client.go — identityPropagatingRoundTripper pattern can be extended to carry selected headers

I don't love reliance on stuffing the context for implementing functionality, since it introduces coupling between the middleware and the consumer of the context. The consequences are:

1. It means we've got a whole class of errors that can only be detected at runtime. If the context isn't populated for some reason, we won't know until the code is exercised.
2. Cognitive load. In order to understand the implementation, readers need to jump across modules to see how a context value is initialized and later consumed.

All that being said, this seems unavoidable with the current factoring. We do have some in-flight work to pay down some tech debt in session / client creation (seen here). When that lands, I expect it to make the ideal fix easier, since you won't have to plumb the incoming headers through so many layers. Thus, you won't have to rely on plumbing via context.

Let me know if you want to work on this urgently. If so, then the proposed solution relying on middleware / context data is fine with me.

cc: @jhrozek, @yrobla in case you have thoughts on the proposed solution and FYI on how the session creation work relates to reducing dependence on context-variable-populating-middleware.

[juancarlosm]

No rush on our end — we have a working workaround by hitting the MCP server proxy directly instead of going through vMCP.

Happy to defer to whatever approach makes sense architecturally. If it's a small addition (folding into header_injection as @jerm-dro suggests), it might be worth doing now. If the session/client lifecycle refactor is the cleaner home for this, we can wait. Up to you — we'll follow the thread.

[jerm-dro]

@juancarlosm Given this isn't a blocker for you, let's wait until the session management refactors are complete. We can revisit this conversation when that code lands and decide then on the solution to the problem here.

[juancarlosm]

Hi @jerm-dro any update on this?

[juancarlosm]

Reviving this — the blocker has landed 🎉

This was parked back in March until the session/client lifecycle refactor (THV-0038) was done. That's now in main:

• pkg/vmcp/headerforward exists (Move HeaderForward helpers to pkg/vmcp/headerforward #5302)
• static HeaderForward is wired into the vMCP per-session client (Wire HeaderForward into vMCP per-session HTTP client #5301, Forward MCPServerEntry headerForward to vMCP outbound requests #5239)
• per-request identity already flows to the backend round-tripper (Preserve fresh per-request identity in vMCP backend transports #5335)

So the hard plumbing is done — what's left is just forwarding a configured allowlist of incoming headers in addition to the static ones.

Quick recap of the problem

vMCP builds a fresh request per backend call, so incoming client headers (x-litellm-api-key, x-mcp-auth, any x-env: …) get dropped. The plain MCPServer proxy forwards them by default — the vMCP aggregator doesn't. That breaks backends that resolve a per-user identity from an incoming header (ours resolves x-litellm-api-key against a whoami endpoint). Static injection can't help: every user would collapse to one identity. And really this isn't auth at all — forwarding x-env: pepe has nothing to do with authenticating to the backend.

Two ways to shape it

Option A — a generic, non-auth field (my preference, since it isn't auth):

spec:
  groupRef: { name: google-ro }
  passthroughHeaders:        # allowlist → forwarded to all backends
    - x-litellm-api-key
    - x-env
  outgoingAuth: { source: discovered }   # untouched

Option B — fold into header_injection, as @jerm-dro suggested:

outgoingAuth:
  type: header_injection
  headerInjection:
    headersFromIncoming:
      - x-litellm-api-key
      - x-mcp-auth

A keeps the concern out of auth; B is a smaller change but models a non-auth thing as auth.

Sketch of the change

Add a ForwardIncoming []string to the header-forward config, capture the allowlisted incoming headers into the request context via a server middleware, and have the existing headerforward round-tripper set them on the outbound request. Then the usual config + CRD plumbing (converter, deepcopy, manifest regen). The context-stuffing concern from before is now precedented — #5335 already carries per-request identity the same way.

Security

Allowlist only (never forward-all), block RestrictedHeaders (Host, hop-by-hop, X-Forwarded-*), validate header names like header_injection does. Authorization allowed but documented as needing care. Note the trust assumption: with incomingAuth: anonymous this relies on a trusted upstream (gateway) setting the headers.

Purely additive — no behaviour change when the field is unset. Happy to take a crack at the implementation if there's agreement on A vs B.

[jerm-dro]

@juancarlosm Thanks for keeping the ball rolling here! Option A is fine with me, since it meets your needs and is purely additive.

Feel free to start working on this. I'll assign this to you 🙏

[juancarlosm]

Happy to start working on this!!!

[juancarlosm]

Hi @jerm-dro PR ready: #5466