Forwards all MCP non-transport headers, to downstream methods

Author: bnasslahsen

springdoc-openapi-starter-common-mcp/src/main/java/org/springdoc/ai/mcp/McpRequestContextHolder.java

@@ -0,0 +1,84 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * Copyright 2019-2026 the original author or authors.
+ *  *  *  *  *  *
+ *  *  *  *  *  * Licensed under the Apache License, Version 2.0 (the "License");
+ *  *  *  *  *  * you may not use this file except in compliance with the License.
+ *  *  *  *  *  * You may obtain a copy of the License at
+ *  *  *  *  *  *
+ *  *  *  *  *  *      https://www.apache.org/licenses/LICENSE-2.0
+ *  *  *  *  *  *
+ *  *  *  *  *  * Unless required by applicable law or agreed to in writing, software
+ *  *  *  *  *  * distributed under the License is distributed on an "AS IS" BASIS,
+ *  *  *  *  *  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  *  *  *  *  * See the License for the specific language governing permissions and
+ *  *  *  *  *  * limitations under the License.
+ *  *  *  *  *
+ *  *  *  *
+ *  *  *
+ *  *
+ *
+ */
+
+package org.springdoc.ai.mcp;
+
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * Thread-local holder for HTTP headers captured from inbound MCP requests. Platform-specific
+ * filters ({@code McpAuditMdcFilter} for WebMVC, {@code McpAuditMdcWebFilter} for WebFlux)
+ * populate this holder so that {@link OpenApiToolCallback} can propagate headers
+ * (e.g. {@code Authorization}) to downstream REST API calls.
+ *
+ * <p>Uses a plain {@link ThreadLocal} (not {@link InheritableThreadLocal}) to avoid
+ * leaking credentials to child threads.
+ *
+ * @author bnasslahsen
+ */
+public final class McpRequestContextHolder {
+
+	/**
+	 * Headers to skip when forwarding from inbound requests to downstream API calls.
+	 * These are standard HTTP transport/browser headers that should not be propagated.
+	 */
+	public static final Set<String> SKIP_HEADERS = Set.of("content-type", "content-length", "host", "connection",
+			"accept", "accept-encoding", "accept-language", "user-agent", "origin", "referer", "cookie",
+			"sec-fetch-dest", "sec-fetch-mode", "sec-fetch-site", "sec-ch-ua", "sec-ch-ua-mobile",
+			"sec-ch-ua-platform");
+
+	private static final ThreadLocal<Map<String, String>> HEADERS = new ThreadLocal<>();
+
+	private McpRequestContextHolder() {
+	}
+
+	/**
+	 * Stores the forwardable headers from the current MCP request.
+	 * @param headers the filtered headers to propagate
+	 */
+	public static void setHeaders(Map<String, String> headers) {
+		HEADERS.set(headers);
+	}
+
+	/**
+	 * Returns the forwardable headers captured from the current MCP request,
+	 * or {@code null} if none were set.
+	 * @return the captured headers, or {@code null}
+	 */
+	public static Map<String, String> getHeaders() {
+		return HEADERS.get();
+	}
+
+	/**
+	 * Removes the stored headers. Must be called in a {@code finally} block to
+	 * prevent leaking values across thread-pool reuse.
+	 */
+	public static void clear() {
+		HEADERS.remove();
+	}
+
+}

springdoc-openapi-starter-webflux-mcp/src/main/java/org/springdoc/webflux/ai/McpAuditMdcWebFilter.java

