Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/evalsone--mcp-connect/badge.svg)](/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

i

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)

  1. # MCP Connect
  2. ███╗ ███╗ ██████╗██████╗ ██████╗ ██████╗ ███╗ ██╗███╗ ██╗███████╗ ██████╗████████╗
  3. ████╗ ████║██╔════╝██╔══██╗ ██╔════╝██╔═══██╗████╗ ██║████╗ ██║██╔════╝██╔════╝╚══██╔══╝
  4. ██╔████╔██║██║ ██████╔╝ ██║ ██║ ██║██╔██╗ ██║██╔██╗ ██║█████╗ ██║ ██║
  5. ██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║ ██║██║╚██╗██║██║╚██╗██║██╔══╝ ██║ ██║
  6. ██║ ╚═╝ ██║╚██████╗██║ ╚██████╗╚██████╔╝██║ ╚████║██║ ╚████║███████╗╚██████╗ ██║
  7. ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═══╝╚══════╝ ╚═════╝ ╚═╝
  8. <div align="center">
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  10. [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
  11. [![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-blue)](https://www.typescriptlang.org/)
  12. **Lightweight bridge that exposes local MCP servers as HTTP APIs**
  13. </div>
  14. ---
  15. ## What Is MCP Connect?
  16. 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.
  17. ### What's New
  18. - Added Streamable HTTP mode on top of the classic request/response bridge
  19. - New quick-deploy scripts and configs under `deploy/e2b` for launching in an E2B sandbox
  20. ## How It Works
  21. ```
  22. +-----------------+ HTTP (JSON) +------------------+ stdio +------------------+
  23. | | /bridge | | | |
  24. | Cloud AI tools | <------------------------> | Node.js Bridge | <------------> | MCP Server |
  25. | (Remote) | | (Local) | | (Local) |
  26. | | HTTP (SSE stream) | | | |
  27. | | /mcp/:serverId | | | |
  28. +-----------------+ Tunnels (optional) +------------------+ +------------------+
  29. ```
  30. **Key Features**
  31. | Feature | Description |
  32. |--------|-------------|
  33. | 🚀 Dual modes | Call local stdio MCP servers via Streamable HTTP or the classic HTTP bridge |
  34. | 🔄 Session management | Maintain conversational continuity with sessions |
  35. | 🔐 Security | Bearer token auth + CORS allowlist |
  36. | 🌐 Public access | Built-in Ngrok tunnel to expose endpoints externally |
  37. | ☁️ Cloud deploy | One-click deploy to E2B cloud sandbox |
  38. ---
  39. ## Quick Start
  40. ### Prerequisites
  41. - Node.js >= 22.0.0 (recommended)
  42. - npm or yarn
  43. ### 1) Install
  44. ```bash
  45. git clone https://github.com/EvalsOne/MCP-connect.git
  46. cd mcp-connect
  47. npm install
  48. ```
  49. ### 2) Preparations
  50. **A. Set up initial environment variables**
  51. ```bash
  52. cp .env.example .env
  53. ```
  54. Set `ACCESS_TOKEN` in `.env` before starting the server. Startup fails if it is empty.
  55. **B. Configure MCP servers**
  56. For Streamable HTTP method, each MCP server needs to be configurated separately, edit file to add more configurations other than the existing sample servers.
  57. ```bash
  58. vim mcp-servers.json
  59. ```
  60. ### 3) Run
  61. ```bash
  62. # Build and start
  63. npm run build
  64. npm start
  65. # Or use dev mode (hot reload)
  66. npm run dev
  67. # Enable Ngrok tunnel
  68. npm run start:tunnel
  69. ```
  70. After you see the startup banner, visit http://localhost:3000/health to check server status.
  71. ---
  72. ## Usage
  73. ### Mode 1: Streamable HTTP bridge
  74. General-purpose and compatible with any MCP client that supports Streamable HTTP.
  75. In Streamable HTTP mode, each MCP server is assigned a unique route. Example: add the `fetch` MCP server in `mcp-servers.json`.
  76. ```json
  77. {
  78. "mcpServers": {
  79. "fetch": {
  80. "command": "uvx",
  81. "args": ["mcp-server-fetch"],
  82. "description": "HTTP/HTTPS content fetcher"
  83. }
  84. }
  85. }
  86. ```
  87. Once started, access the `fetch` MCP server with your favorite MCP client (e.g. Claude Code, Cursor, Codex, GitHub Copilot...)
  88. ```
  89. http://localhost:3000/mcp/fetch
  90. ```
  91. Note: You must configure `mcp-servers.json` before starting the service, otherwise the server won't be available.
  92. ---
  93. ### Mode 2: Classic request/response bridge
  94. Non-standard invocation where you implement methods like `tools/list`, `tools/call`, etc.
  95. Include ``Authorization: Bearer <token>`` in every request header. `ACCESS_TOKEN` is required at startup.
  96. #### Example 1: List available tools
  97. ```bash
  98. curl -X POST http://localhost:3000/bridge \
  99. -H "Authorization: Bearer your-secret-token-here" \
  100. -H "Content-Type: application/json" \
  101. -d '{
  102. "serverPath": "uvx",
  103. "args": ["mcp-server-fetch"],
  104. "method": "tools/list",
  105. "params": {}
  106. }'
  107. ```
  108. #### Example 2: Call a tool
  109. ```bash
  110. curl -X POST http://localhost:3000/bridge \
  111. -H "Authorization: Bearer your-secret-token-here" \
  112. -H "Content-Type: application/json" \
  113. -d '{
  114. "serverPath": "uvx",
  115. "args": ["mcp-server-fetch"],
  116. "method": "tools/call",
  117. "params": {
  118. "name": "fetch",
  119. "arguments": {
  120. "url": "https://example.com"
  121. }
  122. }
  123. }'
  124. ```
  125. ### Security
  126. #### Authentication
  127. 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.
  128. ```bash
  129. Authorization: Bearer <your_auth_token>
  130. ```
  131. #### Allowed Origins
  132. In production, set `ALLOWED_ORIGINS` to restrict cross-origin requests:
  133. ```env
  134. ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
  135. ```
  136. If `ALLOWED_ORIGINS` is set, non-matching origins are rejected.
  137. ---
  138. ## API Reference
  139. ### `GET /health`
  140. Health check endpoint (no auth required)
  141. Response:
  142. ```json
  143. {"status": "ok"}
  144. ```
  145. ---
  146. ### `POST /mcp/:serverId`
  147. Streaming HTTP mode
  148. Path params:
  149. - `serverId`: server ID defined in `MCP_SERVERS`
  150. Headers:
  151. - `Authorization: Bearer <token>` (required)
  152. - `Accept: application/json, text/event-stream` (required)
  153. - `mcp-session-id: <session-id>` (optional, reuse existing session)
  154. Body:
  155. ```json
  156. [
  157. {"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}},
  158. {"jsonrpc":"2.0","method":"notifications/initialized"}
  159. ]
  160. ```
  161. ---
  162. ### `POST /bridge`
  163. Original request/response bridge mode
  164. Headers:
  165. - `Authorization: Bearer <token>` (required)
  166. - `Content-Type: application/json`
  167. Body:
  168. ```json
  169. {
  170. "serverPath": "Executable command or URL (http/https/ws/wss)",
  171. "method": "JSON-RPC method name",
  172. "params": {},
  173. "args": ["optional command-line args"],
  174. "env": {"OPTIONAL_ENV_VAR": "value"}
  175. }
  176. ```
  177. Supported methods:
  178. - `tools/list`, `tools/call`
  179. - `prompts/list`, `prompts/get`
  180. - `resources/list`, `resources/read`
  181. - `resources/subscribe`, `resources/unsubscribe`
  182. - `completion/complete`
  183. - `logging/setLevel`
  184. ---
  185. ## Expose Publicly via Ngrok
  186. 1. Get a token: https://dashboard.ngrok.com/get-started/your-authtoken
  187. 2. Add to `.env`:
  188. ```env
  189. NGROK_AUTH_TOKEN=your-token-here
  190. ```
  191. 3. Start the service:
  192. ```bash
  193. npm run start:tunnel
  194. ```
  195. 4. The console will show public URLs:
  196. ```
  197. Tunnel URL: https://abc123.ngrok.io
  198. MCP Bridge URL: https://abc123.ngrok.io/bridge
  199. ```
  200. ---
  201. ## Quick Deploy to E2B Sandbox
  202. E2B provides isolated cloud sandboxes, ideal for running untrusted MCP servers safely.
  203. ### Step 1: Prepare E2B environment
  204. ```bash
  205. # Sign up at https://e2b.dev and get an API key
  206. pip install e2b
  207. export E2B_API_KEY=your-e2b-api-key
  208. ```
  209. Optionally set a bearer token for the bridge (preferred env for E2B deployments):
  210. ```bash
  211. export E2B_MCP_AUTH_TOKEN=your-secure-token
  212. ```
  213. ### Step 2: Build sandbox templates
  214. ```bash
  215. cd deploy/e2b
  216. python build.py
  217. ```
  218. ### Step 3: Launch from template
  219. ```bash
  220. python sandbox_deploy.py --template-id mcp-dev-gui
  221. ```
  222. See:[E2B deployment guide](deploy/e2b/README.md) for details.
  223. ---
  224. ## Logging & Monitoring
  225. ### Log files
  226. - `combined.log`: all levels
  227. - `error.log`: error level only
  228. ### Levels
  229. Control verbosity via `LOG_LEVEL`:
  230. ```env
  231. LOG_LEVEL=DEBUG # development
  232. LOG_LEVEL=INFO # production (default)
  233. LOG_LEVEL=WARN # warnings + errors
  234. ```
  235. ---
  236. ## Development
  237. ### Project layout
  238. ```
  239. src/
  240. ├── server/
  241. │ └── http-server.ts # HTTP server and routes
  242. ├── client/
  243. │ └── mcp-client-manager.ts # MCP client manager
  244. ├── stream/
  245. │ ├── session-manager.ts # session lifecycle
  246. │ └── stream-session.ts # SSE session implementation
  247. ├── config/
  248. │ └── config.ts # config loading & validation
  249. ├── utils/
  250. │ ├── logger.ts # Winston logger
  251. │ └── tunnel.ts # Ngrok tunnel management
  252. └── index.ts # entry point
  253. ```
  254. ---
  255. ## Contributing
  256. Issues and PRs are welcome!
  257. ---
  258. <div align="center">
  259. **If this project helps you, please ⭐️ Star it!**
  260. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.