Content
# MCP Proxy
A TypeScript streamable HTTP and SSE proxy for [MCP](https://modelcontextprotocol.io/) servers that use `stdio` transport.
> [!NOTE]
> 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).
> [!NOTE]
> MCP Proxy is what [FastMCP](https://github.com/punkpeye/fastmcp) uses to enable streamable HTTP and SSE.
## Installation
```bash
npm install mcp-proxy
```
## Quickstart
### Command-line
```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.
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)
- `--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)
### Passing arguments to the wrapped command
When wrapping a command that takes arguments starting with `-`, you must use `--` to prevent `mcp-proxy` from interpreting them as its own options. Everything after `--` is passed directly to the wrapped command.
For example, to wrap a command that uses the `-v` flag:
```bash
# Wrong: mcp-proxy will try to parse -v as its own option
npx mcp-proxy --port 8080 my-command -v
# Correct: use -- to pass -v to my-command
npx mcp-proxy --port 8080 -- my-command -v
```
### Stateless Mode
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 (`--stateless`) 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.js
# Stateless mode with stream-only transport
npx mcp-proxy --port 8080 --stateless --server stream tsx server.js
```
> [!NOTE]
> Stateless mode only affects HTTP streamable transport (`/mcp` 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
### API Key Authentication
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 `X-API-Key` 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:
- `/ping` - 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
### 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.
#### `proxyServer`
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.
#### `startHTTPServer`
Starts a proxy that listens on a `port`, 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:
- `createServer`: 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)
#### `startStdioServer`
Starts a proxy that listens on a `stdio`, 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",
});
```
#### `tapTransport`
Taps into a transport and logs events.
```ts
import { tapTransport } from "mcp-proxy";
const transport = tapTransport(new StdioClientTransport(), (event) => {
console.log(event);
});
```
## Development
### Running MCP Proxy with a local server
```bash
tsx src/bin/mcp-proxy.ts --debug tsx src/fixtures/simple-stdio-server.ts
```
