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)       ❌ unreachable

mcp-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)       ✅ works

Features

| 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-reverse

Requires @modelcontextprotocol/sdk as 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) => console.log(`Disconnected: ${serverName}`));

// ─── 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-reverse

Internal 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',
  reconnect: { enabled: true },
});

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',
  reconnect: { enabled: true, maxDelay: 30000 },
});

client.on('connected', () => console.log('Connected'));
client.on('disconnected', () => console.log('Disconnected'));
client.on('reconnecting', (attempt) => console.log(`Reconnecting (${attempt})`));

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 | {enabled:true} | Auto-reconnect | | heartbeat | SSEHeartbeatOptions | {enabled:true} | Keepalive | | headers | Record<string, string> | — | Extra headers | | insecureTls | boolean | false | Skip TLS verify | | 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)
}

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 point

Sub-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 43 tests (unit + integration)
npm run build              # TypeScript compilation

License

MIT