[AUTH FEATURE]: HTTP Header Passthrough (forward headers to MCP server)

[bechols-dmb]

The company I work for is looking at using this as a gateway for our MCP servers. One issue is that we do authentication through a auth gateway that then provides authorization headers into this system. Those headers currently need to be passed along with all MCP tool invocations to whatever kind of backing system mcp/rest/gateway.

We would like to build the solution for this:

Allow for gateways or rest endpoints to be configured with 'allowed passthrough headers' that would be passed from an invoke tool request to the backing system for the invocation. This allows for passing in context about the invoker to the backing gateways / rest servers.

I am open to other suggestions for how to handle this.

🧭 Type of Feature

Please select the most appropriate category:

• Enhancement to existing functionality
• New feature or capability
• New MCP-compliant server
• New component or integration
• Developer tooling or test improvement
• Packaging, automation and deployment (ex: pypi, docker, quay.io, kubernetes, terraform)
• Other (please describe below)

🧭 Epic

Title: Passthrough headers
Goal: Allow specific headers to be passed through requests to gateways or rest.
Why now: Allow for systems that need context to be passed to their their own authentication gateways already to pass authorization headers into the backing MCP servers.

---

🙋‍♂️ User Story 1

As a: mcp-context-forge hoster
I want: to pass context from the invoke_tool request to the backing systems
So that: the invoker's authorization of the tool can be confirmed.

✅ Acceptance Criteria

Scenario: Successfully passing headers
  **State:** Gateway is configured with new "passthrough-headers" option
  **Action:** invoke_tool request is made with headers
  **Result:** The headers specified in the passthrough-headers for that gateway or rest endpoint are copied into the request being made to the backing system.

Scenario: No configured headers
  **State:** Gateway is configured with no headers allowed to be passed through
  **Action:** invoke_tool request is made with headers
  **Result:** no headers are copied from the request.

🔗 MCP Standards Check

• Change adheres to current MCP specifications
• No breaking changes to existing MCP-compliant integrations
• If deviations exist, please describe them below:

---

🔄 Alternatives Considered

Passthrough Auth - not really viable unless the whole auth system is changed to allow multiple headers. The more generic 'passthough headers' allows you to pass any kind of context which could be useful.
Virtual Server per user - would require the ability to set auth headers for every tool / gateway / rest endpoint. This would then require us to create a custom gateway for every user of every tool. This seems awkward and also would not scale well (because you would end up with tens of thousands of combinations of users and tools).
I see there is a roadmap item for 'per virtual server api keys' which could possibly kind-of solve this we would then just need another service/library to decode the key back into our various headers before the tools can be invoked with the correct cont

---

📓 Additional Context

[crivetimihai]

Hi there and thanks for the proposal! It fits our roadmap, but we need a bit more details. Could you please share:

• Design sketch - where the allow-list lives (model + migration) and how the gateway forwards the headers.

• A few quick diagrams - happy path vs. a header that gets blocked or conflicts.

• Example calls:

  • create / update a gateway with passthrough_headers
  • an invoke_tool that shows headers forwarded, and one where they’re dropped.

• Test notes – how you'd demo the feature with curl (conflict, deny-list, etc.) and some sample servers to test with?

My understanding

Right now, every invoke_tool call that hits a downstream MCP server or plain REST service has to carry its auth/context headers manually, because the gateway provides no way to forward caller-supplied headers. We can inject headers ad-hoc for each tool, which doesn't scale.

Adding a passthrough-headers allow-list to every configured MCP Server / REST entry in the registry would let us declare which header names (e.g., Authorization, X-Tenant-Id, X-Trace-Id) are safe to forward.

When the client includes any of those headers, the gateway copies them to the downstream request and silently drops everything else. The gateway stays stateless, we avoid inventing a new auth scheme, and downstream services still get the context they expect.

Note

• The existing auth_type / auth_value fields store static credentials, not caller-supplied headers.
• You declare an auth_type (basic, bearer, or authheaders) plus the matching raw fields (auth_username/auth_password, or auth_token, or auth_header_key + auth_header_value.

Open questions

1. Conflict handling – If a header name appears both in auth_value (static) and in the passthrough set, does the request fail, does the static value win, or do we overwrite it with the caller's value?
2. Configuration surface – Where should passthrough-headers live (.env, DB column)? Do we require hot-reload, or is a gateway restart acceptable?
3. Security & auditing – Are there headers we must never forward (e.g., Cookie, Host)? Do we need wildcard/regex support, and should sensitive header values be redacted in logs?
4. Granularity – Does one allow-list cover an entire gateway, or do we need per-tool overrides or virtual server overrides? If a single invocation fans out to multiple downstream calls, do we forward the same headers to every hop?

---

Sequence diagrams

1. Current flow – manual header injection

sequenceDiagram
    autonumber
    actor Client
    participant Gateway
    participant Downstream

    Client->>Gateway: invoke_tool()<br/>(explicit auth/context headers)
    Note over Client,Gateway: Caller injects headers tool-by-tool
    Gateway->>Downstream: REST/MCP request<br/>(same headers)
    Note over Gateway,Downstream: Gateway just forwards body/payload

Loading

2. Proposed flow – passthrough-headers allow-list

sequenceDiagram
    autonumber
    actor Client
    participant Gateway
    participant Downstream

    Client->>Gateway: invoke_tool() with auth/context headers
    Note over Client,Gateway: Caller injects headers per tool
    Gateway->>Downstream: REST/MCP request with same headers
    Note over Gateway,Downstream: Gateway simply forwards body/payload

Loading

Would having something like this make sense:

curl -X PUT -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"passthrough_headers":["Authorization","X-Tenant-Id","X-Trace-Id"]}' \
     http://localhost:4444/gateways/3

[bechols-dmb]

I think we roughly have the same idea:

1. Conflict resolution: I would lean towards don't allow conflicting headers, show the user an error if they try to configure that. As a backup in the case that somehow data is corrupted I think that the auth header definitions should win because if you configured that explicitly I think you wouldn't want it to be overridden.

2. Storage: This should be stored in the configuration for a federated gateway / rest endpoint which would put it in the DB. This should be refreshed the same way that any DB value is refreshed. EDIT: Now that I think about it, maybe having a global config allowed for the entire server that could be overridden by each federated gateway could be nice. This would simplify the process to add many federated gateways in the case they all need the same headers). It should probably still just be stored in the DB. I am unsure if there is currently server wide configuration stored in the DB. If so, it should be easy to add another configuration, but if there isn't this could be a larger change.

3. Security / Audit: I don't think we should limit which headers can be forwarded but it would probably be preferred to redact sensitive headers (esp headers related to auth / user)

4. Granularity - I would have preferred to keep this as simple as possible but it looks like REST is always configured as a single tool and as such we should allow for tool level setting of passthrough headers.

[crivetimihai]

Great, thanks! Have set this as planned for 0.6.0 but we may tackle some of the design components and pre-reqs earlier.

Any additional info / suggestions you have on how to test this (sample MCP servers, agents, example headers) would help!