MCP-connect
Enables cloud-based AI services to access local Stdio based MCP servers via HTTP requests
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/evalsone--mcp-connect)HTML
<a href="/listings/evalsone--mcp-connect"><img src="/api/listings/evalsone--mcp-connect/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 369 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # MCP Connect
- ███╗ ███╗ ██████╗██████╗ ██████╗ ██████╗ ███╗ ██╗███╗ ██╗███████╗ ██████╗████████╗
- ████╗ ████║██╔════╝██╔══██╗ ██╔════╝██╔═══██╗████╗ ██║████╗ ██║██╔════╝██╔════╝╚══██╔══╝
- ██╔████╔██║██║ ██████╔╝ ██║ ██║ ██║██╔██╗ ██║██╔██╗ ██║█████╗ ██║ ██║
- ██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║ ██║██║╚██╗██║██║╚██╗██║██╔══╝ ██║ ██║
- ██║ ╚═╝ ██║╚██████╗██║ ╚██████╗╚██████╔╝██║ ╚████║██║ ╚████║███████╗╚██████╗ ██║
- ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═══╝╚══════╝ ╚═════╝ ╚═╝
- <div align="center">
- [](https://opensource.org/licenses/MIT)
- [](https://nodejs.org/)
- [](https://www.typescriptlang.org/)
- **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
- ```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 <token>`` 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 <your_auth_token>
- ```
- #### 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 <token>` (required)
- - `Accept: application/json, text/event-stream` (required)
- - `mcp-session-id: <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 <token>` (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!
- ---
- <div align="center">
- **If this project helps you, please ⭐️ Star it!**
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.