mcp-proxy 5.8.1 → 5.10.0

package/README.md

@@ -3,7 +3,7 @@
 A TypeScript streamable HTTP and SSE proxy for [MCP](https://modelcontextprotocol.io/) servers that use `stdio` transport.
 
 > [!NOTE]
-> CORS is enabled by default.
+> CORS is enabled by default with configurable options. See [CORS Configuration](#cors-configuration) for details.
 
 > [!NOTE]
 > For a Python implementation, see [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy).
@@ -143,6 +143,152 @@ The following endpoints do not require authentication:
 - **Generate strong keys**: Use cryptographically secure random strings for API keys
 - **Rotate keys regularly**: Change API keys periodically for better security
 
+### CORS Configuration
+
+MCP Proxy provides flexible CORS (Cross-Origin Resource Sharing) configuration to control how browsers can access your MCP server from different origins.
+
+#### Default Behavior
+
+By default, CORS is enabled with the following settings:
+- **Origin**: `*` (allow all origins)
+- **Methods**: `GET, POST, OPTIONS`
+- **Headers**: `Content-Type, Authorization, Accept, Mcp-Session-Id, Last-Event-Id`
+- **Credentials**: `true`
+- **Exposed Headers**: `Mcp-Session-Id`
+
+#### Basic Configuration
+
+```typescript
+import { startHTTPServer } from 'mcp-proxy';
+
+// Use default CORS settings (backward compatible)
+await startHTTPServer({
+  createServer: async () => { /* ... */ },
+  port: 3000,
+});
+
+// Explicitly enable default CORS
+await startHTTPServer({
+  createServer: async () => { /* ... */ },
+  port: 3000,
+  cors: true,
+});
+
+// Disable CORS completely
+await startHTTPServer({
+  createServer: async () => { /* ... */ },
+  port: 3000,
+  cors: false,
+});
+```
+
+#### Advanced CORS Configuration
+
+For more control over CORS behavior, you can provide a detailed configuration:
+
+```typescript
+import { startHTTPServer, CorsOptions } from 'mcp-proxy';
+
+const corsOptions: CorsOptions = {
+  // Allow specific origins
+  origin: ['https://app.example.com', 'https://admin.example.com'],
+  
+  // Or use a function for dynamic origin validation
+  origin: (origin: string) => origin.endsWith('.example.com'),
+  
+  // Specify allowed methods
+  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+  
+  // Allow any headers (useful for browser clients with custom headers)
+  allowedHeaders: '*',
+  
+  // Or specify exact headers
+  allowedHeaders: [
+    'Content-Type',
+    'Authorization',
+    'Accept',
+    'Mcp-Session-Id',
+    'Last-Event-Id',
+    'X-Custom-Header',
+    'X-API-Key'
+  ],
+  
+  // Headers to expose to the client
+  exposedHeaders: ['Mcp-Session-Id', 'X-Total-Count'],
+  
+  // Allow credentials
+  credentials: true,
+  
+  // Cache preflight requests for 24 hours
+  maxAge: 86400,
+};
+
+await startHTTPServer({
+  createServer: async () => { /* ... */ },
+  port: 3000,
+  cors: corsOptions,
+});
+```
+
+#### Common Use Cases
+
+**Allow any custom headers (solves browser CORS issues):**
+```typescript
+await startHTTPServer({
+  createServer: async () => { /* ... */ },
+  port: 3000,
+  cors: {
+    allowedHeaders: '*', // Allows X-Custom-Header, X-API-Key, etc.
+  },
+});
+```
+
+**Restrict to specific domains:**
+```typescript
+await startHTTPServer({
+  createServer: async () => { /* ... */ },
+  port: 3000,
+  cors: {
+    origin: ['https://myapp.com', 'https://admin.myapp.com'],
+    allowedHeaders: '*',
+  },
+});
+```
+
+**Development-friendly settings:**
+```typescript
+await startHTTPServer({
+  createServer: async () => { /* ... */ },
+  port: 3000,
+  cors: {
+    origin: ['http://localhost:3000', 'http://localhost:5173'], // Common dev ports
+    allowedHeaders: '*',
+    credentials: true,
+  },
+});
+```
+
+#### Migration from Older Versions
+
+If you were using mcp-proxy 5.5.6 and want the same permissive behavior in 5.9.0+:
+
+```typescript
+// Old behavior (5.5.6) - automatic wildcard headers
+await startHTTPServer({
+  createServer: async () => { /* ... */ },
+  port: 3000,
+});
+
+// New equivalent (5.9.0+) - explicit wildcard headers
+await startHTTPServer({
+  createServer: async () => { /* ... */ },
+  port: 3000,
+  cors: {
+    allowedHeaders: '*',
+  },
+});
+```
+
 ### Node.js SDK
 
 The Node.js SDK provides several utilities that are used to create a proxy.
@@ -198,6 +344,7 @@ Options:
 - `streamEndpoint`: Streamable HTTP endpoint path (default: "/mcp", set to null to disable)
 - `stateless`: Enable stateless mode for HTTP streamable transport (default: false)
 - `apiKey`: API key for authenticating requests (optional)
+- `cors`: CORS configuration (default: enabled with permissive settings, see CORS Configuration section)
 - `onConnect`: Callback when a server connects (optional)
 - `onClose`: Callback when a server disconnects (optional)
 - `onUnhandledRequest`: Callback for unhandled HTTP requests (optional)

package/dist/bin/mcp-proxy.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Client, InMemoryEventStore, ReadBuffer, Server, __commonJS, __toESM, proxyServer, serializeMessage, startHTTPServer } from "../stdio-9KZaSDCW.js";
+import { Client, InMemoryEventStore, ReadBuffer, Server, __commonJS, __toESM, proxyServer, serializeMessage, startHTTPServer } from "../stdio-DF5lH8jj.js";
 import { createRequire } from "node:module";
 import { basename, dirname, extname, join, normalize, relative, resolve } from "path";
 import { format, inspect } from "util";

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import http from "http";
+import http, { IncomingMessage } from "http";
 import { EventStore } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { JSONRPCMessage, ServerCapabilities } from "@modelcontextprotocol/sdk/types.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -7,8 +7,26 @@ import { SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.
 import { StreamableHTTPClientTransportOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 
+//#region src/authentication.d.ts
+interface AuthConfig {
+  apiKey?: string;
+  oauth?: {
+    protectedResource?: {
+      resource?: string;
+    };
+  };
+}
+declare class AuthenticationMiddleware {
+  private config;
+  constructor(config?: AuthConfig);
+  getUnauthorizedResponse(): {
+    body: string;
+    headers: Record<string, string>;
+  };
+  validateRequest(req: IncomingMessage): boolean;
+}
+//#endregion
 //#region src/InMemoryEventStore.d.ts
-
 /**
  * Simple in-memory implementation of the EventStore interface for resumability
  * This is primarily intended for examples and testing, not for production use
@@ -54,6 +72,14 @@ declare const proxyServer: ({
 }) => Promise<void>;
 //#endregion
 //#region src/startHTTPServer.d.ts
+interface CorsOptions {
+  allowedHeaders?: string | string[];
+  credentials?: boolean;
+  exposedHeaders?: string[];
+  maxAge?: number;
+  methods?: string[];
+  origin?: ((origin: string) => boolean) | string | string[];
+}
 type SSEServer = {
   close: () => Promise<void>;
 };
@@ -64,10 +90,12 @@ type ServerLike = {
 declare const startHTTPServer: <T extends ServerLike>({
   apiKey,
   authenticate,
+  cors,
   createServer,
   enableJsonResponse,
   eventStore,
   host,
+  oauth,
   onClose,
   onConnect,
   onUnhandledRequest,
@@ -78,10 +106,12 @@ declare const startHTTPServer: <T extends ServerLike>({
 }: {
   apiKey?: string;
   authenticate?: (request: http.IncomingMessage) => Promise<unknown>;
+  cors?: boolean | CorsOptions;
   createServer: (request: http.IncomingMessage) => Promise<T>;
   enableJsonResponse?: boolean;
   eventStore?: EventStore;
   host?: string;
+  oauth?: AuthConfig["oauth"];
   onClose?: (server: T) => Promise<void>;
   onConnect?: (server: T) => Promise<void>;
   onUnhandledRequest?: (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
@@ -129,5 +159,5 @@ type TransportEvent = {
 };
 declare const tapTransport: (transport: Transport, eventHandler: (event: TransportEvent) => void) => Transport;
 //#endregion
-export { InMemoryEventStore, ServerType, proxyServer, startHTTPServer, startStdioServer, tapTransport };
+export { type AuthConfig, AuthenticationMiddleware, type CorsOptions, InMemoryEventStore, ServerType, proxyServer, startHTTPServer, startStdioServer, tapTransport };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Client, InMemoryEventStore, JSONRPCMessageSchema, LATEST_PROTOCOL_VERSION, NEVER, ReadBuffer, Server, ZodIssueCode, anyType, arrayType, booleanType, isInitializedNotification, isJSONRPCRequest, isJSONRPCResponse, numberType, objectType, proxyServer, serializeMessage, startHTTPServer, stringType } from "./stdio-9KZaSDCW.js";
+import { AuthenticationMiddleware, Client, InMemoryEventStore, JSONRPCMessageSchema, LATEST_PROTOCOL_VERSION, NEVER, ReadBuffer, Server, ZodIssueCode, anyType, arrayType, booleanType, isInitializedNotification, isJSONRPCRequest, isJSONRPCResponse, numberType, objectType, proxyServer, serializeMessage, startHTTPServer, stringType } from "./stdio-DF5lH8jj.js";
 import process from "node:process";
 
 //#region node_modules/.pnpm/eventsource-parser@3.0.6/node_modules/eventsource-parser/dist/index.js
@@ -1850,5 +1850,5 @@ const tapTransport = (transport, eventHandler) => {
 };
 
 //#endregion
-export { InMemoryEventStore, ServerType, proxyServer, startHTTPServer, startStdioServer, tapTransport };
+export { AuthenticationMiddleware, InMemoryEventStore, ServerType, proxyServer, startHTTPServer, startStdioServer, tapTransport };
 //# sourceMappingURL=index.js.map

package/dist/{stdio-9KZaSDCW.js → stdio-DF5lH8jj.js}

@@ -29,6 +29,35 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+//#endregion
+//#region src/authentication.ts
+var AuthenticationMiddleware = class {
+	constructor(config = {}) {
+		this.config = config;
+	}
+	getUnauthorizedResponse() {
+		const headers = { "Content-Type": "application/json" };
+		if (this.config.oauth?.protectedResource?.resource) headers["WWW-Authenticate"] = `Bearer resource_metadata="${this.config.oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`;
+		return {
+			body: JSON.stringify({
+				error: {
+					code: 401,
+					message: "Unauthorized: Invalid or missing API key"
+				},
+				id: null,
+				jsonrpc: "2.0"
+			}),
+			headers
+		};
+	}
+	validateRequest(req) {
+		if (!this.config.apiKey) return true;
+		const apiKey = req.headers["x-api-key"];
+		if (!apiKey || typeof apiKey !== "string") return false;
+		return apiKey === this.config.apiKey;
+	}
+};
+
 //#endregion
 //#region src/InMemoryEventStore.ts
 /**
@@ -14968,33 +14997,6 @@ var StreamableHTTPServerTransport = class {
 	}
 };
 
-//#endregion
-//#region src/authentication.ts
-var AuthenticationMiddleware = class {
-	constructor(config = {}) {
-		this.config = config;
-	}
-	getUnauthorizedResponse() {
-		return {
-			body: JSON.stringify({
-				error: {
-					code: 401,
-					message: "Unauthorized: Invalid or missing API key"
-				},
-				id: null,
-				jsonrpc: "2.0"
-			}),
-			headers: { "Content-Type": "application/json" }
-		};
-	}
-	validateRequest(req) {
-		if (!this.config.apiKey) return true;
-		const apiKey = req.headers["x-api-key"];
-		if (!apiKey || typeof apiKey !== "string") return false;
-		return apiKey === this.config.apiKey;
-	}
-};
-
 //#endregion
 //#region src/startHTTPServer.ts
 const getBody = (request) => {
@@ -15024,6 +15026,10 @@ const createJsonRpcErrorResponse = (code, message) => {
 		jsonrpc: "2.0"
 	});
 };
+const getWWWAuthenticateHeader = (oauth) => {
+	if (!oauth?.protectedResource?.resource) return;
+	return `Bearer resource_metadata="${oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`;
+};
 const handleResponseError = (error, res) => {
 	if (error instanceof Response) {
 		const fixedHeaders = {};
@@ -15045,7 +15051,48 @@ const cleanupServer = async (server, onClose) => {
 		console.error("[mcp-proxy] error closing server", error);
 	}
 };
-const handleStreamRequest = async ({ activeTransports, authenticate, createServer, enableJsonResponse, endpoint, eventStore, onClose, onConnect, req, res, stateless }) => {
+const applyCorsHeaders = (req, res, corsOptions) => {
+	if (!req.headers.origin) return;
+	const defaultCorsOptions = {
+		allowedHeaders: "Content-Type, Authorization, Accept, Mcp-Session-Id, Last-Event-Id",
+		credentials: true,
+		exposedHeaders: ["Mcp-Session-Id"],
+		methods: [
+			"GET",
+			"POST",
+			"OPTIONS"
+		],
+		origin: "*"
+	};
+	let finalCorsOptions;
+	if (corsOptions === false) return;
+	else if (corsOptions === true || corsOptions === void 0) finalCorsOptions = defaultCorsOptions;
+	else finalCorsOptions = {
+		...defaultCorsOptions,
+		...corsOptions
+	};
+	try {
+		const origin = new URL(req.headers.origin);
+		let allowedOrigin = "*";
+		if (finalCorsOptions.origin) {
+			if (typeof finalCorsOptions.origin === "string") allowedOrigin = finalCorsOptions.origin;
+			else if (Array.isArray(finalCorsOptions.origin)) allowedOrigin = finalCorsOptions.origin.includes(origin.origin) ? origin.origin : "false";
+			else if (typeof finalCorsOptions.origin === "function") allowedOrigin = finalCorsOptions.origin(origin.origin) ? origin.origin : "false";
+		}
+		if (allowedOrigin !== "false") res.setHeader("Access-Control-Allow-Origin", allowedOrigin);
+		if (finalCorsOptions.credentials !== void 0) res.setHeader("Access-Control-Allow-Credentials", finalCorsOptions.credentials.toString());
+		if (finalCorsOptions.methods) res.setHeader("Access-Control-Allow-Methods", finalCorsOptions.methods.join(", "));
+		if (finalCorsOptions.allowedHeaders) {
+			const allowedHeaders = typeof finalCorsOptions.allowedHeaders === "string" ? finalCorsOptions.allowedHeaders : finalCorsOptions.allowedHeaders.join(", ");
+			res.setHeader("Access-Control-Allow-Headers", allowedHeaders);
+		}
+		if (finalCorsOptions.exposedHeaders) res.setHeader("Access-Control-Expose-Headers", finalCorsOptions.exposedHeaders.join(", "));
+		if (finalCorsOptions.maxAge !== void 0) res.setHeader("Access-Control-Max-Age", finalCorsOptions.maxAge.toString());
+	} catch (error) {
+		console.error("[mcp-proxy] error parsing origin", error);
+	}
+};
+const handleStreamRequest = async ({ activeTransports, authenticate, createServer, enableJsonResponse, endpoint, eventStore, oauth, onClose, onConnect, req, res, stateless }) => {
 	if (req.method === "POST" && new URL(req.url, "http://localhost").pathname === endpoint) {
 		try {
 			const sessionId = Array.isArray(req.headers["mcp-session-id"]) ? req.headers["mcp-session-id"][0] : req.headers["mcp-session-id"];
@@ -15057,6 +15104,8 @@ const handleStreamRequest = async ({ activeTransports, authenticate, createServe
 				if (!authResult || typeof authResult === "object" && "authenticated" in authResult && !authResult.authenticated) {
 					const errorMessage = authResult && typeof authResult === "object" && "error" in authResult && typeof authResult.error === "string" ? authResult.error : "Unauthorized: Authentication failed";
 					res.setHeader("Content-Type", "application/json");
+					const wwwAuthHeader = getWWWAuthenticateHeader(oauth);
+					if (wwwAuthHeader) res.setHeader("WWW-Authenticate", wwwAuthHeader);
 					res.writeHead(401).end(JSON.stringify({
 						error: {
 							code: -32e3,
@@ -15071,6 +15120,8 @@ const handleStreamRequest = async ({ activeTransports, authenticate, createServe
 				const errorMessage = error instanceof Error ? error.message : "Unauthorized: Authentication error";
 				console.error("Authentication error:", error);
 				res.setHeader("Content-Type", "application/json");
+				const wwwAuthHeader = getWWWAuthenticateHeader(oauth);
+				if (wwwAuthHeader) res.setHeader("WWW-Authenticate", wwwAuthHeader);
 				res.writeHead(401).end(JSON.stringify({
 					error: {
 						code: -32e3,
@@ -15118,6 +15169,8 @@ const handleStreamRequest = async ({ activeTransports, authenticate, createServe
 					const errorMessage = error instanceof Error ? error.message : String(error);
 					if (errorMessage.includes("Authentication") || errorMessage.includes("Invalid JWT") || errorMessage.includes("Token") || errorMessage.includes("Unauthorized")) {
 						res.setHeader("Content-Type", "application/json");
+						const wwwAuthHeader = getWWWAuthenticateHeader(oauth);
+						if (wwwAuthHeader) res.setHeader("WWW-Authenticate", wwwAuthHeader);
 						res.writeHead(401).end(JSON.stringify({
 							error: {
 								code: -32e3,
@@ -15149,6 +15202,8 @@ const handleStreamRequest = async ({ activeTransports, authenticate, createServe
 					const errorMessage = error instanceof Error ? error.message : String(error);
 					if (errorMessage.includes("Authentication") || errorMessage.includes("Invalid JWT") || errorMessage.includes("Token") || errorMessage.includes("Unauthorized")) {
 						res.setHeader("Content-Type", "application/json");
+						const wwwAuthHeader = getWWWAuthenticateHeader(oauth);
+						if (wwwAuthHeader) res.setHeader("WWW-Authenticate", wwwAuthHeader);
 						res.writeHead(401).end(JSON.stringify({
 							error: {
 								code: -32e3,
@@ -15275,24 +15330,18 @@ const handleSSERequest = async ({ activeTransports, createServer, endpoint, onCl
 	}
 	return false;
 };
-const startHTTPServer = async ({ apiKey, authenticate, createServer, enableJsonResponse, eventStore, host = "::", onClose, onConnect, onUnhandledRequest, port, sseEndpoint = "/sse", stateless, streamEndpoint = "/mcp" }) => {
+const startHTTPServer = async ({ apiKey, authenticate, cors, createServer, enableJsonResponse, eventStore, host = "::", oauth, onClose, onConnect, onUnhandledRequest, port, sseEndpoint = "/sse", stateless, streamEndpoint = "/mcp" }) => {
 	const activeSSETransports = {};
 	const activeStreamTransports = {};
-	const authMiddleware = new AuthenticationMiddleware({ apiKey });
+	const authMiddleware = new AuthenticationMiddleware({
+		apiKey,
+		oauth
+	});
 	/**
 	* @author https://dev.classmethod.jp/articles/mcp-sse/
 	*/
 	const httpServer = http.createServer(async (req, res) => {
-		if (req.headers.origin) try {
-			const origin = new URL(req.headers.origin);
-			res.setHeader("Access-Control-Allow-Origin", origin.origin);
-			res.setHeader("Access-Control-Allow-Credentials", "true");
-			res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-			res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, Accept, Mcp-Session-Id, Last-Event-Id");
-			res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
-		} catch (error) {
-			console.error("[mcp-proxy] error parsing origin", error);
-		}
+		applyCorsHeaders(req, res, cors);
 		if (req.method === "OPTIONS") {
 			res.writeHead(204);
 			res.end();
@@ -15324,6 +15373,7 @@ const startHTTPServer = async ({ apiKey, authenticate, createServer, enableJsonR
 			enableJsonResponse,
 			endpoint: streamEndpoint,
 			eventStore,
+			oauth,
 			onClose,
 			onConnect,
 			req,
@@ -21538,5 +21588,5 @@ function serializeMessage(message) {
 }
 
 //#endregion
-export { Client, InMemoryEventStore, JSONRPCMessageSchema, LATEST_PROTOCOL_VERSION, NEVER, ReadBuffer, Server, ZodIssueCode, __commonJS, __toESM, anyType, arrayType, booleanType, isInitializedNotification, isJSONRPCRequest, isJSONRPCResponse, numberType, objectType, proxyServer, serializeMessage, startHTTPServer, stringType };
-//# sourceMappingURL=stdio-9KZaSDCW.js.map
+export { AuthenticationMiddleware, Client, InMemoryEventStore, JSONRPCMessageSchema, LATEST_PROTOCOL_VERSION, NEVER, ReadBuffer, Server, ZodIssueCode, __commonJS, __toESM, anyType, arrayType, booleanType, isInitializedNotification, isJSONRPCRequest, isJSONRPCResponse, numberType, objectType, proxyServer, serializeMessage, startHTTPServer, stringType };
+//# sourceMappingURL=stdio-DF5lH8jj.js.map