Back to search
mcp-proxy
SkillGitHub
A TypeScript streamable HTTP and SSE proxy for MCP servers that use stdio transport.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/punkpeye--mcp-proxy)HTML
<a href="/listings/punkpeye--mcp-proxy"><img src="/api/listings/punkpeye--mcp-proxy/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
npm install mcp-proxy
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 622 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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 the inverse — giving a stdio-only client access to a remote MCP server, including the interactive OAuth flow — see [mcp-remote](https://github.com/punkpeye/mcp-remote).
- > [!NOTE]
- > MCP Proxy is what [FastMCP](https://github.com/punkpeye/fastmcp) uses to enable streamable HTTP and SSE.
- ## Protocol revisions
- MCP Proxy serves protocol revision `2026-07-28` and the 2025-era revisions
- (`2024-10-07` through `2025-11-25`) from the same endpoint. Every POST to the
- streamable HTTP endpoint is classified by its own content — the 2026-07-28
- revision puts a `_meta` envelope on every request, and requests without one are
- served by the 2025-era session machinery — so old and new clients share one URL
- and neither has to know the other exists.
- | | 2025-era clients | 2026-07-28 clients |
- | --------------------- | ---------------- | ----------------------------- |
- | `/mcp` (streamable) | yes, sessionful | yes, per-request |
- | `/sse` (HTTP+SSE) | yes | n/a — no SSE transport exists |
- | stdio (`startStdioServer`) | yes | not yet — see below |
- | Change notifications | unsolicited | `subscriptions/listen` stream |
- Progress notifications and cancellation cross the proxy in both eras: a
- forwarded call carries the caller's abort signal, and relayed progress is
- re-tagged with the token the caller sent.
- Use `--no-modern` to serve only 2025-era clients; a 2026-07-28 client is then
- answered by the 2025-era machinery, which does not recognise its request. The
- modern leg lives on the streamable HTTP endpoint, so it is also absent when that
- endpoint is disabled (`--server sse`, or `streamEndpoint: null`).
- The upstream connection — the server MCP Proxy spawns — negotiates its own
- revision independently, so any combination works. It uses the 2025 `initialize`
- handshake by default; pass `--upstreamProtocol auto` to probe with
- `server/discover` first (needed to front a 2026-07-28 server) or
- `--upstreamProtocol modern` to require it.
- ```bash
- # front a 2026-07-28 stdio server, serving both eras downstream
- npx mcp-proxy --upstreamProtocol auto -- my-modern-mcp-server
- ```
- ### What does not cross the proxy
- These are consequences of one design decision — the proxy multiplexes every
- downstream connection onto a **single** upstream connection — and are called out
- rather than half-solved.
- - **Anything that asks the client for input** (elicitation, sampling, roots).
- A 2025-era server pushes its request out of band, carrying nothing that says
- which caller it belongs to, so relaying it means guessing whose screen to put
- the prompt on. A 2026-07-28 upstream is not ambiguous that way — the request
- comes back as the `input_required` result of the call the proxy forwarded —
- so that direction is a question of scope, not correlation. Not implemented
- yet.
- - **Log messages, on both sides of a 2026-07-28 connection.** That revision
- carries logs per request: the client asks in a request's `_meta`, the server
- answers on that request's stream. The proxy can do neither half — downstream
- it has no per-request log callback and its notification handlers are passed
- nothing to attribute a log to; upstream it cannot ask for logs at all, so a
- 2026-07-28 server's per-request logging never fires. 2025-era clients still
- get the deprecated unsolicited path: everything from a 2025-era upstream, and
- from a 2026-07-28 upstream only what it sends outside the per-request
- channel, which a conformant one will not use.
- - **`logging/setLevel` upstream.** Answered and honored per downstream
- connection — messages below the level a connection asked for are not
- forwarded to it — but never passed on: the shared upstream carries one level,
- so forwarding would let one client silence another's logs, and the method
- does not exist on a 2026-07-28 upstream at all.
- - **Client identity.** The upstream sees `mcp-proxy` as its client, not the
- downstream caller — so does any telemetry keyed on it.
- - **2026-07-28 over stdio.** `startStdioServer` serves 2025-era clients only;
- the HTTP side serves both.
- - **MCP Events push, and per-caller principals.** See
- [MCP Events](#mcp-events-experimental).
- > [!NOTE]
- > The `/sse` endpoint uses the frozen `@modelcontextprotocol/server-legacy`
- > copy of the HTTP+SSE transport, which the v2 SDK removed. That transport is
- > deprecated as of `2026-07-28` with a twelve-month window; migrate clients to
- > the streamable HTTP endpoint.
- ## MCP Events (experimental)
- MCP Proxy forwards the webhook and poll half of the Events extension
- ([SEP-3415](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3415),
- a draft, last checked against `b08e4f9`). This is experimental forwarding, not
- SEP-3415 compliance: anything the table does not list is not forwarded.
- | Method | Through the proxy |
- | ----------------------------------- | ----------------------------------------------------- |
- | `events/list` | forwarded, pagination included |
- | `events/poll` | forwarded; cursors come back unchanged |
- | `events/subscribe` | forwarded, to subscribe and to refresh |
- | `events/unsubscribe` | forwarded |
- | `events/stream` (push) | not forwarded: `-32026 Unsupported` |
- | `notifications/events/list_changed` | not delivered: `listChanged` is advertised as `false` |
- - **Only when the upstream offers it.** These methods are answered only if the
- upstream advertises `capabilities.extensions["io.modelcontextprotocol/events"]`
- (an empty `{}` counts). Otherwise every `events/*` request is `-32601 Method
- not found`, as before.
- - **Passed through, not parsed.** Params and results cross as they are: `null`
- stays distinct from absent (`cursor`, `ttlMs`), and unknown fields and
- `_meta` survive. Errors keep their code, message and `data` for every code
- SEP-3415 uses. `resultType` belongs to the protocol revision, so each
- connection drops and re-stamps it, and a 2026-07-28 connection adds a
- `serverInfo` entry to a result's `_meta` when it has none. Cancellation,
- progress and `--requestTimeout` apply as to any forwarded call.
- - **Webhooks go straight to the caller.** The upstream POSTs to `delivery.url`
- itself. The proxy never receives a webhook, creates or checks a secret,
- stores a subscription or refreshes one, and a downstream connection closing
- unsubscribes nothing. A subscription lasts as long as the upstream keeps it:
- until its TTL lapses, someone calls `events/unsubscribe`, or the upstream
- ends it.
- - **No push.** The proxy answers `events/stream` itself with `-32026
- Unsupported` and `data: { "feature": "deliveryMode", "value": "push" }`:
- SEP-3415's signal that a delivery mode is not available, so a client can
- fall back to poll or webhook. (`-32601` would read as "no Events support at
- all".) The catalog is not rewritten, so event types still list `"push"`, and
- those that offer only push cannot be consumed through the proxy. Like every
- SEP-3415 code, `-32026` is provisional until the SEP is accepted.
- - **Upstream revision.** SEP-3415 is defined for `2026-07-28`, so a conformant
- server advertises the extension on `server/discover` only. Run the proxy
- with `--upstreamProtocol auto` (or `modern`). Under the default `legacy`
- handshake the proxy sees the extension only if the server also puts it in
- its `initialize` result, as some do. Downstream, both eras get the methods.
- - **`Mcp-Name`.** SEP-3415 requires it, set to `params.name`, on `events/poll`,
- `events/subscribe` and `events/unsubscribe` over streamable HTTP. The SDK
- client sets it; the proxy does not check it.
- - **Only `extensions` is relayed.** The pre-SEP top-level `capabilities.events`
- that some clients still read is dropped when the SDK parses the upstream's
- capabilities.
- - **Your own `Server`.** The CLI and `startStdioServer` advertise
- `listChanged: false`. If you build the downstream `Server` yourself (for
- `proxyServer`, or through `initStdioServer`), do the same.
- > [!WARNING]
- > **Every caller is the same principal upstream.** SEP-3415 keys a webhook
- > subscription on `(principal, delivery.url, name, arguments)`, where the
- > principal is whoever the upstream authenticated. The proxy has one upstream
- > connection (for the CLI, one process), so every downstream caller is that
- > process's own identity: its credentials, its environment.
- >
- > - Two callers that send the same `delivery.url`, `name` and `arguments`
- > share one subscription, and either can refresh it, rotate its secret or
- > delete it.
- > - The upstream caches a callback URL's verification per principal, so a URL
- > one caller has verified is open to every other caller without a new
- > challenge.
- > - stdio carries no MCP authentication, and SEP-3415 has a server refuse
- > `events/subscribe` and `events/unsubscribe` without a principal
- > (`Forbidden`). Through the CLI they work only if the server treats its own
- > process identity as the principal.
- > - Webhooks are POSTed from wherever the upstream runs — for the CLI, the
- > proxy's host. Anyone who can reach the proxy chooses those URLs, so make
- > sure the server does the URL checks SEP-3415 requires before exposing the
- > proxy.
- >
- > `--apiKey` and `authenticate` decide who reaches the proxy, not who the
- > upstream thinks is calling, and the proxy passes on no per-caller identity.
- > Isolating principals takes a separate upstream connection (process) per
- > principal, or a trusted delegation mechanism designed for it.
- ## Installation
- ```bash
- npm install mcp-proxy
- ```
- ## Quickstart
- ### Command-line
- ```bash
- # no mcp-proxy options
- npx mcp-proxy npx -y @anthropic/mcp-server-filesystem /path
- # with mcp-proxy options
- npx mcp-proxy --port 8080 --shell -- tsx server.js
- ```
- The second spawns `tsx server.js` over `stdio` and serves it on port 8080 at `/mcp` (streamable HTTP) and `/sse` (SSE).
- > [!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`: Create a fresh server instance per request instead of maintaining sessions. Applies to the 2025-era leg; 2026-07-28 is per-request by construction.
- - `--modern`: Serve protocol revision 2026-07-28 on the streamable HTTP endpoint alongside the 2025-era revisions (default: `true`). Use `--no-modern` to serve only 2025-era clients. See [Protocol revisions](#protocol-revisions).
- - `--upstreamProtocol`: Which protocol revision to speak to the spawned server — `legacy` (default), `auto`, or `modern`. See [Protocol revisions](#protocol-revisions).
- - `--port`: Specify the port to listen on (default: 8080)
- - `--connectionTimeout`: Timeout in milliseconds for the initial connection to the MCP server (default: 60000)
- - `--requestTimeout`: Timeout in milliseconds for requests to the MCP server (default: 300000)
- - `--keepAliveTimeout`: HTTP keep-alive timeout in milliseconds for stateful stream sessions (default: 300000)
- - `--sessionIdleTimeout`: How long in milliseconds a stateful stream session survives with no stream attached and no requests before it is closed (default: 1800000, 30 minutes). Set to `0` to keep every session until its client sends `DELETE`. See [Abandoned sessions](#abandoned-sessions).
- - `--eventStore`: Enable the resumability event store, letting clients replay missed messages after a reconnect (default: `true`). `--no-eventStore` disables it. 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 and the SSE endpoint's `POST /messages`; larger requests are answered with `413 Payload Too Large` (default: 10485760, 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
- - `--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 server times out with `Expected server to respond to ping`, run Python unbuffered — buffered stdout can delay JSON-RPC messages long enough for the proxy to treat the server as unresponsive:
- ```bash
- npx mcp-proxy -- python -u -m your_package.mcp_server
- # or: PYTHONUNBUFFERED=1 npx mcp-proxy -- python -m your_package.mcp_server
- ```
- stdio servers should also reserve stdout for protocol messages — send diagnostics to stderr, and use `--debug` for proxy-side logs.
- ### Stateless Mode
- By default each client connection holds a server instance for the life of its session. `--stateless` creates a fresh instance per request instead, so requests are fully independent — which suits serverless platforms, load-balanced deployments, and anywhere you'd rather not hold connection state.
- ```bash
- npx mcp-proxy --port 8080 --stateless -- tsx server.js
- # 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.
- ### API Key Authentication
- Optional and off by default. When enabled, clients must send a valid key in the `X-API-Key` header.
- ```bash
- npx mcp-proxy --port 8080 --apiKey "your-secret-key" -- tsx server.js
- # or via the environment
- export MCP_PROXY_API_KEY="your-secret-key"
- npx mcp-proxy --port 8080 -- tsx server.js
- ```
- Clients pass it as a transport header:
- ```typescript
- const transport = new StreamableHTTPClientTransport(
- new URL("http://localhost:8080/mcp"),
- { headers: { "X-API-Key": "your-secret-key" } },
- );
- ```
- `/ping` and `OPTIONS` preflights are exempt. Keys travel in a header, so serve over HTTPS in production.
- ### CORS Configuration
- #### Default Behavior
- CORS is enabled by default with:
- - **Origin**: `*` (allow all origins)
- - **Methods**: `GET, POST, DELETE, OPTIONS`
- - **Headers**: `Content-Type, Authorization, Accept, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-Id, Mcp-Method, Mcp-Name`
- - **Credentials**: `true`
- - **Exposed Headers**: `Mcp-Session-Id`
- `Access-Control-Allow-Credentials` is omitted whenever the allowed origin comes
- out as `*`, because the Fetch Standard makes a browser
- [reject the whole CORS response](https://fetch.spec.whatwg.org/#http-access-control-allow-credentials)
- when it sees both. Credentialed browser requests (`credentials: "include"`,
- `withCredentials`) therefore need an explicit `origin` — a list or a function,
- not a wildcard.
- `Mcp-Method` and `Mcp-Name` are required on 2026-07-28 streamable HTTP POSTs, so
- browser clients on that revision need them allowed. That revision's
- `Mcp-Param-*` headers are a prefix, which `Access-Control-Allow-Headers` cannot
- express — if your tools declare `x-mcp-header` parameters, add those header
- names explicitly with `--corsAddAllowedHeader` or `allowedHeaders`.
- #### Configuration
- `cors: true` (or omitted) uses the defaults, `cors: false` disables it, and a
- `CorsOptions` object overrides individual fields:
- ```typescript
- import { startHTTPServer, CorsOptions } from "mcp-proxy";
- const cors: CorsOptions = {
- // A list, or a function for dynamic validation
- origin: ["https://app.example.com"],
- methods: ["GET", "POST", "DELETE", "OPTIONS"],
- // "*" allows any header — the usual fix for browser preflight failures.
- // Listing headers instead REPLACES the defaults, so restate the protocol's
- // own: dropping Mcp-Method/Mcp-Name breaks browser clients on 2026-07-28.
- allowedHeaders: "*",
- exposedHeaders: ["Mcp-Session-Id"],
- credentials: true,
- maxAge: 86400,
- };
- await startHTTPServer({ cors, createServer, port: 3000 });
- ```
- Upgrading from 5.5.6 or earlier, where headers were wildcarded automatically?
- Set `allowedHeaders: "*"` to restore that behavior.
- #### CLI: adding allowed headers
- `--corsAddAllowedHeader` appends to the default `Access-Control-Allow-Headers`
- list, keeping the defaults. Repeat it to add more. The common use is unblocking
- the browser preflight for a custom auth header under `--apiKey`:
- ```bash
- npx mcp-proxy --port 8080 --apiKey secret \
- --corsAddAllowedHeader X-API-Key \
- -- npx -y @modelcontextprotocol/server-filesystem /srv
- ```
- For origin allowlists, wildcard headers, or disabling CORS, use the
- programmatic `cors` option above.
- ### Node.js SDK
- #### `proxyServer`
- Sets up a proxy between a server and a client.
- ```ts
- const transport = new StdioClientTransport();
- const client = new Client();
- await client.connect(transport);
- const serverCapabilities = client.getServerCapabilities();
- const server = new Server(client.getServerVersion(), {
- capabilities: serverCapabilities,
- });
- await proxyServer({
- client,
- server,
- serverCapabilities,
- });
- ```
- In this example, the server will proxy all requests to the client and vice
- versa. Handlers are registered from `serverCapabilities`, so a method the
- upstream never advertised is answered "method not found" locally instead of
- making a round trip to find out.
- Options:
- - `client`: The connected upstream client
- - `server`: The downstream server to wire up
- - `serverCapabilities`: What the upstream advertised; decides which handlers are registered
- - `requestTimeout`: Timeout in milliseconds applied to every forwarded request (optional)
- > [!NOTE]
- > One `proxyServer` call serves one downstream connection, but they share a
- > single upstream client, so an upstream notification is received once and
- > offered to **every** connected client. Two are narrowed before they are
- > forwarded: `notifications/resources/updated` reaches only the connections
- > that subscribed to that URI, and `notifications/message` only those whose
- > `logging/setLevel` admits it — a connection that never set one still gets
- > everything. The `list_changed` notifications are not
- > narrowed — they describe the one upstream, which every connection is looking
- > at. If you derive per-request identity in `createServer` to serve several
- > tenants from one proxy, that is the line to check against your model.
- #### `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/server";
- import { startHTTPServer } from "mcp-proxy";
- const { close, notify } = 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)
- - `sessionIdleTimeout`: How long in milliseconds a stateful stream session survives with no stream attached and no requests before it is closed (default: 1800000, 30 minutes). Pass `0` to keep every session until its client sends `DELETE`. See [Abandoned sessions](#abandoned-sessions).
- - `maxBodySize`: Caps how many bytes of a request body the streamable HTTP endpoint and the SSE endpoint's `POST /messages` buffer; larger requests are answered with `413 Payload Too Large` (default: 10485760, 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). Applies to the 2025-era leg; protocol revision 2026-07-28 is per-request by construction.
- - `modern`: Serve protocol revision 2026-07-28 alongside the 2025-era revisions on `streamEndpoint` (default: true). See [Protocol revisions](#protocol-revisions).
- - `apiKey`: API key for authenticating requests (optional)
- - `cors`: CORS configuration (default: enabled with permissive settings, see CORS Configuration section)
- - `onConnect`: Callback when a server instance is created (optional). Fires once per session on the 2025-era legs and **once per request** on the 2026-07-28 leg, which builds a fresh instance per request.
- - `onClose`: Callback when a server instance is torn down (optional). Same per-era unit as `onConnect`; keep it cheap and idempotent. A rejection is logged and does not stop the rest of teardown.
- - `onUnhandledRequest`: Callback for unhandled HTTP requests (optional)
- - `beforeDispatch`: Lets the server answer a request with its own HTTP response before `mcp-proxy` hands it to the transport (optional). See [Answering before dispatch](#answering-before-dispatch).
- Returns `{ close, notify }`. See [Change notifications](#change-notifications)
- for what `notify` is for.
- ##### Change notifications
- A 2025-era client receives `list_changed` and `resources/updated` unsolicited on
- its own connection, and `proxyServer` forwards them there for you.
- Protocol revision 2026-07-28 has no such connection: it delivers those events
- only on a `subscriptions/listen` stream the client opened, and the per-request
- server instances that serve it own no stream. Those events are published to the
- handler's bus instead, which is what `startHTTPServer` returns as `notify`. Wire
- your upstream change events to it:
- ```ts
- import { getUpstreamBridge, startHTTPServer } from "mcp-proxy";
- const { notify } = await startHTTPServer({ createServer, port: 8080 });
- getUpstreamBridge({ client }).subscribe({
- promptsListChanged: () => notify.promptsChanged(),
- resourcesListChanged: () => notify.resourcesChanged(),
- resourceUpdated: ({ uri }) => notify.resourceUpdated(uri),
- toolsListChanged: () => notify.toolsChanged(),
- });
- ```
- `notify` is a no-op when `modern: false`, so this wiring is safe to leave in
- place unconditionally. The `mcp-proxy` CLI does exactly this.
- `getUpstreamBridge(client)` registers the upstream notification handlers once
- per client and fans them out, so several downstream connections can share one
- upstream server. `subscribe(sink)` returns a lease with
- `addResourceSubscription` / `removeResourceSubscription` / `owns` / `release`.
- Resource subscriptions are owned per lease, so one connection unsubscribing
- never cancels a URI another still wants, and `release()` drops whatever a
- disconnecting connection held.
- A 2026-07-28 client asks for resource updates through the `resourceSubscriptions`
- field of its `subscriptions/listen` filter rather than `resources/subscribe`.
- Pass `onListenSubscriptions` to act on those URIs; `acquireListenSubscriptions`
- is the implementation the CLI uses, and acquires them all-or-nothing so a filter
- the upstream only partly accepts does not strand the rest:
- ```ts
- import { acquireListenSubscriptions } from "mcp-proxy";
- await startHTTPServer({
- createServer,
- onListenSubscriptions: (uris) => acquireListenSubscriptions({ client, uris }),
- port: 8080,
- });
- ```
- ##### Resumability and memory use
- The streamable HTTP transport can retain server→client messages so a client
- reconnecting with a `Last-Event-ID` resumes where it left off. Each session gets
- its own `InMemoryEventStore` capped at 1000 events (oldest evicted first, via
- `--eventStoreMaxEvents` / `eventStoreMaxEvents`), so a long-lived session's
- memory stays bounded rather than growing for the life of the process.
- Don't need resume-after-reconnect? `--no-eventStore` (CLI) or
- `eventStore: false` (library) drops the bookkeeping entirely. For a larger
- replay window or shared storage across processes (e.g. Redis), pass your own
- `EventStore` — you're then responsible for bounding its size.
- ##### Abandoned sessions
- A 2025-era session outlives the connection that created it — that is what makes
- replay-on-reconnect work — and is meant to be ended by a `DELETE`. In practice
- most clients never send one: they close a laptop, get killed, or lose a network,
- and are simply never heard from again. Each session left behind holds a server
- instance, a transport, and an event store that goes on buffering notifications
- it can no longer deliver.
- `mcp-proxy` closes a session once nothing is attached to it and nothing has
- happened for 30 minutes (`--sessionIdleTimeout` / `sessionIdleTimeout`). A
- session with a stream attached is never closed however quiet it is, so a client
- parked on the notification stream is unaffected; the countdown starts when the
- stream drops, not at the last request. Closing runs the same path a `DELETE`
- does, so `onClose` fires exactly as it always has.
- What this costs is resumability past the timeout: a client returning later with
- a `Last-Event-ID` gets a new session instead of its replay. With the default
- in-memory store capped at 1000 events, there is usually little left to replay by
- then anyway. Set the timeout to `0` to keep every session until its client sends
- `DELETE`.
- Sessions on the `/sse` endpoint end with their connection and are unaffected, as
- are `--stateless` mode and protocol revision 2026-07-28, neither of which
- retains anything between requests.
- ##### Request body size
- The streamable HTTP endpoint and the SSE endpoint's `POST /messages` buffer each
- request body before parsing it, so a 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 (`--maxBodySize` / `maxBodySize`). An oversized
- `Content-Length` is rejected before any body is read; a chunked body is cut off
- as soon as it exceeds the cap. Either way the answer is `413 Payload Too Large`
- with a JSON-RPC error body naming the limit, then the connection closes.
- The default is deliberately generous — base64 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 `0` (CLI) / `false` (library) to disable it,
- which restores unbounded buffering and is only safe behind a gateway that
- already limits body size.
- ##### Answering before dispatch
- Once a message reaches the transport, the SDK owns the HTTP response: a tool
- runs after that, and whatever it throws comes back as a JSON-RPC error on a
- `200`. So a tool cannot send MCP's `403 insufficient_scope` challenge, which
- tells the client to re-authorize with more scopes.
- `beforeDispatch` runs first. It is offered every message POSTed to the
- streamable HTTP endpoint or the SSE endpoint's `POST /messages` once
- `authenticate` has passed, along with that request's `authResult` and the
- `server` that would handle it. A batch is offered one message at a time. Return
- a `Response` to answer the request with it - none of its messages is then
- dispatched - or nothing to let the message through. For the scope
- challenge, throw an `InsufficientScopeError` and `mcp-proxy` builds it:
- ```ts
- await startHTTPServer({
- authenticate,
- beforeDispatch: ({ authResult, message }) => {
- const missing = missingScopes(authResult, message); // your own check
- if (missing.length > 0) {
- throw {
- data: { error: "insufficient_scope", requiredScopes: missing },
- name: "InsufficientScopeError",
- };
- }
- },
- createServer,
- oauth: { protectedResource: { resource: "https://example.com/mcp" } },
- port: 8080,
- });
- ```
- The client gets a `403` with `WWW-Authenticate: Bearer error="insufficient_scope",
- scope="…", resource_metadata="…"`. `resource_metadata` comes from
- `oauth.protectedResource.resource` and is left out without it; `oauth.realm`
- adds `realm`. A thrown `Response` is sent as is; anything else thrown is
- answered with a `500`.
- #### `startStdioServer`
- Starts a proxy that listens on a `stdio`, and sends messages to the attached `sse` or `streamable` server.
- ```ts
- import { ServerType, startStdioServer } from "mcp-proxy";
- await startStdioServer({
- serverType: ServerType.SSE,
- url: "http://127.0.0.1:8080/sse",
- });
- ```
- Options:
- - `serverType`: `ServerType.SSE` or `ServerType.HTTPStream`
- - `url`: URL of the upstream MCP server
- - `transportOptions`: Options passed to the client transport (optional)
- - `upstreamProtocol`: Which protocol revision to speak upstream — `"legacy"` (default, the 2025 `initialize` handshake), `"auto"` (probe with `server/discover`, fall back to the handshake), or `"modern"` (require 2026-07-28). See [Protocol revisions](#protocol-revisions). Note that the stdio connection this serves is 2025-era regardless.
- - `initStdioServer` / `initStreamClient`: Bring your own `Server` / `Client` instance (optional)
- Closing the returned server also closes the upstream client created by
- `startStdioServer`. A client supplied by `initStreamClient` remains caller-owned
- during ordinary shutdown.
- #### `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
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.