mcp-proxy/README.md

A TypeScript SSE proxy for MCP servers that use stdio transport.

# 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

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)
- `--keepAliveTimeout`: HTTP keep-alive timeout in milliseconds for stateful stream sessions (default: 300000, which is 5 minutes)
- `--eventStore`: Enable the streamable HTTP transport's resumability event store, which lets clients replay missed messages after a reconnect (default: `true`). Use `--no-eventStore` to disable it entirely for request/response-only deployments that don't need replay and would rather avoid the memory overhead. See [Resumability and memory use](#resumability-and-memory-use).
- `--eventStoreMaxEvents`: Maximum number of buffered events the resumability event store retains per session before it evicts the oldest (default: 1000). Ignored when `--no-eventStore` is set.
- `--maxBodySize`: Maximum request body size in bytes accepted by the streamable HTTP endpoint; larger requests are answered with `413 Payload Too Large` (default: 10485760, which is 10 MiB). Set to `0` to disable the limit. See [Request body size](#request-body-size).
- `--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](#public-tunnel))
- `--tunnelSubdomain`: Request a specific subdomain for the tunnel (availability not guaranteed)
- `--corsAddAllowedHeader`: Add a header name to `Access-Control-Allow-Headers` (defaults preserved). Repeat to add multiple. Useful when running with `--apiKey` so browser preflights for `X-API-Key` succeed.

### Troubleshooting Python stdio servers

If a Python stdio MCP server times out with an error such as `Expected server to respond to ping`, make sure Python is running in unbuffered mode. Buffered stdout can delay MCP JSON-RPC messages long enough for the proxy to treat the server as unresponsive.

Use `python -u` when launching the server:

```bash
npx mcp-proxy -- python -u -m your_package.mcp_server
```

Alternatively, set `PYTHONUNBUFFERED=1`:

```bash
PYTHONUNBUFFERED=1 npx mcp-proxy -- python -m your_package.mcp_server
```

MCP stdio servers should also reserve stdout for protocol messages. Send logs, warnings, and other diagnostic output to stderr, and use `--debug` when you need proxy-side logs.

### Public Tunnel

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.

```bash
# Expose your MCP server via a public tunnel
npx mcp-proxy --port 8080 --tunnel -- tsx server.js

# Request a specific subdomain
npx mcp-proxy --port 8080 --tunnel --tunnelSubdomain myapp -- 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](https://github.com/punkpeye/pipenet) and sponsored by [glama.ai](https://glama.ai). For more information, see the [pipenet announcement](https://glama.ai/blog/2026-01-19-pipenet).

### 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,
  },
});
```

#### CLI: adding allowed headers

The CLI exposes a single `--corsAddAllowedHeader` flag that appends to the
default `Access-Control-Allow-Headers` list (defaults preserved). The most
common use is unblocking the browser preflight for a custom auth header when
the proxy is started with `--apiKey`:

```bash
npx mcp-proxy --port 8080 --apiKey secret \
  --corsAddAllowedHeader X-API-Key \
  -- npx -y @modelcontextprotocol/server-filesystem /srv
```

Repeat the flag to add more (`--corsAddAllowedHeader X-API-Key --corsAddAllowedHeader X-Other`).
For broader CORS overrides (origin allowlist, wildcard headers, disabling CORS),
use the programmatic `cors` option below.

#### 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();
  },
  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 the streamable HTTP transport's resumability support (optional). Pass `false` to disable resumability entirely; omit to get a fresh, bounded `InMemoryEventStore` per session (see `eventStoreMaxEvents`); pass an `EventStore` instance to bring your own (e.g. persistent/cross-process), shared across all sessions. See [Resumability and memory use](#resumability-and-memory-use).
- `eventStoreMaxEvents`: Caps how many events the auto-created per-session `InMemoryEventStore` retains before evicting the oldest (default: 1000). Only applies when `eventStore` is not explicitly provided.
- `port`: Port number to listen on
- `host`: Host to bind to (default: "::")
- `keepAliveTimeout`: HTTP keep-alive timeout in milliseconds for stateful stream sessions (default: 300000)
- `maxBodySize`: Caps how many bytes of a request body the streamable HTTP endpoint buffers; larger requests are answered with `413 Payload Too Large` (default: 10485760, which is 10 MiB). Pass `false` to disable the cap. See [Request body size](#request-body-size).
- `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)

##### Resumability and memory use

The streamable HTTP transport can retain server→client messages so a client
that reconnects with a `Last-Event-ID` can resume where it left off. By
default, `mcp-proxy` gives each session its own `InMemoryEventStore` capped at
1000 buffered events (oldest evicted first via `--eventStoreMaxEvents` /
`eventStoreMaxEvents`), so a long-lived session's memory use stays bounded
instead of growing for as long as the process runs.

If you don't need resume-after-reconnect - for example, a short-lived
request/response deployment - disable the store entirely with
`--no-eventStore` (CLI) or `eventStore: false` (library) to drop the
resumability bookkeeping altogether.

If you need resumability with a larger replay window or one backed by shared
storage (e.g. Redis) across multiple proxy processes, pass your own
`EventStore` implementation as `eventStore`; in that case you're responsible
for bounding its size.

##### Request body size

The streamable HTTP endpoint buffers each request body in memory before it
parses the JSON-RPC message, so a single slow-chunking client could otherwise
grow the process's memory for as long as it kept sending. `mcp-proxy` caps
that buffer at 10 MiB by default (`--maxBodySize` / `maxBodySize`).

A request over the cap is answered with `413 Payload Too Large` and a JSON-RPC
error body naming the limit, then the connection is closed; the server also
logs `[mcp-proxy] request body too large`. When the client declares an
oversized `Content-Length`, it is rejected before any of the body is read; a
chunked body that declares no size up front is cut off as soon as the bytes
received exceed the cap.

The default is deliberately generous, because MCP payloads are often large -
base64-encoded images, documents and long pasted text routinely push a single
tool call past a megabyte. Raise it if your clients legitimately send more, or
set it to `0` (CLI) / `false` (library) to disable the cap entirely, which
restores unbounded buffering and is only safe behind a gateway that already
limits body size.

The cap applies to the streamable HTTP endpoint only. The SSE endpoint's
`POST /messages` bodies are read by the MCP SDK, not by `mcp-proxy`, so this
option does not affect them.

#### `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
```