Gateway
A high-performance MCP (Model Context Protocol) gateway written in Go that bridges multiple downstream MCP servers to an upstream WebSocket endpoint.
Installation
npx mcp-gatewayAsk AI about Gateway
Powered by Claude ยท Grounded in docs
I know everything about Gateway. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Gateway
A high-performance MCP (Model Context Protocol) gateway written in Go that bridges multiple downstream MCP servers to multiple upstream WebSocket endpoints.
Features
- ๐ High Performance: Native Go concurrency with goroutines
- ๐ Multiple Transport Types: Supports stdio, HTTP, SSE, and StreamableHTTP
- ๐ Auto Reconnection: Exponential backoff with jitter
- ๐ Tool Aggregation: Aggregates tools from multiple MCP servers
- ๐ก๏ธ Robust Error Handling: Graceful shutdown and process management
- ๐ Structured Logging: Using Go 1.21+ slog with verbose mode
- ๐ Multi-Upstream Support: Connect multiple upstreams with independent MCP server configurations
- ๐ง Environment Variables: Support
${VAR}syntax in config files
Architecture
โโโโโโโโโโโโโโโโโโโ WebSocket โโโโโโโโโโโโโโโโโโโโ
โ Upstream AI 1 โ โโโโโโโโโโโโโโโโโโโบ โ โ
โ (xiaozhi-1) โ โ โ
โโโโโโโโโโโโโโโโโโโ โ mcp-gateway โ
โ โ
โโโโโโโโโโโโโโโโโโโ WebSocket โ โ
โ Upstream AI 2 โ โโโโโโโโโโโโโโโโโโโบ โ โ
โ (xiaozhi-2) โ โโโโโโโโโโฌโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโผโโโโโโโโโโโโโโ
โผ โผ โผ
โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ
โ stdio โ โ HTTP โ โ SSE โ
โ adapter โ โ adapter โ โ adapter โ
โโโโโโฌโโโโโโ โโโโโโฌโโโโโโ โโโโโโฌโโโโโโ
โ โ โ
โโโโโโผโโโโโ โโโโโโผโโโโโ โโโโโโผโโโโโ
โcalculatorโ โweb-searchโ โsmartrun โ
โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโ
Note: Each upstream has its own independent MCP servers configuration, allowing different tokens/credentials per upstream.
Quick Start
1. Clone and Build
cd mcp-gateway
go mod tidy
go build -o mcp-gateway ./cmd/mcp-gateway
2. Configure
# ๅคๅถ็คบไพ้
็ฝฎๆไปถ
cp configs/mcp_config.example.json configs/mcp_config.json
cp run_local.example.sh run_local.sh
cp deploy_remote.example.sh deploy_remote.sh
# ็ผ่พ้
็ฝฎๆไปถ๏ผๅกซๅ
ฅไฝ ็ token
vim configs/mcp_config.json
vim run_local.sh
vim deploy_remote.sh
# ๆทปๅ ๆง่กๆ้
chmod +x run_local.sh deploy_remote.sh
3. Run
# ๆฌๅฐ macOS ่ฟ่ก
./run_local.sh build # ็ผ่ฏ
./run_local.sh start # ๅฏๅจ
./run_local.sh status # ๆฅ็็ถๆ
./run_local.sh logs # ๆฅ็ๆฅๅฟ
./run_local.sh check # ๆฃๆฅ MCP ๆๅกๅจ็ถๆๅๅทฅๅ
ทๅ่กจ
# ่ฟ็จ Linux ้จ็ฝฒ
./deploy_remote.sh deploy # ็ผ่ฏ + ไธไผ + ๅฏๅจ
./deploy_remote.sh status # ่ฟ็จ็ถๆ
./deploy_remote.sh logs # ่ฟ็จๆฅๅฟ
Check Command
ไฝฟ็จ check ๅฝไปคๅฏไปฅ้ช่ฏ้
็ฝฎๅนถๆฃๆฅๆๆ MCP ๆๅกๅจ็่ฟๆฅ็ถๆๅๅฏ็จๅทฅๅ
ท๏ผ
# ้่ฟ่ๆฌ่ฟ่ก
./run_local.sh check
# ๆ็ดๆฅ่ฟ่กไบ่ฟๅถ
./mcp-gateway -check -config configs/mcp_config.json
# JSON ๆ ผๅผ่พๅบ๏ผๆนไพฟ่ๆฌ่งฃๆ๏ผ
./mcp-gateway -check -config configs/mcp_config.json -output json
# ่ชๅฎไน่ถ
ๆถๆถ้ด
./mcp-gateway -check -config configs/mcp_config.json -timeout 60s
่พๅบ็คบไพ๏ผ
==================================================
MCP Gateway Configuration Check
==================================================
๐ก Upstream: xiaozhi-agent
Endpoint: wss://api.xiaozhi.me/mcp/?token=***
โ
[tencentdocs] (http)
URL: https://docs.qq.com/openapi/mcp
Status: Connected
Server: mcp-McpserverService v1.0.0
Tools (12):
โข create_word_by_markdown ้่ฟMarkdownๆ ผๅผๅๅปบๅจ็บฟWordๆๆกฃ...
โข get_content ่ทๅๆๆกฃๅฎๆดๅ
ๅฎน...
...
โ [local-mcp] (stdio)
Command: python mcp_server.py
Status: Failed
Error: start failed: exec: "python": not found
--------------------------------------------------
๐ Summary
--------------------------------------------------
Total Upstreams: 1
Total MCP Servers: 2
โข Healthy: 1
โข Failed: 1
Total Tools: 12
==================================================
Configuration
Environment Variables
# Optional: WebSocket endpoint (can be used with ${MCP_ENDPOINT} in config)
export MCP_ENDPOINT='wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN'
# Optional: Log level
export MCP_LOG_LEVEL=debug
Config File Format
See configs/mcp_config.example.json for full example:
{
"upstreams": [
{
"name": "xiaozhi-agent-1",
"endpoint": "${MCP_ENDPOINT}",
"reconnect": {
"enabled": true,
"initialBackoff": "1s",
"maxBackoff": "10m",
"multiplier": 2
},
"keepalive": {
"interval": "30s",
"timeout": "10s"
},
"mcpServers": {
"tencentdocs": {
"type": "http",
"url": "https://docs.qq.com/openapi/mcp",
"headers": {
"Authorization": "your-token"
},
"timeout": "60s",
"disabled": false
},
"web-search": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp",
"timeout": "120s"
}
}
},
{
"name": "xiaozhi-agent-2",
"endpoint": "wss://api.xiaozhi.me/mcp/?token=ANOTHER_TOKEN",
"reconnect": { "enabled": true },
"keepalive": { "interval": "30s", "timeout": "10s" },
"mcpServers": {
"xxx-mcp": {
"type": "http",
"url": "https://xxx-mcp.123.com/mcp",
"headers": { "Authorization": "Bearer your-smartrun-token" },
"timeout": "180s"
}
}
}
],
"logging": {
"level": "info",
"format": "text",
"verbose": false
},
"metrics": {
"enabled": false,
"port": 9090
}
}
Configuration Structure
| Field | Description |
|---|---|
upstreams | Array of upstream configurations, each with independent MCP servers |
upstreams[].name | Unique name for the upstream instance |
upstreams[].endpoint | WebSocket URL (supports ${VAR} environment variable expansion) |
upstreams[].reconnect | Reconnection settings (enabled, initialBackoff, maxBackoff, multiplier) |
upstreams[].keepalive | Keepalive settings (interval, timeout) |
upstreams[].mcpServers | Map of MCP server configurations for this upstream |
logging.verbose | When true, logs full request arguments and response content |
Server Types
| Type | Description |
|---|---|
stdio | Local process with stdin/stdout communication |
http | HTTP/StreamableHTTP endpoint |
sse | Server-Sent Events endpoint |
Multi-Upstream Use Case
Each upstream can have its own set of MCP servers with different configurations:
- Different AI agents: Connect multiple AI assistants simultaneously
- Different credentials: Each upstream can use different tokens for the same MCP service
- Independent routing: Tools from each upstream's MCP servers are routed independently
Files Structure
mcp-gateway/
โโโ cmd/mcp-gateway/ # Main entry point
โ โโโ main.go # Application bootstrap
โโโ internal/
โ โโโ adapter/ # MCP server adapters (stdio, http, sse)
โ โโโ checker/ # Configuration check & validation
โ โโโ config/ # Configuration management
โ โโโ protocol/ # MCP protocol definitions
โ โโโ router/ # Message routing & tool aggregation
โ โโโ upstream/ # WebSocket upstream client
โโโ pkg/retry/ # Retry utilities with backoff
โโโ configs/
โ โโโ mcp_config.example.json # โญ ้
็ฝฎ็คบไพ๏ผๆไบคๅฐ git๏ผ
โ โโโ mcp_config.json # ๐ ๅฎ้
้
็ฝฎ๏ผไธๆไบค๏ผ
โโโ run_local.example.sh # โญ ๆฌๅฐ่ฟ่ก่ๆฌ็คบไพ
โโโ run_local.sh # ๐ ๆฌๅฐ่ฟ่ก่ๆฌ๏ผๅซ็ฏๅขๅ้๏ผ
โโโ deploy_remote.example.sh # โญ ่ฟ็จ้จ็ฝฒ่ๆฌ็คบไพ
โโโ deploy_remote.sh # ๐ ่ฟ็จ้จ็ฝฒ่ๆฌ๏ผๅซๆๅกๅจไฟกๆฏ๏ผ
โโโ go.mod # Go module definition
โโโ .gitignore # Git ignore rules
Security Notes
โ ๏ธ ๆๆไฟกๆฏๅค็๏ผ
ไปฅไธๆไปถๅ ๅซ token ็ญๆๆไฟกๆฏ๏ผไธ่ฆๆไบคๅฐ git๏ผ
configs/mcp_config.jsonrun_local.shdeploy_remote.sh.env
่ฏทไฝฟ็จ .example ๅ็ผ็็คบไพๆไปถไฝไธบๆจกๆฟ๏ผๅคๅถๅๅกซๅ
ฅไฝ ็ๅฎ้
้
็ฝฎใ
Building
# Development build
go build -o mcp-gateway ./cmd/mcp-gateway
# Production build with optimizations
CGO_ENABLED=0 go build -ldflags="-s -w" -o mcp-gateway ./cmd/mcp-gateway
# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o mcp-gateway-linux ./cmd/mcp-gateway
Comparison with Python Version
| Aspect | Python (mcp_pipe.py) | Go (mcp-gateway) |
|---|---|---|
| Performance | Single-threaded asyncio | Native goroutines |
| Memory | ~50-100MB | ~10-20MB |
| Startup | 2-3s | <100ms |
| Deployment | Python + venv + deps | Single binary |
| Process Mgmt | Subprocess + mcp_proxy | In-process |
| Stability | Basic error handling | Robust recovery |
License
MIT
