feat(gateway): add MCP server support (#1558)

## Summary
- Add Model Context Protocol (MCP) endpoint at `/mcp` for tool discovery
and execution
- New MCP servers dialog in playground for managing HTTP-based MCP
server connections
- Integration with chat API to enable MCP tools in conversations

## Test plan
- [ ] Test MCP endpoint responds to tool listing requests
- [ ] Test MCP tool execution through the gateway
- [ ] Verify MCP servers dialog allows adding/removing servers in
playground
- [ ] Test chat completions with MCP tools enabled

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added Model Context Protocol (MCP) support: manage MCP servers
(add/edit/enable/disable, persisted locally) and integrate MCP tools
into chat streaming with tool-name display.

* **Bug Fixes**
* Improved tool detection and more robust cleanup/error handling for MCP
client connections and streaming flows.

* **UI**
* Replaced some filter controls with toggle switches for a cleaner
layout; tool headers now show tool titles.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Luca Steeb (bot) <contact@luca-steeb.com>

Author: 3 people

apps/gateway/package.json

@@ -35,6 +35,7 @@
 		"@llmgateway/logger": "workspace:*",
 		"@llmgateway/models": "workspace:*",
 		"@llmgateway/shared": "workspace:*",
+		"@modelcontextprotocol/sdk": "1.25.3",
 		"@opentelemetry/api": "1.9.0",
 		"@opentelemetry/sdk-node": "0.205.0",
 		"decimal.js": "10.5.0",

apps/gateway/src/app.ts

@@ -18,6 +18,7 @@ import { HealthChecker } from "@llmgateway/shared";
 
 import { anthropic } from "./anthropic/anthropic.js";
 import { chat } from "./chat/chat.js";
+import { mcpHandler, registerMcpOAuthRoutes } from "./mcp/mcp.js";
 import { tracingMiddleware } from "./middleware/tracing.js";
 import { models } from "./models/route.js";
 import { responses } from "./responses/responses.js";
@@ -77,17 +78,29 @@ app.use(
 			"http://localhost:3005",
 			"http://localhost:3006",
 		],
-		allowHeaders: ["Content-Type", "Authorization", "Cache-Control"],
+		allowHeaders: [
+			"Content-Type",
+			"Authorization",
+			"Cache-Control",
+			"x-api-key",
+			"mcp-session-id",
+		],
 		allowMethods: ["POST", "GET", "OPTIONS", "PUT", "PATCH", "DELETE"],
-		exposeHeaders: ["Content-Length"],
+		exposeHeaders: ["Content-Length", "mcp-session-id"],
 		maxAge: 600,
 		credentials: true,
 	}),
 );
 
 // Middleware to check for application/json content type on POST requests
+// Excludes /mcp endpoint which handles its own content type validation
+// Excludes /oauth endpoints which accept form-urlencoded or JSON
 app.use("*", async (c, next) => {
-	if (c.req.method === "POST") {
+	if (
+		c.req.method === "POST" &&
+		!c.req.path.startsWith("/mcp") &&
+		!c.req.path.startsWith("/oauth")
+	) {
 		const contentType = c.req.header("Content-Type");
 		if (!contentType || !contentType.includes("application/json")) {
 			throw new HTTPException(415, {
@@ -237,6 +250,13 @@ v1.route("/responses", responses);
 
 app.route("/v1", v1);
 
+// MCP endpoint - Model Context Protocol server
+app.all("/mcp", mcpHandler);
+
+// Register MCP OAuth routes for Claude Code authentication workaround
+// This adds OAuth endpoints at /.well-known/oauth-authorization-server and /oauth/*
+registerMcpOAuthRoutes(app);
+
 app.doc("/json", config);
 
 app.get("/docs", swaggerUI({ url: "/json" }));

apps/gateway/src/chat/chat.ts

@@ -260,11 +260,25 @@ chat.openapi(completions, async (c) => {
 		plugins,
 	} = validationResult.data;
 
+	// Debug: Log tools received from the AI SDK (development only)
+	if (process.env.NODE_ENV !== "production" && tools && tools.length > 0) {
+		logger.debug("Tools received by gateway", { count: tools.length });
+		for (const tool of tools) {
+			if (tool.type === "function") {
+				logger.debug(`Function tool: ${tool.function?.name || "unknown"}`, {
+					hasParameters: !!tool.function?.parameters,
+					parametersPreview: tool.function?.parameters
+						? JSON.stringify(tool.function.parameters).slice(0, 500)
+						: "none",
+				});
+			} else if (tool.type === "web_search") {
+				logger.debug("Web search tool configured");
+			}
+		}
+	}
+
 	// If web_search parameter is true, automatically add the web_search tool
-	if (
-		web_search &&
-		(!tools || !tools.some((t: any) => t.type === "web_search"))
-	) {
+	if (web_search && (!tools || !tools.some((t) => t.type === "web_search"))) {
 		tools = tools || [];
 		tools.push({
 			type: "web_search" as const,