mcp-proxy 5.9.0 → 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-CsjPjeWC.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

@@ -72,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>;
 };
@@ -82,6 +90,7 @@ type ServerLike = {
 declare const startHTTPServer: <T extends ServerLike>({
   apiKey,
   authenticate,
+  cors,
   createServer,
   enableJsonResponse,
   eventStore,
@@ -97,6 +106,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 +159,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-DF5lH8jj.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-DF5lH8jj.js}

@@ -15051,6 +15051,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 {
@@ -15289,7 +15330,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 +15341,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 +21589,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-DF5lH8jj.js.map