mcp-proxy 5.9.0 → 5.11.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-CsjPjeWC.js";
+import { Client, InMemoryEventStore, ReadBuffer, Server, __commonJS, __toESM, proxyServer, serializeMessage, startHTTPServer } from "../stdio-BEX6di72.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

@@ -11,15 +11,25 @@ import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 interface AuthConfig {
   apiKey?: string;
   oauth?: {
+    error?: string;
+    error_description?: string;
+    error_uri?: string;
     protectedResource?: {
       resource?: string;
     };
+    realm?: string;
+    scope?: string;
   };
 }
 declare class AuthenticationMiddleware {
   private config;
   constructor(config?: AuthConfig);
-  getUnauthorizedResponse(): {
+  getUnauthorizedResponse(options?: {
+    error?: string;
+    error_description?: string;
+    error_uri?: string;
+    scope?: string;
+  }): {
     body: string;
     headers: Record<string, string>;
   };
@@ -72,6 +82,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>;
 };
@@ -82,6 +100,7 @@ type ServerLike = {
 declare const startHTTPServer: <T extends ServerLike>({
   apiKey,
   authenticate,
+  cors,
   createServer,
   enableJsonResponse,
   eventStore,
@@ -97,6 +116,7 @@ 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;
@@ -149,5 +169,5 @@ type TransportEvent = {
 };
 declare const tapTransport: (transport: Transport, eventHandler: (event: TransportEvent) => void) => Transport;
 //#endregion
-export { type AuthConfig, AuthenticationMiddleware, 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 { 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-CsjPjeWC.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-BEX6di72.js";
 import process from "node:process";
 
 //#region node_modules/.pnpm/eventsource-parser@3.0.6/node_modules/eventsource-parser/dist/index.js

package/dist/{stdio-CsjPjeWC.js → stdio-BEX6di72.js}

@@ -35,14 +35,27 @@ var AuthenticationMiddleware = class {
 	constructor(config = {}) {
 		this.config = config;
 	}
-	getUnauthorizedResponse() {
+	getUnauthorizedResponse(options) {
 		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"`;
+		if (this.config.oauth) {
+			const params = [];
+			if (this.config.oauth.realm) params.push(`realm="${this.config.oauth.realm}"`);
+			if (this.config.oauth.protectedResource?.resource) params.push(`resource_metadata="${this.config.oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`);
+			const error = options?.error || this.config.oauth.error || "invalid_token";
+			params.push(`error="${error}"`);
+			const escaped = (options?.error_description || this.config.oauth.error_description || "Unauthorized: Invalid or missing API key").replace(/"/g, "\\\"");
+			params.push(`error_description="${escaped}"`);
+			const error_uri = options?.error_uri || this.config.oauth.error_uri;
+			if (error_uri) params.push(`error_uri="${error_uri}"`);
+			const scope = options?.scope || this.config.oauth.scope;
+			if (scope) params.push(`scope="${scope}"`);
+			if (params.length > 0) headers["WWW-Authenticate"] = `Bearer ${params.join(", ")}`;
+		}
 		return {
 			body: JSON.stringify({
 				error: {
 					code: 401,
-					message: "Unauthorized: Invalid or missing API key"
+					message: options?.error_description || "Unauthorized: Invalid or missing API key"
 				},
 				id: null,
 				jsonrpc: "2.0"
@@ -15026,19 +15039,37 @@ 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 getWWWAuthenticateHeader = (oauth, options) => {
+	if (!oauth) return;
+	const params = [];
+	if (oauth.realm) params.push(`realm="${oauth.realm}"`);
+	if (oauth.protectedResource?.resource) params.push(`resource_metadata="${oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`);
+	const error = options?.error || oauth.error;
+	if (error) params.push(`error="${error}"`);
+	const error_description = options?.error_description || oauth.error_description;
+	if (error_description) {
+		const escaped = error_description.replace(/"/g, "\\\"");
+		params.push(`error_description="${escaped}"`);
+	}
+	const error_uri = options?.error_uri || oauth.error_uri;
+	if (error_uri) params.push(`error_uri="${error_uri}"`);
+	const scope = options?.scope || oauth.scope;
+	if (scope) params.push(`scope="${scope}"`);
+	if (params.length === 0) return;
+	return `Bearer ${params.join(", ")}`;
 };
-const handleResponseError = (error, res) => {
-	if (error instanceof Response) {
+const handleResponseError = async (error, res) => {
+	if (error && typeof error === "object" && "status" in error && "headers" in error && "statusText" in error || error instanceof Response) {
+		const responseError = error;
 		const fixedHeaders = {};
-		error.headers.forEach((value, key$1) => {
+		responseError.headers.forEach((value, key$1) => {
 			if (fixedHeaders[key$1]) if (Array.isArray(fixedHeaders[key$1])) fixedHeaders[key$1].push(value);
 			else fixedHeaders[key$1] = [fixedHeaders[key$1], value];
 			else fixedHeaders[key$1] = value;
 		});
-		res.writeHead(error.status, error.statusText, fixedHeaders).end(error.statusText);
+		const body = await responseError.text();
+		res.writeHead(responseError.status, responseError.statusText, fixedHeaders);
+		res.end(body);
 		return true;
 	}
 	return false;
@@ -15051,6 +15082,47 @@ const cleanupServer = async (server, onClose) => {
 		console.error("[mcp-proxy] error closing server", error);
 	}
 };
+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 {
@@ -15063,7 +15135,10 @@ 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);
+					const wwwAuthHeader = getWWWAuthenticateHeader(oauth, {
+						error: "invalid_token",
+						error_description: errorMessage
+					});
 					if (wwwAuthHeader) res.setHeader("WWW-Authenticate", wwwAuthHeader);
 					res.writeHead(401).end(JSON.stringify({
 						error: {
@@ -15076,10 +15151,14 @@ const handleStreamRequest = async ({ activeTransports, authenticate, createServe
 					return true;
 				}
 			} catch (error) {
+				if (await handleResponseError(error, res)) return true;
 				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);
+				const wwwAuthHeader = getWWWAuthenticateHeader(oauth, {
+					error: "invalid_token",
+					error_description: errorMessage
+				});
 				if (wwwAuthHeader) res.setHeader("WWW-Authenticate", wwwAuthHeader);
 				res.writeHead(401).end(JSON.stringify({
 					error: {
@@ -15125,10 +15204,14 @@ const handleStreamRequest = async ({ activeTransports, authenticate, createServe
 				try {
 					server = await createServer(req);
 				} catch (error) {
+					if (await handleResponseError(error, res)) return true;
 					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);
+						const wwwAuthHeader = getWWWAuthenticateHeader(oauth, {
+							error: "invalid_token",
+							error_description: errorMessage
+						});
 						if (wwwAuthHeader) res.setHeader("WWW-Authenticate", wwwAuthHeader);
 						res.writeHead(401).end(JSON.stringify({
 							error: {
@@ -15140,7 +15223,6 @@ const handleStreamRequest = async ({ activeTransports, authenticate, createServe
 						}));
 						return true;
 					}
-					if (handleResponseError(error, res)) return true;
 					res.writeHead(500).end("Error creating server");
 					return true;
 				}
@@ -15158,10 +15240,14 @@ const handleStreamRequest = async ({ activeTransports, authenticate, createServe
 				try {
 					server = await createServer(req);
 				} catch (error) {
+					if (await handleResponseError(error, res)) return true;
 					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);
+						const wwwAuthHeader = getWWWAuthenticateHeader(oauth, {
+							error: "invalid_token",
+							error_description: errorMessage
+						});
 						if (wwwAuthHeader) res.setHeader("WWW-Authenticate", wwwAuthHeader);
 						res.writeHead(401).end(JSON.stringify({
 							error: {
@@ -15173,7 +15259,6 @@ const handleStreamRequest = async ({ activeTransports, authenticate, createServe
 						}));
 						return true;
 					}
-					if (handleResponseError(error, res)) return true;
 					res.writeHead(500).end("Error creating server");
 					return true;
 				}
@@ -15243,7 +15328,7 @@ const handleSSERequest = async ({ activeTransports, createServer, endpoint, onCl
 		try {
 			server = await createServer(req);
 		} catch (error) {
-			if (handleResponseError(error, res)) return true;
+			if (await handleResponseError(error, res)) return true;
 			res.writeHead(500).end("Error creating server");
 			return true;
 		}
@@ -15289,7 +15374,7 @@ const handleSSERequest = async ({ activeTransports, createServer, endpoint, onCl
 	}
 	return false;
 };
-const startHTTPServer = async ({ apiKey, authenticate, createServer, enableJsonResponse, eventStore, host = "::", oauth, 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({
@@ -15300,16 +15385,7 @@ const startHTTPServer = async ({ apiKey, authenticate, createServer, enableJsonR
 	* @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();
@@ -21557,4 +21633,4 @@ function serializeMessage(message) {
 
 //#endregion
 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-CsjPjeWC.js.map
+//# sourceMappingURL=stdio-BEX6di72.js.map