Curl MCP Fly

通用MCP服务器代理

一个灵活的、生产就绪的代理服务器，它将任何基于stdio的MCP（模型上下文协议）服务器包装在一起，提供承载令牌身份验证和SSE流支持。

概述

该脚手架为部署MCP服务器提供了一个强大的基础设施，包括：

• 承载令牌身份验证 用于安全访问
• SSE流媒体 用于实时MCP协议通信
• 健康监测 优雅的启动操作
• 结构化日志记录 用于调试和监控
• 生产就绪 错误处理和优雅关机

快速开始

1.安装依赖项

要求：

• Node.js：22.x LTS或更高版本
• npm：10.x或更高（包含在Node 22中）

npm install

2.设置所需的环境变量

必修的：

• MCP_COMMAND -启动MCP服务器的命令

可选（用于生产）：

• BEARER_TOKEN -API访问的身份验证令牌
• DEBUG_LOGGING -启用详细日志记录(true 或 1)
• PORT -外部端口（默认：8080）

3.配置您的MCP服务器

设置 MCP_COMMAND 启动MCP服务器的命令的环境变量：

# GitHub MCP Server
export MCP_COMMAND="npx -y @modelcontextprotocol/server-github"

# Linear MCP Server  
export MCP_COMMAND="npx -y @linear-mcp/server"

# Custom MCP Server
export MCP_COMMAND="node /path/to/your/mcp-server.js"

4.添加工具特定的环境变量

传递MCP服务器所需的任何凭据：

export GITHUB_TOKEN="ghp_..."
export LINEAR_API_KEY="lin_api_..."
export OPENAI_API_KEY="sk-..."

5.启动代理

node server.js

代理将在端口8080上启动，并通过超级网关生成您的MCP服务器。

建筑

Client → Generic MCP Proxy (8080) → Supergateway (8000) → MCP Server (stdio)

组件详细信息

• 通用MCP代理：具有承载身份验证、请求路由和SSE流的HTTP服务器
• 超级网关：将HTTP/SSE桥接到stdio以进行MCP协议通信
• MCP服务器：您的特定MCP工具服务器（任何基于stdio的实现）

配置

API终点

GET /sse

MCP协议通信的SSE端点（生产中需要承载令牌）

POST /sse

MCP请求的HTTP端点（生产中需要承载令牌）

GET /health

健康检查端点-返回网关状态

认证

发展模式

在以下情况下，身份验证是可选的：

• NODE_ENV 不是 "production"
• FLY_APP_NAME 未设置

生产模式

在以下情况下需要身份验证：

• NODE_ENV 是 "production"
• FLY_APP_NAME 已设置（Fly.io部署）

生成安全令牌：

TOKEN=$(openssl rand -base64 32)
echo $TOKEN

设置令牌：

export BEARER_TOKEN="$TOKEN"

部署示例

Fly.io部署

1. 创建 fly.toml:

[build]
  dockerfile = "Dockerfile"

[env]
  PORT = "8080"

# VM resource allocation (Fly.io V2)
[[vm]]
  size = "shared-cpu-1x"
  memory = "512mb"

