Content
# MCP Bridge Service
Dynamically convert any stdio-based MCP server into an HTTP endpoint.
## Overview
**MCP Bridge Service** is a management service that lets you take any MCP server
configuration using stdio transport (command + args + env) and expose it via
**Streamable HTTP** or **SSE** transport — on any port, instantly.
```bash
# 1. Start the service
python run.py
# 2. Register an MCP server (just the package name!)
curl -X POST http://127.0.0.1:8191/register \
-H 'Content-Type: application/json' \
-d '{"stdio": "bing-cn-mcp"}'
# 3. Use it via HTTP
curl -s http://<public-ip>:<returned-port>/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
## Features
- **Auto name resolution** — just pass `"bing-cn-mcp"` and it auto-runs `npx -y <name>`
- **Two transport modes**: Streamable HTTP (default, request-response) and SSE (session-based streaming)
- **Dynamic ports**: specify a port or let the OS assign a random one (port: 0)
- **Management API**: `POST /register`, `GET /servers`, `DELETE /servers/{id}`
- **Web dashboard**: built-in management page at `http://localhost:8191/` for visual proxy management
- **Multiple instances**: run multiple MCP servers in parallel, each on its own port
- **Real public IP**: endpoints display the machine's public IP automatically
- **Client-friendly**: supports both `/` and `/mcp` paths with CORS headers
- **Subprocess isolation**: each proxy runs in its own process; a crash won't affect others
- **Auto-cleanup**: all proxy processes are terminated when the service shuts down
## Requirements
- Python 3.10+
- `pip install -r requirements.txt` (fastapi + uvicorn)
## Project Structure
```
mcp-slink/
├── pyproject.toml # Project metadata
├── run.py # Entry point (python run.py)
├── requirements.txt # Python dependencies
├── register.example.json # Example config
└── src/
└── mcp_bridge/
├── __init__.py # Package marker
├── __main__.py # python -m mcp_bridge support
├── config.py # StdioConfig, name resolution, IP detection
├── server.py # MCP subprocess manager, SSE sessions, JSON-RPC helpers
├── proxy_app.py # Single proxy FastAPI app
├── service_app.py # Management API + HTML dashboard
└── cli.py # CLI entry point
```
## Usage
### Service mode (default)
Start the management API:
```bash
python run.py
# or with custom admin port
python run.py --admin-port 9000
# or via package
PYTHONPATH=src python -m mcp_bridge
```
Then open the **web dashboard** at [http://localhost:8191/](http://localhost:8191/)
to view and manage proxies visually, or use the API directly.
Register a proxy — three ways:
```bash
# ① Just the server name (auto-resolves to npx -y <name>)
curl -X POST http://127.0.0.1:8191/register \
-H 'Content-Type: application/json' \
-d '{"stdio": "bing-cn-mcp"}'
# ② Full command config
curl -X POST http://127.0.0.1:8191/register \
-H 'Content-Type: application/json' \
-d '{
"stdio": {
"command": "npx",
"args": ["-y", "bing-cn-mcp"]
}
}'
# ③ Claude Desktop mcpServers format
curl -X POST http://127.0.0.1:8191/register \
-H 'Content-Type: application/json' \
-d '{
"stdio": {
"mcpServers": {
"bing-search": {
"command": "npx",
"args": ["-y", "bing-cn-mcp"]
}
}
}
}'
```
Response:
```json
{
"id": "mcp-a1b2c3d4",
"port": 54321,
"transport": "STREAMABLEHTTP",
"status": "running",
"pid": 12345,
"endpoints": {
"http": "http://101.42.40.58:54321/mcp"
},
"created_at": "2026-06-17T07:38:31Z"
}
```
Use the proxy:
```bash
curl -s http://101.42.40.58:54321/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
### Direct proxy mode (standalone)
Run a single proxy without the management API:
```bash
python run.py --mode proxy --transport STREAMABLEHTTP --port 8765 config.json
# or
PYTHONPATH=src python -m mcp_bridge --mode proxy --transport SSE --port 8765 config.json
```
Config file formats — see [register.example.json](register.example.json).
### Server name resolution
When you pass a string as `stdio` (e.g. `"bing-cn-mcp"`), the bridge:
1. Checks `~/.config/claude/mcp_servers.json` or `./mcp_servers.json` for a mapping
2. Falls back to `npx -y <name>` (assumes npm package)
To define custom mappings:
```json
{
"my-server": {
"command": "python",
"args": ["-m", "my_mcp_server"],
"env": { "API_KEY": "xxx" }
},
"bing-cn-mcp": {
"command": "npx",
"args": ["-y", "bing-cn-mcp"]
}
}
```
Save as `~/.config/claude/mcp_servers.json` or set `MCP_SERVERS_CONFIG` env var.
### Override public IP
Set the `MCP_PUBLIC_HOST` env var to override auto-detection:
```bash
MCP_PUBLIC_HOST=example.com python run.py
```
## API Reference
### `POST /register`
Create a proxy instance.
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `stdio` | string \| object | **required** | Server name (string) or `{command, args?, env?}` |
| `transport` | string | `STREAMABLEHTTP` | `STREAMABLEHTTP` or `SSE` |
| `port` | int | `0` | Port number; `0` = random |
### `GET /servers`
List all running proxy instances.
### `GET /servers/{id}`
Get details for a specific proxy.
### `DELETE /servers/{id}`
Stop and remove a proxy instance.
## Transport Protocols
### Streamable HTTP (default)
Single POST endpoint at `/` and `/mcp`. Each request is independent.
```
POST /mcp → JSON-RPC request → (stdin → stdout) → JSON-RPC response
```
- No persistent connection or session state required
- Responses are matched by JSON-RPC `id` field
### SSE (Server-Sent Events)
Session-based streaming transport.
```
GET /sse → SSE stream (receives server messages)
POST /messages?sessionId=<id> → Send request to server
```
- Each SSE connection creates a session
- Server-to-client messages flow through the SSE stream
- Client-to-server messages go through the POST endpoint
## Architecture
```
┌──────────────────────────────────────┐
│ MCP Bridge Service │
│ (management API, :8191) │
│ │
│ POST /register ──→ spawns ──────────┼──→ Proxy Process A (:54321)
│ GET /servers │ └── MCP Server (npx ...)
│ DELETE /servers/:id │
│ ┌──────────────────┤──→ Proxy Process B (:54322)
│ │ PYTHONPATH=src │ └── MCP Server (python ...)
│ │ python -m │
│ │ mcp_bridge │
│ │ --mode proxy │
│ └──────────────────┘
└──────────────────────────────────────┘
```
Each proxy is a subprocess running `python -m mcp_bridge --mode proxy`.
The service tracks all processes and cleans them up on shutdown.
## License
MIT
