A TypeScript SSE proxy for MCP servers that use stdio transport.
npm install mcp-proxyA TypeScript streamable HTTP and SSE proxy for MCP servers that use stdio transport.
> [!NOTE]
> CORS is enabled by default with configurable options. See CORS Configuration for details.
> [!NOTE]
> For a Python implementation, see mcp-proxy.
> [!NOTE]
> MCP Proxy is what FastMCP uses to enable streamable HTTP and SSE.
``bash`
npm install mcp-proxy
MCP Proxy supports two invocation patterns:
Simple usage (no mcp-proxy options):
`bash`
npx mcp-proxy npx -y @anthropic/mcp-server-filesystem /path
With mcp-proxy options:
`bash`
npx mcp-proxy --port 8080 --shell -- tsx server.js
This starts a server and stdio server (tsx server.js). The server listens on port 8080 and /mcp (streamable HTTP) and /sse (SSE) endpoints, and forwards messages to the stdio server.
> [!NOTE]
> About the -- separator:
> - The -- separator is optional when you don't need to pass options to mcp-proxy--
> - Use when you need to pass options to mcp-proxy (like --port, --shell, etc.) to clearly separate them from the command--
> - Without , the first positional argument is treated as the command, and all subsequent arguments are passed to that command--
> - The separator is also useful when the command itself has flags that might conflict with mcp-proxy options
options:
- --server: Set to sse or stream to only enable the respective transport (default: both)--endpoint
- : If server is set to sse or stream, this option sets the endpoint path (default: /sse or /mcp)--sseEndpoint
- : Set the SSE endpoint path (default: /sse). Overrides --endpoint if server is set to sse.--streamEndpoint
- : Set the streamable HTTP endpoint path (default: /mcp). Overrides --endpoint if server is set to stream.--stateless
- : Enable stateless mode for HTTP streamable transport (no session management). In this mode, each request creates a new server instance instead of maintaining persistent sessions.--port
- : Specify the port to listen on (default: 8080)--connectionTimeout
- : Timeout in milliseconds for the initial connection to the MCP server (default: 60000, which is 60 seconds)--requestTimeout
- : Timeout in milliseconds for requests to the MCP server (default: 300000, which is 5 minutes)--debug
- : Enable debug logging--shell
- : Spawn the server via the user's shell--apiKey
- : API key for authenticating requests (uses X-API-Key header)--sslCa
- : Filename to override the trusted CA certificates--sslCert
- : Cert chains filename in PEM format--sslKey
- : Private keys filename in PEM format--tunnel
- : Expose the proxy via a public tunnel (see Public Tunnel)--tunnelSubdomain
- : Request a specific subdomain for the tunnel (availability not guaranteed)
MCP Proxy can expose your local server to the public internet using a tunnel service. This is useful for testing webhooks, sharing your development server, or accessing your MCP server from anywhere.
`bashExpose your MCP server via a public tunnel
npx mcp-proxy --port 8080 --tunnel -- tsx server.js
When the tunnel is established, you'll see a message like:
tunnel established at https://abcdefghij.tunnel.gla.ma
> [!NOTE]
> The requested subdomain may not be available. The actual URL will be displayed when the tunnel is established.
This feature is powered by pipenet and sponsored by glama.ai. For more information, see the pipenet announcement.
$3
By default, MCP Proxy maintains persistent sessions for HTTP streamable transport, where each client connection is associated with a server instance that stays alive for the duration of the session.
Stateless mode (
) changes this behavior:- No session management: Each request creates a new server instance instead of maintaining persistent sessions
- Simplified deployment: Useful for serverless environments or when you want to minimize memory usage
- Request isolation: Each request is completely independent, which can be beneficial for certain use cases
Example usage:
`bash
Enable stateless mode
npx mcp-proxy --port 8080 --stateless -- tsx server.jsStateless mode with stream-only transport
npx mcp-proxy --port 8080 --stateless --server stream -- tsx server.js
`> [!NOTE]
> Stateless mode only affects HTTP streamable transport (
endpoint). SSE transport behavior remains unchanged.When to use stateless mode:
- Serverless environments: When deploying to platforms like AWS Lambda, Vercel, or similar
- Load balancing: When requests need to be distributed across multiple instances
- Memory optimization: When you want to minimize server memory usage
- Request isolation: When you need complete independence between requests
- Simple deployments: When you don't need to maintain connection state
$3
MCP Proxy supports optional API key authentication to secure your endpoints. When enabled, clients must provide a valid API key in the
X-API-Key header to access the proxy.#### Enabling Authentication
Authentication is disabled by default for backward compatibility. To enable it, provide an API key via:
Command-line:
`bash
npx mcp-proxy --port 8080 --apiKey "your-secret-key" -- tsx server.js
`Environment variable:
bash
export MCP_PROXY_API_KEY="your-secret-key"
npx mcp-proxy --port 8080 -- tsx server.js
`#### Client Configuration
Clients must include the API key in the
header:`typescript
// For streamable HTTP transport
const transport = new StreamableHTTPClientTransport(
new URL("http://localhost:8080/mcp"),
{
headers: {
"X-API-Key": "your-secret-key",
},
},
);// For SSE transport
const transport = new SSEClientTransport(new URL("http://localhost:8080/sse"), {
headers: {
"X-API-Key": "your-secret-key",
},
});
`#### Exempt Endpoints
The following endpoints do not require authentication:
-
- Health check endpoint
- OPTIONS requests - CORS preflight requests#### Security Notes
- Use HTTPS in production: API keys should only be transmitted over secure connections
- Keep keys secure: Never commit API keys to version control
- Generate strong keys: Use cryptographically secure random strings for API keys
- Rotate keys regularly: Change API keys periodically for better security
$3
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:
- Credentials:
- Exposed Headers: #### 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: "*",
},
});
`$3
The Node.js SDK provides several utilities that are used to create a proxy.
####
Sets up a proxy between a server and a client.
ts
const transport = new StdioClientTransport();
const client = new Client();const server = new Server(serverVersion, {
capabilities: {},
});
proxyServer({
server,
client,
capabilities: {},
});
`In this example, the server will proxy all requests to the client and vice versa.
####
Starts a proxy that listens on a
, and sends messages to the attached server via StreamableHTTPServerTransport and SSEServerTransport.`ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { startHTTPServer } from "mcp-proxy";const { close } = await startHTTPServer({
createServer: async () => {
return new Server();
},
eventStore: new InMemoryEventStore(),
port: 8080,
stateless: false, // Optional: enable stateless mode for streamable HTTP transport
});
close();
`Options:
-
: Function that creates a new server instance for each connection
- eventStore: Event store for streamable HTTP transport (optional)
- port: Port number to listen on
- host: Host to bind to (default: "::")
- sseEndpoint: SSE endpoint path (default: "/sse", set to null to disable)
- 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)####
startStdioServerStarts a proxy that listens on a
, and sends messages to the attached sse or streamable server.`ts
import { ServerType, startStdioServer } from "./startStdioServer.js";await startStdioServer({
serverType: ServerType.SSE,
url: "http://127.0.0.1:8080/sse",
});
`####
Taps into a transport and logs events.
ts
import { tapTransport } from "mcp-proxy";const transport = tapTransport(new StdioClientTransport(), (event) => {
console.log(event);
});
`Development
$3
bash
tsx src/bin/mcp-proxy.ts --debug -- tsx src/fixtures/simple-stdio-server.ts
``