# MCP Connect

> Enables cloud-based AI services to access local Stdio based MCP servers via HTTP requests

- **Type:** MCP server
- **Install:** `agentstack add mcp-evalsone-mcp-connect`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [EvalsOne](https://agentstack.voostack.com/s/evalsone)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [EvalsOne](https://github.com/EvalsOne)
- **Source:** https://github.com/EvalsOne/MCP-connect

## Install

```sh
agentstack add mcp-evalsone-mcp-connect
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Connect

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

[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)

**Lightweight bridge that exposes local MCP servers as HTTP APIs**

---

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

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

### 2) Preparations

**A. Set up initial environment variables**

```bash
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.
```bash
vim mcp-servers.json  
```

### 3) Run

```bash
# 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`.

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

```bash
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

```bash
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.

```bash
Authorization: Bearer 
```

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

```env
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:
```json
{"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:
```json
[
  {"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:
```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`

---

## Expose Publicly via Ngrok

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

2. Add to `.env`:
   ```env
   NGROK_AUTH_TOKEN=your-token-here
   ```

3. Start the service:
   ```bash
   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

```bash
# 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):

```bash
export E2B_MCP_AUTH_TOKEN=your-secure-token
```

### Step 2: Build sandbox templates

```bash
cd deploy/e2b
python build.py
```

### Step 3: Launch from template

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

See：[E2B deployment guide](deploy/e2b/README.md) for details.

---

## Logging & Monitoring

### Log files

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

### Levels

Control verbosity via `LOG_LEVEL`:

```env
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!

---

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [EvalsOne](https://github.com/EvalsOne)
- **Source:** [EvalsOne/MCP-connect](https://github.com/EvalsOne/MCP-connect)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-evalsone-mcp-connect
- Seller: https://agentstack.voostack.com/s/evalsone
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.