Add support for forwarding headers from MCP clients to GraphQL APIs

[DaleSeo]

Fixes #198

Adds opt-in support for dynamic header forwarding, which enables metadata for A/B testing, feature flagging, geo information from CDNs, or internal instrumentation to be sent from MCP clients to downstream GraphQL APIs. It automatically blocks hop-by-hop headers according to the guidelines in RFC 7230, section 6.1, and it only works with the Streamable HTTP transport.

You can configure using the forward_headers setting:

forward_headers:
  - x-tenant-id
  - x-experiment-id
  - x-geo-country

Please note that this feature is not intended for passing through credentials as documented in the best practices page.

E2E Test

Configure the MCP server to target the Platform API and enable CORS as below, then verify end‑to‑end with MCP Inspector:

endpoint: https://api.apollographql.com/api/graphql
cors:
  enabled: true
  match_origins:
    - "^http://localhost:[0-9]+$"
  allow_headers:
    - accept
    - content-type
    - mcp-protocol-version
    - mcp-session-id
    - traceparent
    - tracestate
    - x-custom-auth-headers
    - X-API-Key
    - apollographql-client-name
    - apollographql-client-version
forward_headers:
  - X-API-Key
  - apollographql-client-name
  - apollographql-client-version
transport:
  type: streamable_http
  port: 8000

With the 3 required headers set in MCP Inspector, tool execution succeeds:

If you configure MCP Inspector with Connection Type = Direct, you can also inspect the MCP call in the browser:

If any required header is missing, the server returns an error:

[apollo-librarian]

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 8 changed, 0 removed

* (developer-tools)/apollo-mcp-server/(latest)/best-practices.mdx
* (developer-tools)/apollo-mcp-server/(latest)/config-file.mdx
* (developer-tools)/apollo-mcp-server/(latest)/deploy.mdx
* (developer-tools)/apollo-mcp-server/(latest)/index.mdx
* (developer-tools)/apollo-mcp-server/(latest)/limitations.mdx
* (developer-tools)/apollo-mcp-server/(latest)/quickstart.mdx
* (developer-tools)/apollo-mcp-server/(latest)/telemetry.mdx
* (developer-tools)/apollo-mcp-server/(latest)/_sidebar.yaml

Build ID: a7fa14ebf9e66e0b65c8094e
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/a7fa14ebf9e66e0b65c8094e

[github-actions]

❌ Changeset file missing for PR

All changes should include an associated changeset file.
Please refer to README for more information on generating changesets.