feat: MCP tool runtime auth header passthrough with admin-configured header names

[skamenan7]

Describe the new functionality needed

Add per-request header passthrough to the MCP tool runtime provider using the shared forward_headers utility from providers/utils/forward_headers.py.

The MCP provider becomes a thin integration: wire build_forwarded_headers() into outbound requests, add forward_headers and extra_blocked_headers config fields, call validate_forward_headers_config() in the model validator.

Config example:

providers:
  tool_runtime:
    - provider_id: mcp-tools
      provider_type: remote::mcp
      config:
        forward_headers:
          maas_api_token: "Authorization"
          tenant_id: "X-Tenant-ID"
        extra_blocked_headers:
          - "X-Internal-Debug"

forward_headers is a key-value map: provider data key to HTTP header name. Default empty = forward nothing (default deny). extra_blocked_headers lets the operator tighten the policy on top of the core blocklist.

Why is this needed? What if we don't build it?

Inline MCP tools (type "mcp" in the Responses API request) already support per-request auth via authorization= and that works today. The gap is in the tool-group path: when MCP tools are pre-registered via toolgroups.register and called through the agent executor, invoke_tool is called without authorization= (tool_executor.py:371-374). The existing mcp_headers mechanism explicitly rejects Authorization (model_context_protocol.py:108), so there is currently no path to forward per-request auth credentials to the downstream server for registered tool groups.

Additionally, mcp_headers requires the client to know the exact downstream header names and construct a URI-to-headers map. forward_headers is an admin-side config that decouples the client from downstream internals. The client sends {"maas_api_token": "my-jwt-token"} via X-LlamaStack-Provider-Data and the server maps it to Authorization: Bearer my-jwt-token on the downstream request. When targeting Authorization, the value must be a bare token — the Bearer prefix is added automatically.

This is the MCP counterpart to the inference passthrough (#5134) and safety passthrough (#5004). Part of the broader header forwarding initiative tracked in #4607.

Other thoughts

• Depends on feat: add forward_headers support to inference passthrough provider #5134 (not yet merged) which introduces the shared providers/utils/forward_headers.py utility. This issue should be picked up after feat: add forward_headers support to inference passthrough provider #5134 lands.
• feat: passthrough safety provider for forwarding to downstream /v1/moderations #5004 (merged) established the pattern with the safety passthrough provider.
• The MCP provider is a thin integration: config fields + wiring, reusing the shared utility.

[skamenan7]

@leseb please check and assign it to me this new issue for passthrough.

[mattf]

Without this, every MCP tool call uses the same static credentials from config, making it impossible to support per-user authorization against MCP services.

tell your llm that this is not correct. point it at https://developers.openai.com/api/docs/guides/tools-connectors-mcp#authentication

[skamenan7]

You're right @mattf, the "static credentials" claim was wrong for inline MCP tools -- authorization= already handles
per-request Bearer tokens there (tool_executor.py:343).

The actual gap is in the tool-group path: when MCP tools are pre-registered via toolgroups.register and called through the
agent executor, invoke_tool gets called without authorization= (tool_executor.py:371-374). Meanwhile,
get_headers_from_request explicitly rejects Authorization in mcp_headers (model_context_protocol.py:108). So for
pre-registered MCP tools, there's no way to pass per-request auth credentials to the downstream server.

The existing mcp_headers mechanism does pass non-auth headers, but it requires the client to know the exact downstream header names and construct the URI-to-headers map. The forward_headers approach from #5134 is an admin-side config that decouples the client from downstream internals -- the client sends {"maas_api_token": "Bearer xyz"} and the server maps it to Authorization.

Happy to update the issue description to focus on the tool-group auth gap and the admin-side mapping.

[skamenan7]

@mattf I updated the description itself as per above comment. thought it will be easier to review it as a whole.

[skamenan7]

@cdoern can you please assign it to me. thanks.

[mattf]

@skamenan7 does this make sense after #4997?

[skamenan7]

Yeah @mattf , #4997 does change the picture. The tool-group auth gap I described goes away if that lands. What's left is the inline path: headers= and authorization= are client-supplied there, so callers have to know the downstream header names.

forward_headers is the operator-side version of that, where the admin configures the mapping and clients just pass values in X-LlamaStack-Provider-Data without knowing the downstream header names. The inference and safety passthrough providers both have it, so it'd be a bit odd to leave MCP out. I think it provides consistency across providers. But we can close this if not needed. Please advise.