@@ -0,0 +1,151 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * Copyright 2019-2026 the original author or authors.
+ *  *  *  *  *  *
+ *  *  *  *  *  * Licensed under the Apache License, Version 2.0 (the "License");
+ *  *  *  *  *  * you may not use this file except in compliance with the License.
+ *  *  *  *  *  * You may obtain a copy of the License at
+ *  *  *  *  *  *
+ *  *  *  *  *  *      https://www.apache.org/licenses/LICENSE-2.0
+ *  *  *  *  *  *
+ *  *  *  *  *  * Unless required by applicable law or agreed to in writing, software
+ *  *  *  *  *  * distributed under the License is distributed on an "AS IS" BASIS,
+ *  *  *  *  *  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  *  *  *  *  * See the License for the specific language governing permissions and
+ *  *  *  *  *  * limitations under the License.
+ *  *  *  *  *
+ *  *  *  *
+ *  *  *
+ *  *
+ *
+ */
+
+package org.springdoc.webflux.ai;
+
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.slf4j.MDC;
+import org.springdoc.ai.mcp.McpRequestContextHolder;
+import reactor.core.publisher.Mono;
+
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.server.reactive.ServerHttpRequest;
+import org.springframework.web.server.ServerWebExchange;
+import org.springframework.web.server.WebFilter;
+import org.springframework.web.server.WebFilterChain;
+
+/**
+ * Reactive WebFilter that populates SLF4J MDC with the caller's IP address and MCP session
+ * ID, and stores forwardable headers in {@link McpRequestContextHolder} for propagation
+ * to downstream REST API calls.
+ *
+ * <p>This is the WebFlux equivalent of
+ * {@code org.springdoc.webmvc.ai.McpAuditMdcFilter}.
+ *
+ * @author bnasslahsen
+ */
+public class McpAuditMdcWebFilter implements WebFilter {
+
+	/**
+	 * MDC key used by {@link org.springdoc.ai.mcp.McpAuditLogger} to read the client IP
+	 * address.
+	 */
+	private static final String MDC_CLIENT_IP = "clientIp";
+
+	/**
+	 * MDC key used by {@link org.springdoc.ai.mcp.McpAuditLogger} to read the MCP
+	 * session ID.
+	 */
+	private static final String MDC_SESSION_ID = "sessionId";
+
+	/**
+	 * HTTP header set by reverse proxies carrying the originating client IP.
+	 */
+	private static final String HEADER_X_FORWARDED_FOR = "X-Forwarded-For";
+
+	/**
+	 * MCP Streamable HTTP transport header carrying the session identifier.
+	 */
+	private static final String HEADER_MCP_SESSION_ID = "mcp-session-id";
+
+	/**
+	 * The MCP endpoint path to match against.
+	 */
+	private final String mcpEndpoint;
+
+	/**
+	 * Creates a new filter scoped to the given MCP endpoint path.
+	 * @param mcpEndpoint the MCP endpoint path (e.g. {@code /mcp})
+	 */
+	public McpAuditMdcWebFilter(String mcpEndpoint) {
+		this.mcpEndpoint = mcpEndpoint;
+	}
+
+	@Override
+	public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
+		String path = exchange.getRequest().getPath().value();
+		if (!path.startsWith(mcpEndpoint)) {
+			return chain.filter(exchange);
+		}
+		ServerHttpRequest request = exchange.getRequest();
+		MDC.put(MDC_CLIENT_IP, resolveClientIp(request));
+		String sessionId = request.getHeaders().getFirst(HEADER_MCP_SESSION_ID);
+		if (sessionId != null && !sessionId.isBlank()) {
+			MDC.put(MDC_SESSION_ID, sessionId);
+		}
+		McpRequestContextHolder.setHeaders(extractForwardableHeaders(request.getHeaders()));
+		return chain.filter(exchange)
+				.doFinally(signal -> {
+					MDC.remove(MDC_CLIENT_IP);
+					MDC.remove(MDC_SESSION_ID);
+					McpRequestContextHolder.clear();
+				});
+	}
+
+	/**
+	 * Extracts headers that should be forwarded to downstream REST API calls,
+	 * filtering out standard HTTP transport/browser headers.
+	 * @param httpHeaders the reactive request headers
+	 * @return the forwardable headers map
+	 */
+	private Map<String, String> extractForwardableHeaders(HttpHeaders httpHeaders) {
+		Map<String, String> headers = new HashMap<>();
+		httpHeaders.forEach((name, values) -> {
+			if (!McpRequestContextHolder.SKIP_HEADERS.contains(name.toLowerCase()) && !values.isEmpty()) {
+				String value = values.get(0);
+				if (value != null && !value.isEmpty()) {
+					headers.put(name, value);
+				}
+			}
+		});
+		return headers;
+	}
+
+	/**
+	 * Resolves the originating client IP from the request. Prefers the first value in
+	 * {@code X-Forwarded-For} when set, otherwise falls back to the remote address.
+	 * @param request the reactive server request
+	 * @return the resolved client IP address string
+	 */
+	private String resolveClientIp(ServerHttpRequest request) {
+		String forwarded = request.getHeaders().getFirst(HEADER_X_FORWARDED_FOR);
+		if (forwarded != null && !forwarded.isBlank()) {
+			int comma = forwarded.indexOf(',');
+			return (comma >= 0 ? forwarded.substring(0, comma) : forwarded).strip();
+		}
+		InetSocketAddress remoteAddress = request.getRemoteAddress();
+		if (remoteAddress != null) {
+			InetAddress address = remoteAddress.getAddress();
+			return address != null ? address.getHostAddress() : remoteAddress.getHostString();
+		}
+		return "unknown";
+	}
+
+}