feat: forward selected request headers to Grafana (SSE/streamable-http) for SSO/ALB session cookies (#659)

Author: shiva-oai

README.md

@@ -468,6 +468,32 @@ You can add arbitrary HTTP headers to all Grafana API requests using the `GRAFAN
 }
 ```
 
+### Forwarding Headers from the Client (SSE/Streamable-HTTP Only)
+
+When the MCP server runs behind a gateway or reverse proxy that handles SSO (e.g. an AWS ALB with OIDC), each user's session cookie must reach Grafana so it can associate the request with the authenticated user. The `GRAFANA_FORWARD_HEADERS` environment variable enables this by specifying a comma-separated allowlist of header names to copy from the **incoming** HTTP request to every outbound Grafana API request.
+
+This only applies when using SSE (`-t sse`) or streamable-http (`-t streamable-http`) transports. It has no effect in stdio mode.
+
+**Example: forward the session cookie**
+
+```json
+{
+  "env": {
+    "GRAFANA_URL": "https://grafana.internal",
+    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
+    "GRAFANA_FORWARD_HEADERS": "Cookie"
+  }
+}
+```
+
+You can forward multiple headers by separating them with commas:
+
+```
+GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id
+```
+
+Forwarded headers are merged with any headers defined in `GRAFANA_EXTRA_HEADERS`. If a header name appears in both, the value from the incoming request takes precedence for that request.
+
 2. You have several options to install `mcp-grafana`:
 
    - **uvx (recommended)**: If you have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed, no extra setup is needed — `uvx` will automatically download and run the server:

mcpgrafana.go

@@ -10,6 +10,7 @@ import (
 	"log/slog"
 	"net"
 	"net/http"
+	"net/textproto"
 	"net/url"
 	"os"
 	"reflect"
@@ -41,7 +42,8 @@ const (
 	grafanaUsernameEnvVar = "GRAFANA_USERNAME"
 	grafanaPasswordEnvVar = "GRAFANA_PASSWORD"
 
-	grafanaExtraHeadersEnvVar = "GRAFANA_EXTRA_HEADERS"
+	grafanaExtraHeadersEnvVar   = "GRAFANA_EXTRA_HEADERS"
+	grafanaForwardHeadersEnvVar = "GRAFANA_FORWARD_HEADERS"
 
 	grafanaURLHeader                 = "X-Grafana-URL"
 	grafanaServiceAccountTokenHeader = "X-Grafana-Service-Account-Token"
@@ -104,6 +106,67 @@ func extraHeadersFromEnv() map[string]string {
 	return headers
 }
 
+func forwardHeaderNamesFromEnv() []string {
+	raw := os.Getenv(grafanaForwardHeadersEnvVar)
+	if raw == "" {
+		return nil
+	}
+	parts := strings.Split(raw, ",")
+	names := make([]string, 0, len(parts))
+	for _, p := range parts {
+		p = strings.TrimSpace(p)
+		if p != "" {
+			names = append(names, p)
+		}
+	}
+	return names
+}
+
+// forwardedHeadersFromRequest reads GRAFANA_FORWARD_HEADERS and copies matching
+// headers from the incoming HTTP request. Returns nil when no headers match.
+func forwardedHeadersFromRequest(req *http.Request) map[string]string {
+	names := forwardHeaderNamesFromEnv()
+	if len(names) == 0 {
+		return nil
+	}
+	var forwarded map[string]string
+	for _, name := range names {
+		if v := req.Header.Get(name); v != "" {
+			if forwarded == nil {
+				forwarded = make(map[string]string, len(names))
+			}
+			forwarded[name] = v
+		}
+	}
+	return forwarded
+}
+
+// mergeHeaders returns a new map containing all entries from base, with entries
+// from override taking precedence. When both maps are non-empty, header names
+// are canonicalized (via textproto.CanonicalMIMEHeaderKey) so that
+// case-insensitive matches are merged correctly and the documented
+// guarantee—incoming request wins—is upheld. When only one side is present the
+// original key casing is preserved.
+func mergeHeaders(base, override map[string]string) map[string]string {
+	if len(base) == 0 && len(override) == 0 {
+		return nil
+	}
+	if len(override) == 0 {
+		return base
+	}
+	if len(base) == 0 {
+		return override
+	}
+	merged := make(map[string]string, len(base)+len(override))
+	for k, v := range base {
+		merged[textproto.CanonicalMIMEHeaderKey(k)] = v
+	}
+	for k, v := range override {
+		merged[textproto.CanonicalMIMEHeaderKey(k)] = v
+	}
+	return merged
+}
+
 func orgIdFromHeaders(req *http.Request) int64 {
 	orgIDStr := req.Header.Get(client.OrgIDHeader)
 	if orgIDStr == "" {
@@ -487,6 +550,7 @@ type httpContextFunc func(ctx context.Context, req *http.Request) context.Contex
 
 // ExtractGrafanaInfoFromHeaders is a HTTPContextFunc that extracts Grafana configuration from HTTP request headers.
 // It reads X-Grafana-URL and X-Grafana-API-Key headers, falling back to environment variables if headers are not present.
+// Headers listed in GRAFANA_FORWARD_HEADERS are copied from the incoming request and merged with GRAFANA_EXTRA_HEADERS.
 var ExtractGrafanaInfoFromHeaders httpContextFunc = func(ctx context.Context, req *http.Request) context.Context {
 	u, apiKey, basicAuth, orgID := extractKeyGrafanaInfoFromReq(req)
 
@@ -497,7 +561,7 @@ var ExtractGrafanaInfoFromHeaders httpContextFunc = func(ctx context.Context, re
 	config.APIKey = apiKey
 	config.BasicAuth = basicAuth
 	config.OrgID = orgID
-	config.ExtraHeaders = extraHeadersFromEnv()
+	config.ExtraHeaders = mergeHeaders(extraHeadersFromEnv(), forwardedHeadersFromRequest(req))
 	return WithGrafanaConfig(ctx, config)
 }
 

mcpgrafana_test.go

@@ -865,6 +865,154 @@ func TestExtractGrafanaInfoWithExtraHeaders(t *testing.T) {
 	})
 }
 
+func TestForwardHeaderNamesFromEnv(t *testing.T) {
+	t.Run("empty env returns nil", func(t *testing.T) {
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "")
+		names := forwardHeaderNamesFromEnv()
+		assert.Nil(t, names)
+	})
+
+	t.Run("single header", func(t *testing.T) {
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "Cookie")
+		names := forwardHeaderNamesFromEnv()
+		assert.Equal(t, []string{"Cookie"}, names)
+	})
+
+	t.Run("multiple headers with spaces", func(t *testing.T) {
+		t.Setenv("GRAFANA_FORWARD_HEADERS", " Cookie , X-Session-Id , X-Request-Id ")
+		names := forwardHeaderNamesFromEnv()
+		assert.Equal(t, []string{"Cookie", "X-Session-Id", "X-Request-Id"}, names)
+	})
+
+	t.Run("trailing comma ignored", func(t *testing.T) {
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "Cookie,")
+		names := forwardHeaderNamesFromEnv()
+		assert.Equal(t, []string{"Cookie"}, names)
+	})
+}
+
+func TestForwardedHeadersFromRequest(t *testing.T) {
+	t.Run("no env returns nil", func(t *testing.T) {
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "")
+		req, _ := http.NewRequest("GET", "http://example.com", nil)
+		req.Header.Set("Cookie", "session=abc")
+		assert.Nil(t, forwardedHeadersFromRequest(req))
+	})
+
+	t.Run("header present in request", func(t *testing.T) {
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "Cookie")
+		req, _ := http.NewRequest("GET", "http://example.com", nil)
+		req.Header.Set("Cookie", "session=abc")
+		forwarded := forwardedHeadersFromRequest(req)
+		assert.Equal(t, map[string]string{"Cookie": "session=abc"}, forwarded)
+	})
+
+	t.Run("header missing from request returns nil", func(t *testing.T) {
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "Cookie")
+		req, _ := http.NewRequest("GET", "http://example.com", nil)
+		assert.Nil(t, forwardedHeadersFromRequest(req))
+	})
+
+	t.Run("multiple headers partial match", func(t *testing.T) {
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "Cookie,X-Session-Id")
+		req, _ := http.NewRequest("GET", "http://example.com", nil)
+		req.Header.Set("Cookie", "session=abc")
+		forwarded := forwardedHeadersFromRequest(req)
+		assert.Equal(t, map[string]string{"Cookie": "session=abc"}, forwarded)
+	})
+}
+
+func TestMergeHeaders(t *testing.T) {
+	t.Run("both nil", func(t *testing.T) {
+		assert.Nil(t, mergeHeaders(nil, nil))
+	})
+
+	t.Run("base only", func(t *testing.T) {
+		result := mergeHeaders(map[string]string{"A": "1"}, nil)
+		assert.Equal(t, map[string]string{"A": "1"}, result)
+	})
+
+	t.Run("override only", func(t *testing.T) {
+		result := mergeHeaders(nil, map[string]string{"B": "2"})
+		assert.Equal(t, map[string]string{"B": "2"}, result)
+	})
+
+	t.Run("override wins on conflict", func(t *testing.T) {
+		base := map[string]string{"A": "1", "B": "2"}
+		override := map[string]string{"B": "override", "C": "3"}
+		result := mergeHeaders(base, override)
+		assert.Equal(t, map[string]string{"A": "1", "B": "override", "C": "3"}, result)
+	})
+
+	t.Run("case-insensitive header merge: override wins", func(t *testing.T) {
+		base := map[string]string{"cookie": "static"}
+		override := map[string]string{"Cookie": "from-request"}
+		result := mergeHeaders(base, override)
+		assert.Len(t, result, 1)
+		assert.Equal(t, "from-request", result["Cookie"], "forwarded request value must win over extra header")
+	})
+}
+
+func TestExtractGrafanaInfoFromHeadersForwardedHeaders(t *testing.T) {
+	t.Run("forwarded headers merged into config", func(t *testing.T) {
+		t.Setenv("GRAFANA_EXTRA_HEADERS", `{"X-Tenant-ID": "tenant-123"}`)
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "Cookie")
+		req, _ := http.NewRequest("GET", "http://example.com", nil)
+		req.Header.Set("Cookie", "session=user1")
+
+		ctx := ExtractGrafanaInfoFromHeaders(context.Background(), req)
+		config := GrafanaConfigFromContext(ctx)
+		assert.Equal(t, map[string]string{
+			"X-Tenant-Id": "tenant-123",
+			"Cookie":      "session=user1",
+		}, config.ExtraHeaders)
+	})
+
+	t.Run("forwarded header overrides extra header with same name", func(t *testing.T) {
+		t.Setenv("GRAFANA_EXTRA_HEADERS", `{"Cookie": "static-cookie"}`)
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "Cookie")
+		req, _ := http.NewRequest("GET", "http://example.com", nil)
+		req.Header.Set("Cookie", "dynamic-cookie")
+
+		ctx := ExtractGrafanaInfoFromHeaders(context.Background(), req)
+		config := GrafanaConfigFromContext(ctx)
+		assert.Equal(t, "dynamic-cookie", config.ExtraHeaders["Cookie"])
+	})
+
+	t.Run("no forward env uses only extra headers", func(t *testing.T) {
+		t.Setenv("GRAFANA_EXTRA_HEADERS", `{"X-Tenant-ID": "tenant-789"}`)
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "")
+		req, _ := http.NewRequest("GET", "http://example.com", nil)
+		req.Header.Set("Cookie", "session=ignored")
+
+		ctx := ExtractGrafanaInfoFromHeaders(context.Background(), req)
+		config := GrafanaConfigFromContext(ctx)
+		assert.Equal(t, map[string]string{"X-Tenant-ID": "tenant-789"}, config.ExtraHeaders)
+	})
+
+	t.Run("forward header not present in request", func(t *testing.T) {
+		t.Setenv("GRAFANA_EXTRA_HEADERS", "")
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "Cookie")
+		req, _ := http.NewRequest("GET", "http://example.com", nil)
+
+		ctx := ExtractGrafanaInfoFromHeaders(context.Background(), req)
+		config := GrafanaConfigFromContext(ctx)
+		assert.Nil(t, config.ExtraHeaders)
+	})
+
+	t.Run("forwarded Cookie wins when extra headers has lowercase cookie", func(t *testing.T) {
+		t.Setenv("GRAFANA_EXTRA_HEADERS", `{"cookie": "static"}`)
+		t.Setenv("GRAFANA_FORWARD_HEADERS", "Cookie")
+		req, _ := http.NewRequest("GET", "http://example.com", nil)
+		req.Header.Set("Cookie", "session=user2")
+
+		ctx := ExtractGrafanaInfoFromHeaders(context.Background(), req)
+		config := GrafanaConfigFromContext(ctx)
+		assert.Len(t, config.ExtraHeaders, 1)
+		assert.Equal(t, "session=user2", config.ExtraHeaders["Cookie"], "incoming request must take precedence regardless of extra header key case")
+	})
+}
+
 func TestOrgIDRoundTripper(t *testing.T) {
 	t.Run("adds org ID header to request", func(t *testing.T) {
 		var capturedReq *http.Request

server.json

@@ -57,6 +57,13 @@
           "format": "string",
           "isSecret": false,
           "name": "GRAFANA_EXTRA_HEADERS"
+        },
+        {
+          "description": "Comma-separated list of HTTP header names to forward from the incoming request to Grafana (SSE/streamable-http only). Example: Cookie,X-Session-Id",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false,
+          "name": "GRAFANA_FORWARD_HEADERS"
         }
       ]
     }