MCP Proxy

Because MCP Proxy multiplexes many downstream connections onto a single upstream connection, certain features are limited or unavailable:

• Client Input/Sampling: Anything requiring client input (elicitation, sampling, roots) is not currently supported because the proxy cannot reliably attribute a request for input to a specific downstream caller in the 2025-era.
• Per-request Logging (2026-07-28): The proxy cannot attribute logs to specific requests or callers. 2025-era clients receive unsolicited logs from the upstream, but 2026-07-28 per-request logging is not supported.
• Upstream logging/setLevel: While the proxy honors log levels per downstream connection, it cannot pass these commands to the upstream. The shared upstream connection maintains a single log level.
• Client Identity: The upstream server sees mcp-proxy as the client, not the individual downstream callers. This affects any telemetry or identity-based logic on the server.
• 2026-07-28 over stdio: The startStdioServer command only serves 2025-era clients; modern protocol support is only available via the HTTP endpoints.

MCP Proxy is designed to be backward compatible, serving both 2025-era clients and 2026-07-28 clients simultaneously.

Revision Detection

• 2026-07-28 clients: Identified by the presence of a _meta envelope in every request. These use per-request streamable HTTP.
• 2025-era clients: Identified by the absence of a _meta envelope. These use sessionful streamable HTTP or the /sse (HTTP+SSE) endpoint.

Upstream Negotiation

While the proxy serves multiple eras downstream, the connection it spawns to your actual MCP server (the upstream) negotiates its own revision. By default, it uses the 2025 initialize handshake. You can control this behavior using the --upstreamProtocol flag.

Protocol Support Matrix

# Front a 2026-07-28 stdio server, serving both eras downstream
npx mcp-proxy --upstreamProtocol auto -- my-modern-mcp-server

The proxy enables CORS by default with a permissive configuration (Origin: *).

Important for Browser Clients: Because Access-Control-Allow-Credentials is set to true, you cannot use a wildcard * for the origin in a browser. You must specify an explicit origin.

Adding Custom Headers: If you use --apiKey, you must add X-API-Key to the allowed headers so browser preflights succeed. Use the --corsAddAllowedHeader flag to append to the defaults.

Programmatic Configuration (SDK): If using the Node.js SDK, pass a CorsOptions object to startHTTPServer to override defaults like origin, methods, allowedHeaders, exposedHeaders, and credentials.

# Adding a custom header via CLI
npx mcp-proxy --port 8080 --apiKey secret \
  --corsAddAllowedHeader X-API-Key \
  -- npx -y @modelcontextprotocol/server-filesystem /srv

import { startHTTPServer, CorsOptions } from "mcp-proxy";

const cors: CorsOptions = {
  origin: ["https://app.example.com"],
  methods: ["GET", "POST", "OPTIONS"],
  allowedHeaders: "*", // Note: This replaces defaults; ensure Mcp-Method/Mcp-Name are included if needed
  exposedHeaders: ["Mcp-Session-Id"],
  credentials: true,
  maxAge: 86400,
};

await startHTTPServer({ cors, createServer, port: 3000 });

The mcp-proxy uses an UpstreamBridge to multiplex a single upstream MCP Client connection across multiple downstream connections.

To prevent one downstream connection from accidentally canceling a resource subscription needed by another, the proxy uses an UpstreamLease model. Each downstream connection receives a lease when it subscribes to the bridge. This lease manages its own set of resource subscriptions. When a lease is released, it only removes the specific URIs it requested, provided no other active leases still require them (using internal reference counting).

Key components:

• UpstreamBridge: A shared object per upstream Client that manages the lifecycle of the connection and fans out notifications to all connected sinks.
• UpstreamLease: A per-connection object used to manage resource subscriptions and determine if a specific URI update should be delivered to that connection.
• UpstreamNotificationSink: A consumer interface that receives fanned-out notifications (like toolsListChanged or resourceUpdated).

// Conceptual flow:
const bridge = getUpstreamBridge({ client });
const lease = bridge.subscribe(mySink);

// Subscribe to a specific resource via the lease
await lease.addResourceSubscription("mcp://resource/1");

// When done, release the lease to clean up subscriptions
lease.release();