# HTTP service configuration (Fly.io V2)
[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 0
  processes = ["web"]

# TCP/TLS service configuration
[[services]]
  internal_port = 8080
  protocol = "tcp"
  processes = ['web']  # CRITICAL: Required for proper routing

  [[services.ports]]
    handlers = ["http"]
    port = 80

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

  [[services.tcp_checks]]
    grace_period = "1s"
    interval = "15s"
    restart_limit = 0
    timeout = "2s"

  [[services.http_checks]]
    grace_period = "10s"
    interval = "30s"
    method = "GET"
    path = "/healthz"
    protocol = "http"
    restart_limit = 0
    timeout = "5s"
    tls_skip_verify = false

# Process configuration
[processes]
  web = "node server.js"

看 fly.example.toml 以完成V2配置。

1. 部署：

flyctl deploy --remote-only

1. 设置秘密：

flyctl secrets set BEARER_TOKEN="$TOKEN"
flyctl secrets set MCP_COMMAND="npx -y @modelcontextprotocol/server-github"
flyctl secrets set GITHUB_TOKEN="ghp_..."

Docker部署

1. 创建 Dockerfile:

FROM node:22-alpine3.23

WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
ENV PATH="/app/node_modules/.bin:$PATH"

COPY . .

EXPOSE 8080
CMD ["node", "server.js"]

主要特点：

• ✅ 节点22 LTS基础映像
• ✅ 将npm二进制文件烘焙到PATH中以直接执行
• ✅ 现代npm命令(--omit=dev 而不是弃用的标志）
• ✅ 非root用户安全
• ✅ 健康检查包括

1. 构建并运行：

docker build -t mcp-proxy .
docker run -p 8080:8080 \
  -e MCP_COMMAND="npx -y @modelcontextprotocol/server-github" \
  -e BEARER_TOKEN="$TOKEN" \
  -e GITHUB_TOKEN="ghp_..." \
  mcp-proxy

MCP服务器兼容性

此代理适用于以下任何MCP服务器：

• 通过stdio进行通信
• 遵循MCP协议规范
• 可以通过命令行界面启动

经过测试的MCP服务器

• @modelcontextprotocol/server-github
• @linear-mcp/server
• 基于stdio的自定义MCP服务器

监控与调试

结构化日志记录

所有事件都以JSON格式记录，结构如下：

{
  "timestamp": "2025-01-01T00:00:00.000Z",
  "level": "info",
  "category": "mcp-call",
  "phase": "runtime",
  "message": "MCP method: tools/call",
  "data": { "requestId": "abc123", "method": "tools/call" }
}

调试模式

启用详细日志记录：

export DEBUG_LOGGING=true
node server.js

健康监测

监控网关运行状况：

curl http://localhost:8080/health

答复：

{
  "status": "healthy",
  "gatewayReady": true,
  "gatewayExited": false,
  "uptimeMs": 12345
}

故障排除

常见问题

“MCP_COMMAND环境变量是必需的”

• 设置 MCP_COMMAND MCP服务器启动命令的环境变量

“生产中需要BEARER_TOKEN”

• 为生产部署生成并设置安全的承载令牌

“网关启动超时”

• 检查您的MCP命令是否有效，服务器是否可以启动
• 验证您的MCP服务器是否设置了所有必需的环境变量

“服务不可用：MCP网关已退出”

• 检查日志中的启动错误
• 确保您的MCP服务器兼容且配置正确

调试步骤

1. 手动验证MCP命令：

eval $MCP_COMMAND --help

1. 检查环境变量：

env | grep -E "(MCP_COMMAND|BEARER_TOKEN)"

1. 启用调试日志记录：

export DEBUG_LOGGING=true
node server.js

1. 测试健康终点：

curl -v http://localhost:8080/health

安全注意事项

• 在生产中始终使用不记名代币 -该端点可以通过其他方式公开访问
• 定期旋转令牌 -在部署管道中实现令牌轮换
• 限制令牌范围 -使用具有最低所需权限的令牌
• 监控访问日志 -警惕未经授权的访问企图
• 在生产环境中使用HTTPS -在负载均衡器或反向代理端终止TLS

演出

• 冷启动处理 -代理在接受请求之前等待MCP服务器启动
• SSE流媒体 -长期连接得到妥善管理，没有超时
• 请求缓冲 -HTTP请求被缓冲；SSE响应被流式传输
• 资源限制 -网关进程有50MB的缓冲区限制，以防止内存问题

经验教训：npm二进制路径管理

问题

npm包将二进制文件安装到 node_modules/.bin/，默认情况下不在系统PATH中。这导致了以下问题 supergateway 无法直接访问，需要 npx 变通办法。

解决方案

在Docker构建时将npm二进制文件烘焙到PATH中：

RUN npm install --omit=dev
ENV PATH="/app/node_modules/.bin:$PATH"

好处

• ✅ 更快的启动 -无npx处置开销
• ✅ 可预测的行为 -直接二进制执行
• ✅ 离线兼容性 -没有网络呼叫来检查更新
• ✅ 清理原木 -没有npx消息
• ✅ 生产就绪 -符合最佳实践

为何这很重要

在分叉此脚手架时，请确保您的Dockerfile包含PATH配置。没有它，你需要使用 npx 前缀或在运行时手动将二进制文件添加到PATH中，这会增加复杂性并降低性能。

许可证

MIT许可证-您可以自由地将此脚手架用于MCP服务器部署。