feat(mcp): add configurable header forwarding to GraphQL requests

Implements header forwarding from MCP requests to GraphQL endpoint with
opt-in configuration for additional headers beyond Authorization.

Key changes:
- Authorization header is always forwarded (maintains backward compatibility)
- New `forward_headers` config with `enabled` (default: false) and `allow_list`
- Support for exact header matches and regex patterns (e.g., "X-.*")
- Case-insensitive header matching
- Context-based header storage and filtering
- Comprehensive unit tests for filtering logic
- Updated JSON schema with validation

Configuration example:
```yaml
mcp:
  forward_headers:
    enabled: true
    allow_list:
      - "X-Tenant-ID"
      - "X-Trace-ID"
      - "X-.*"

Author: asoorm

router/core/router.go

@@ -886,6 +886,7 @@ func (r *Router) bootstrap(ctx context.Context) error {
 			mcpserver.WithEnableArbitraryOperations(r.mcp.EnableArbitraryOperations),
 			mcpserver.WithExposeSchema(r.mcp.ExposeSchema),
 			mcpserver.WithStateless(r.mcp.Session.Stateless),
+			mcpserver.WithForwardHeaders(r.mcp.ForwardHeaders.Enabled, r.mcp.ForwardHeaders.AllowList),
 		}
 
 		// Determine the router GraphQL endpoint

router/pkg/config/config.go

@@ -963,15 +963,21 @@ type CacheWarmupConfiguration struct {
 }
 
 type MCPConfiguration struct {
-	Enabled                   bool             `yaml:"enabled" envDefault:"false" env:"MCP_ENABLED"`
-	Server                    MCPServer        `yaml:"server,omitempty"`
-	Storage                   MCPStorageConfig `yaml:"storage,omitempty"`
-	Session                   MCPSessionConfig `yaml:"session,omitempty"`
-	GraphName                 string           `yaml:"graph_name" envDefault:"mygraph" env:"MCP_GRAPH_NAME"`
-	ExcludeMutations          bool             `yaml:"exclude_mutations" envDefault:"false" env:"MCP_EXCLUDE_MUTATIONS"`
-	EnableArbitraryOperations bool             `yaml:"enable_arbitrary_operations" envDefault:"false" env:"MCP_ENABLE_ARBITRARY_OPERATIONS"`
-	ExposeSchema              bool             `yaml:"expose_schema" envDefault:"false" env:"MCP_EXPOSE_SCHEMA"`
-	RouterURL                 string           `yaml:"router_url,omitempty" env:"MCP_ROUTER_URL"`
+	Enabled                   bool                        `yaml:"enabled" envDefault:"false" env:"MCP_ENABLED"`
+	Server                    MCPServer                   `yaml:"server,omitempty"`
+	Storage                   MCPStorageConfig            `yaml:"storage,omitempty"`
+	Session                   MCPSessionConfig            `yaml:"session,omitempty"`
+	GraphName                 string                      `yaml:"graph_name" envDefault:"mygraph" env:"MCP_GRAPH_NAME"`
+	ExcludeMutations          bool                        `yaml:"exclude_mutations" envDefault:"false" env:"MCP_EXCLUDE_MUTATIONS"`
+	EnableArbitraryOperations bool                        `yaml:"enable_arbitrary_operations" envDefault:"false" env:"MCP_ENABLE_ARBITRARY_OPERATIONS"`
+	ExposeSchema              bool                        `yaml:"expose_schema" envDefault:"false" env:"MCP_EXPOSE_SCHEMA"`
+	RouterURL                 string                      `yaml:"router_url,omitempty" env:"MCP_ROUTER_URL"`
+	ForwardHeaders            MCPForwardHeadersConfiguration `yaml:"forward_headers"`
+}
+
+type MCPForwardHeadersConfiguration struct {
+	Enabled   bool     `yaml:"enabled" envDefault:"false" env:"MCP_FORWARD_HEADERS_ENABLED"`
+	AllowList []string `yaml:"allow_list" env:"MCP_FORWARD_HEADERS_ALLOW_LIST"`
 }
 
 type MCPSessionConfig struct {

router/pkg/config/config.schema.json

@@ -2071,6 +2071,25 @@
           "type": "boolean",
           "default": false,
           "description": "Expose the full GraphQL schema through MCP. When enabled, AI models can request the complete schema of your API."
+        },
+        "forward_headers": {
+          "type": "object",
+          "description": "Configuration for forwarding additional HTTP headers from MCP requests to GraphQL requests. The Authorization header is always forwarded regardless of this configuration to maintain backward compatibility. Use this to forward additional headers like tenant IDs, trace IDs, or custom authentication tokens.",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Enable forwarding of additional headers beyond Authorization. When false (default), only the Authorization header is forwarded. When true, headers matching the allow_list are also forwarded."
+            },
+            "allow_list": {
+              "type": "array",
+              "description": "List of additional header names or regex patterns to forward (beyond Authorization which is always forwarded). Supports exact matches (e.g., 'X-Tenant-ID') and regex patterns (e.g., 'X-.*' for all headers starting with 'X-'). Header matching is case-insensitive.",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
         }
       }
     },

router/pkg/mcpserver/server.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"regexp"
 	"strings"
 	"time"
 
@@ -25,16 +26,31 @@ import (
 // authKey is a custom context key for storing the auth token.
 type authKey struct{}
 
+// headersKey is a custom context key for storing forwarded headers.
+type headersKey struct{}
+
 // withAuthKey adds an auth key to the context.
 func withAuthKey(ctx context.Context, auth string) context.Context {
 	return context.WithValue(ctx, authKey{}, auth)
 }
 
+// withHeaders adds headers to the context.
+func withHeaders(ctx context.Context, headers http.Header) context.Context {
+	return context.WithValue(ctx, headersKey{}, headers)
+}
+
 // authFromRequest extracts the auth token from the request headers.
 func authFromRequest(ctx context.Context, r *http.Request) context.Context {
 	return withAuthKey(ctx, r.Header.Get("Authorization"))
 }
 
+// headersFromRequest extracts all headers from the request and stores them in context.
+func headersFromRequest(ctx context.Context, r *http.Request) context.Context {
+	// Clone the headers to avoid any mutation issues
+	headers := r.Header.Clone()
+	return withHeaders(ctx, headers)
+}
+
 // tokenFromContext extracts the auth token from the context.
 // This can be used by clients to pass the auth token to the server.
 func tokenFromContext(ctx context.Context) (string, error) {
@@ -45,6 +61,12 @@ func tokenFromContext(ctx context.Context) (string, error) {
 	return auth, nil
 }
 
+// headersFromContext extracts headers from the context.
+func headersFromContext(ctx context.Context) (http.Header, bool) {
+	headers, ok := ctx.Value(headersKey{}).(http.Header)
+	return headers, ok
+}
+
 // Options represents configuration options for the GraphQLSchemaServer
 type Options struct {
 	// GraphName is the name of the graph to be served
@@ -70,6 +92,10 @@ type Options struct {
 	ExposeSchema bool
 	// Stateless determines whether the MCP server should be stateless
 	Stateless bool
+	// ForwardHeadersEnabled determines whether header forwarding is enabled
+	ForwardHeadersEnabled bool
+	// ForwardHeadersAllowList is the list of headers (or regex patterns) to forward
+	ForwardHeadersAllowList []string
 }
 
 // GraphQLSchemaServer represents an MCP server that works with GraphQL schemas and operations
@@ -91,6 +117,8 @@ type GraphQLSchemaServer struct {
 	operationsManager         *OperationsManager
 	schemaCompiler            *SchemaCompiler
 	registeredTools           []string
+	forwardHeadersEnabled     bool
+	forwardHeadersAllowList   []string
 }
 
 type graphqlRequest struct {
@@ -218,6 +246,8 @@ func NewGraphQLSchemaServer(routerGraphQLEndpoint string, opts ...func(*Options)
 		exposeSchema:              options.ExposeSchema,
 		stateless:                 options.Stateless,
 		baseURL:                   options.BaseURL,
+		forwardHeadersEnabled:     options.ForwardHeadersEnabled,
+		forwardHeadersAllowList:   options.ForwardHeadersAllowList,
 	}
 
 	return gs, nil
@@ -285,6 +315,14 @@ func WithStateless(stateless bool) func(*Options) {
 	}
 }
 
+// WithForwardHeaders configures header forwarding to GraphQL requests
+func WithForwardHeaders(enabled bool, allowList []string) func(*Options) {
+	return func(o *Options) {
+		o.ForwardHeadersEnabled = enabled
+		o.ForwardHeadersAllowList = allowList
+	}
+}
+
 // Serve starts the server with the configured options and returns a streamable HTTP server.
 func (s *GraphQLSchemaServer) Serve() (*server.StreamableHTTPServer, error) {
 	// Create custom HTTP server
@@ -295,11 +333,20 @@ func (s *GraphQLSchemaServer) Serve() (*server.StreamableHTTPServer, error) {
 		IdleTimeout:  60 * time.Second,
 	}
 
+	// Create a combined context function that captures both auth and headers
+	contextFunc := func(ctx context.Context, r *http.Request) context.Context {
+		ctx = authFromRequest(ctx, r)
+		if s.forwardHeadersEnabled {
+			ctx = headersFromRequest(ctx, r)
+		}
+		return ctx
+	}
+
 	streamableHTTPServer := server.NewStreamableHTTPServer(s.server,
 		server.WithStreamableHTTPServer(httpServer),
 		server.WithLogger(NewZapAdapter(s.logger.With(zap.String("component", "mcp-server")))),
 		server.WithStateLess(s.stateless),
-		server.WithHTTPContextFunc(authFromRequest),
+		server.WithHTTPContextFunc(contextFunc),
 		server.WithHeartbeatInterval(10*time.Second),
 	)
 
@@ -654,6 +701,39 @@ Important Notes:
 	}
 }
 
+// filterHeaders filters headers based on the allowlist configuration.
+// It supports both exact matches and regex patterns.
+func (s *GraphQLSchemaServer) filterHeaders(headers http.Header) http.Header {
+	if !s.forwardHeadersEnabled || len(s.forwardHeadersAllowList) == 0 {
+		return http.Header{}
+	}
+
+	filtered := http.Header{}
+	
+	for _, pattern := range s.forwardHeadersAllowList {
+		// Try to compile as regex
+		re, err := regexp.Compile("(?i)^" + pattern + "$")
+		if err != nil {
+			// If it's not a valid regex, treat it as an exact match (case-insensitive)
+			for headerName, headerValues := range headers {
+				if strings.EqualFold(headerName, pattern) {
+					filtered[headerName] = headerValues
+				}
+			}
+			continue
+		}
+		
+		// Match using regex
+		for headerName, headerValues := range headers {
+			if re.MatchString(headerName) {
+				filtered[headerName] = headerValues
+			}
+		}
+	}
+	
+	return filtered
+}
+
 // executeGraphQLQuery executes a GraphQL query against the router endpoint
 func (s *GraphQLSchemaServer) executeGraphQLQuery(ctx context.Context, query string, variables json.RawMessage) (*mcp.CallToolResult, error) {
 	// Create the GraphQL request
@@ -675,14 +755,29 @@ func (s *GraphQLSchemaServer) executeGraphQLQuery(ctx context.Context, query str
 	req.Header.Set("Accept", "application/json")
 	req.Header.Set("Content-Type", "application/json; charset=utf-8")
 
+	// Always forward Authorization header (legacy behavior)
 	token, err := tokenFromContext(ctx)
 	if err != nil {
 		s.logger.Debug("failed to get token from context", zap.Error(err))
 	} else if token != "" {
 		req.Header.Set("Authorization", token)
 	}
 
-	// Forward Authorization header if provided
+	// Forward additional headers if enabled
+	if s.forwardHeadersEnabled {
+		if headers, ok := headersFromContext(ctx); ok {
+			filteredHeaders := s.filterHeaders(headers)
+			for headerName, headerValues := range filteredHeaders {
+				// Skip Authorization as it's already handled above
+				if strings.EqualFold(headerName, "Authorization") {
+					continue
+				}
+				for _, headerValue := range headerValues {
+					req.Header.Add(headerName, headerValue)
+				}
+			}
+		}
+	}
 
 	resp, err := s.httpClient.Do(req)
 	if err != nil {