MCP Connect

███╗ ███╗ ██████╗██████╗ ██████╗ ██████╗ ███╗ ██╗███╗ ██╗███████╗ ██████╗████████╗

████╗ ████║██╔════╝██╔══██╗ ██╔════╝██╔═══██╗████╗ ██║████╗ ██║██╔════╝██╔════╝╚══██╔══╝

██╔████╔██║██║ ██████╔╝ ██║ ██║ ██║██╔██╗ ██║██╔██╗ ██║█████╗ ██║ ██║

██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║ ██║██║╚██╗██║██║╚██╗██║██╔══╝ ██║ ██║

██║ ╚═╝ ██║╚██████╗██║ ╚██████╗╚██████╔╝██║ ╚████║██║ ╚████║███████╗╚██████╗ ██║

╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═══╝╚══════╝ ╚═════╝ ╚═╝

What Is MCP Connect?

MCP Connect is an HTTP gateway that lets you call local MCP servers (that speak stdio) through Streamable HTTP or a classic request/response bridge.

What's New

• Added Streamable HTTP mode on top of the classic request/response bridge
• New quick-deploy scripts and configs under `deploy/e2b` for launching in an E2B sandbox

How It Works

+-----------------+   HTTP (JSON)               +------------------+      stdio      +------------------+
|                 |   /bridge                   |                  |                 |                  |
|  Cloud AI tools |   |  Node.js Bridge  |   |    MCP Server    |
|   (Remote)      |                             |    (Local)       |                 |     (Local)      |
|                 |   HTTP (SSE stream)         |                  |                 |                  |
|                 |   /mcp/:serverId            |                  |                 |                  |
+-----------------+         Tunnels (optional)  +------------------+                 +------------------+

Key Features

Quick Start

Prerequisites

• Node.js >= 22.0.0 (recommended)
• npm or yarn

1) Install

git clone https://github.com/EvalsOne/MCP-connect.git
cd mcp-connect
npm install

2) Preparations

A. Set up initial environment variables

cp .env.example .env

Set `ACCESS_TOKEN` in `.env` before starting the server. Startup fails if it is empty.

B. Configure MCP servers

For Streamable HTTP method, each MCP server needs to be configurated separately, edit file to add more configurations other than the existing sample servers.

vim mcp-servers.json

3) Run

# Build and start
npm run build
npm start

# Or use dev mode (hot reload)
npm run dev

# Enable Ngrok tunnel
npm run start:tunnel

After you see the startup banner, visit http://localhost:3000/health to check server status.

Usage

Mode 1: Streamable HTTP bridge

General-purpose and compatible with any MCP client that supports Streamable HTTP.

In Streamable HTTP mode, each MCP server is assigned a unique route. Example: add the `fetch` MCP server in `mcp-servers.json`.

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "description": "HTTP/HTTPS content fetcher"
    }
  }
}

Once started, access the `fetch` MCP server with your favorite MCP client (e.g. Claude Code, Cursor, Codex, GitHub Copilot...)

http://localhost:3000/mcp/fetch

Note: You must configure `mcp-servers.json` before starting the service, otherwise the server won't be available.

Mode 2: Classic request/response bridge

Non-standard invocation where you implement methods like `tools/list`, `tools/call`, etc.

Include ``Authorization: Bearer `` in every request header. `ACCESS_TOKEN` is required at startup.

Example 1: List available tools

curl -X POST http://localhost:3000/bridge \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "serverPath": "uvx",
    "args": ["mcp-server-fetch"],
    "method": "tools/list",
    "params": {}
  }'

Example 2: Call a tool

curl -X POST http://localhost:3000/bridge \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "serverPath": "uvx",
    "args": ["mcp-server-fetch"],
    "method": "tools/call",
    "params": {
      "name": "fetch",
      "arguments": {
        "url": "https://example.com"
      }
    }
  }'

Security

Authentication

MCP Connect requires a token-based authentication system. Set `ACCESS_TOKEN` in `.env` before startup. If it is empty, the server exits with a configuration error.

Authorization: Bearer

Allowed Origins

In production, set `ALLOWED_ORIGINS` to restrict cross-origin requests:

ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

If `ALLOWED_ORIGINS` is set, non-matching origins are rejected.

API Reference

`GET /health`

Health check endpoint (no auth required)

Response:

{"status": "ok"}

`POST /mcp/:serverId`

Streaming HTTP mode

Path params:

• `serverId`: server ID defined in `MCP_SERVERS`

Headers:

• `Authorization: Bearer ` (required)
• `Accept: application/json, text/event-stream` (required)
• `mcp-session-id: ` (optional, reuse existing session)

Body:

[
  {"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}},
  {"jsonrpc":"2.0","method":"notifications/initialized"}
]

`POST /bridge`

Original request/response bridge mode

Headers:

• `Authorization: Bearer ` (required)
• `Content-Type: application/json`

Body:

{
  "serverPath": "Executable command or URL (http/https/ws/wss)",
  "method": "JSON-RPC method name",
  "params": {},
  "args": ["optional command-line args"],
  "env": {"OPTIONAL_ENV_VAR": "value"}
}

Supported methods:

• `tools/list`, `tools/call`
• `prompts/list`, `prompts/get`
• `resources/list`, `resources/read`
• `resources/subscribe`, `resources/unsubscribe`
• `completion/complete`
• `logging/setLevel`

Expose Publicly via Ngrok

1. Get a token: https://dashboard.ngrok.com/get-started/your-authtoken

2. Add to `.env`:

NGROK_AUTH_TOKEN=your-token-here

3. Start the service:

npm run start:tunnel

4. The console will show public URLs:

Tunnel URL: https://abc123.ngrok.io
   MCP Bridge URL: https://abc123.ngrok.io/bridge

Quick Deploy to E2B Sandbox

E2B provides isolated cloud sandboxes, ideal for running untrusted MCP servers safely.

Step 1: Prepare E2B environment

# Sign up at https://e2b.dev and get an API key
pip install e2b
export E2B_API_KEY=your-e2b-api-key

Optionally set a bearer token for the bridge (preferred env for E2B deployments):

export E2B_MCP_AUTH_TOKEN=your-secure-token

Step 2: Build sandbox templates

cd deploy/e2b
python build.py

Step 3: Launch from template

python sandbox_deploy.py --template-id mcp-dev-gui

See：E2B deployment guide for details.

Logging & Monitoring

Log files

• `combined.log`: all levels
• `error.log`: error level only

Levels

Control verbosity via `LOG_LEVEL`:

LOG_LEVEL=DEBUG  # development
LOG_LEVEL=INFO   # production (default)
LOG_LEVEL=WARN   # warnings + errors

Development

Project layout

src/
├── server/
│   └── http-server.ts      # HTTP server and routes
├── client/
│   └── mcp-client-manager.ts  # MCP client manager
├── stream/
│   ├── session-manager.ts   # session lifecycle
│   └── stream-session.ts    # SSE session implementation
├── config/
│   └── config.ts            # config loading & validation
├── utils/
│   ├── logger.ts            # Winston logger
│   └── tunnel.ts            # Ngrok tunnel management
└── index.ts                 # entry point

Contributing

Issues and PRs are welcome!