mcp-reverse
v1.4.0
Published
Reverse transports for MCP (Model Context Protocol) — SSE engine. Allows internal MCP servers behind NAT/firewall to connect out to public MCP clients.
Maintainers
Readme
mcp-reverse
Reverse transports for MCP — SSE engine.
Let internal MCP servers behind NAT/firewall connect OUT to your public client.
The Problem
Standard MCP transports are client-initiated: the Client must reach the Server's address.
Client (public) ───connect───> Server (public) ✅ works
Client (public) ───connect───X Server (NAT) ❌ unreachablemcp-reverse flips the direction at the transport layer. The internal MCP Server initiates the connection; the public MCP Client accepts it. The MCP protocol then runs normally over the established channel.
Public Client (chat-ai) <───incoming──── Internal Server (behind NAT) ✅ worksFeatures
| Feature | Support | |---------|:---:| | NAT traversal | ✅ | | Authentication (token + custom handler) | ✅ | | Keepalive / heartbeat | ✅ SSE comments | | Auto-reconnect (exponential backoff + jitter) | ✅ | | TLS / HTTPS | ✅ | | Tools / Resources / Prompts | ✅ | | Notifications (both directions) | ✅ | | Next.js / Vercel / serverless | ✅ |
Install
npm install mcp-reverseRequires Node.js 20+ and @modelcontextprotocol/sdk 1.10.0+ as a peer dependency.
Quick Start — SSE
Public Side (chat-ai / Next.js App Router)
import { SSEAcceptor } from 'mcp-reverse';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
const acceptor = new SSEAcceptor({
authTokens: { 'office-server': 'secret123' },
});
acceptor.onConnection(async ({ transport, metadata }) => {
console.log(`Server connected: ${metadata.serverName}`);
const client = new Client(
{ name: 'chat-ai', version: '1.0.0' },
{ capabilities: {} }
);
await client.connect(transport);
// Use client normally
const tools = await client.listTools();
const result = await client.callTool({ name: 'exec', arguments: { cmd: 'ls' } });
});
acceptor.onDisconnection((serverName, sessionId) => {
console.log(`Disconnected: ${serverName} (${sessionId})`);
});
// ─── Next.js App Router integration ───
export async function GET(req: NextRequest) {
return acceptor.handleSSE(req);
}
export async function POST(req: NextRequest) {
return acceptor.handleMessage(req);
}Or run standalone (creates its own HTTP server):
const acceptor = new SSEAcceptor({ port: 3400, authTokens: { ... } });
await acceptor.start(); // listens on http://0.0.0.0:3400/mcp-reverseInternal Side (behind NAT)
import { SSEReverseClientTransport } from 'mcp-reverse';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
const transport = new SSEReverseClientTransport({
url: 'https://public-chatai.example.com:3000/mcp-reverse',
serverName: 'office-server',
authToken: 'secret123',
connectTimeout: 15000,
});
// This low-level transport performs one connection only. For automatic
// reconnection, use ReverseMCPClient below.
const server = new McpServer({ name: 'office-server', version: '1.0.0' });
server.tool('greet', 'Greet someone', { name: z.string() },
async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] })
);
await server.connect(transport);High-Level Client (recommended)
import { ReverseMCPClient } from 'mcp-reverse/connector';
const client = await ReverseMCPClient.createSSE(server, {
url: 'https://public-host.example.com:3000/mcp-reverse',
serverName: 'office-server',
authToken: 'secret123',
connectTimeout: 15000,
initializationTimeout: 15000,
heartbeat: { readTimeout: 45000 },
reconnect: { enabled: true, maxDelay: 30000, stableConnectionMs: 30000 },
});
client.on('connected', () => console.log('MCP initialized and ready'));
client.on('disconnected', () => console.log('Disconnected'));
client.on('reconnecting', (attempt) => console.log(`Reconnecting (${attempt})`));
await client.start(); // schedules attempts; does not wait for readiness1.4 connection lifecycle
connectednow means the MCPnotifications/initializedhandshake completed, not merely HTTP 200/SSE open. Existingserver.server.oninitializedhooks and transport wrappers are preserved.initializationTimeoutbounds the wait after SSE opens (default 15000 ms, positive).heartbeatis forwarded to the low-level SSE reader; neither setting changes a tool execution deadline.- Failed handshakes and connections that immediately close continue exponential backoff. A connection must survive
stableConnectionMs(default 30000 ms) before disconnect resets the failure cycle. No stability timer or parallel retry loop is created. Set0only if immediate reset is intentionally required. - Web stream enqueue failures, Node response errors/closure, and heartbeat write failures retire the exact session. Asynchronous Node write failures reject
send(); awrite()return offalseis only backpressure. - Stop cancels initialization waits and pending retries. Reconnection never replays tool calls: a failed response does not prove a command had no side effects.
- Wire endpoints, authentication and MCP message formats are unchanged. New gateways can serve old connectors; old connectors keep their own retry defects until upgraded. SDK 1.30.0 is the development baseline; the existing peer range is retained for compatible 1.x consumers.
API Reference
SSEAcceptor (Public Side)
new SSEAcceptor(options: SSEAcceptorOptions | SSEAcceptorStandaloneOptions)| Option | Type | Default | Notes |
|--------|------|---------|-------|
| authTokens | Record<string, string> | — | serverName → token map |
| authHandler | async (meta) => boolean | — | Custom auth logic |
| heartbeat | SSEHeartbeatOptions | {enabled:true} | Keepalive |
| maxMessageSize | number | 4MB | POST body limit |
| sessionTimeout | number | 60000 | Inactivity timeout (ms) |
| pathPrefix | string | /mcp-reverse | URL prefix |
| port | number | — | Standalone only: listen port |
SSEReverseClientTransport (Internal Side)
new SSEReverseClientTransport(options: SSEReverseClientTransportOptions)| Option | Type | Default | Notes |
|--------|------|---------|-------|
| url | string | required | Base URL |
| serverName | string | required | Server identifier |
| authToken | string | — | Bearer token |
| reconnect | ReconnectOptions | — | Deprecated on the low-level transport; use ReverseMCPClient |
| heartbeat | SSEHeartbeatOptions | {enabled:true} | Keepalive |
| headers | Record<string, string> | — | Extra headers for GET and POST |
| insecureTls | boolean | — | Reserved for compatibility; not supported by the built-in fetch transport |
| connectTimeout | number | 15000 | SSE connection timeout in ms (0 disables) |
| queryParams | Record<string, string> | — | Extra query params |
Reconnect Options
{
enabled?: boolean; // default: true
initialDelay?: number; // default: 1000ms
maxDelay?: number; // default: 30000ms
multiplier?: number; // default: 2
jitter?: boolean; // default: true
maxRetries?: number; // default: 0 (infinite)
stableConnectionMs?: number; // default: 30000ms, 0 = immediate reset
}Project Structure
src/
├── protocol/ # Protocol-level abstractions
│ ├── types.ts # All type definitions
│ └── reconnect.ts # Exponential backoff reconnection
├── acceptor/
│ └── sse-acceptor.ts # SSEAcceptor (public side)
├── connector/
│ ├── mcp-connector.ts # ReverseMCPClient (high-level)
│ └── sse-connector.ts # SSEReverseClientTransport (internal side)
├── transport/
│ ├── sse-transport.ts # SSEConnectionTransport
│ └── sse-util.ts # SSE parsing/formatting utilities
├── proxy/
│ └── reverse-proxy.ts # ReverseProxy / gateway
└── index.ts # Main entry pointSub-path exports
| Export path | Description |
|-------------|-------------|
| mcp-reverse | Main entry — all types |
| mcp-reverse/connector | High-level ReverseMCPClient |
| mcp-reverse/acceptor | SSEAcceptor |
| mcp-reverse/sse | Backward compat — all SSE types |
| mcp-reverse/transport | SSEConnectionTransport, SSE utilities |
| mcp-reverse/proxy | ReverseProxy |
Testing
npm test # All 61 tests (unit + integration)
npm run build # TypeScript compilationLicense
MIT
