MCP Connect

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

<div align="center">

Lightweight bridge that exposes local MCP servers as HTTP APIs

</div>

---

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

| Feature | Description |
|--------|-------------|
| 🚀 Dual modes | Call local stdio MCP servers via Streamable HTTP or the classic HTTP bridge |
| 🔄 Session management | Maintain conversational continuity with sessions |
| 🔐 Security | Bearer token auth + CORS allowlist |
| 🌐 Public access | Built-in Ngrok tunnel to expose endpoints externally |
| ☁️ Cloud deploy | One-click deploy to E2B cloud sandbox |
---

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 <token> in every request header. ACCESS_TOKEN is required at startup.

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": {}
  }'

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"
      }
    }
  }'

Authorization: Bearer <your_auth_token>

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

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

GET /health

{"status": "ok"}

POST /mcp/:serverId

Path params:
- serverId: server ID defined in MCP_SERVERS

Headers:
- Authorization: Bearer <token> (required)
- Accept: application/json, text/event-stream (required)
- mcp-session-id: <session-id> (optional, reuse existing session)

[

  {"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}},

  {"jsonrpc":"2.0","method":"notifications/initialized"}

]

POST /bridge

Headers:
- Authorization: Bearer <token> (required)
- Content-Type: application/json

{

  "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

2. Add to .env:


   NGROK_AUTH_TOKEN=your-token-here

   

   npm run start:tunnel

   

   Tunnel URL: https://abc123.ngrok.io

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

   

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

export E2B_MCP_AUTH_TOKEN=your-secure-token

cd deploy/e2b
python build.py

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

- combined.log: all levels
- error.log: error level only

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!

---

<div align="center">

If this project helps you, please ⭐️ Star it!

</div>