MCP Streamablehttp Proxy

mcp流式http代理

用于MCP（模型上下文协议）服务器的通用stdio到StreamableHTTP桥。该代理允许通过HTTP端点访问任何基于stdio的MCP服务器，使其与基于web的客户端和API网关等HTTP基础设施兼容。

概述

这 mcp-streamablehttp-proxy 作为一个翻译层：

• MCP客户端 使用StreamableHTTP（如Claude.ai，基于web的IDE）
• MCP服务器 只会说stdio JSON-RPC（就像官方的MCP服务器一样）

它管理会话，生成服务器子进程，并透明地处理协议转换。

特性

• 通用MCP服务器支持 -适用于任何基于stdio的MCP服务器
• 会话管理 -每个客户端都有一个独立的服务器子进程
• 完全协议支持 -处理完整的MCP生命周期
• 可配置的 -灵活的超时、主机和端口配置
• 生产就绪 -异步实现，并进行适当的清理
• 网关兼容 -设计用于Traefik和OAuth网关

安装

通过pip

pip install mcp-streamablehttp-proxy

通过 pixi

pixi add --pypi mcp-streamablehttp-proxy

用法

基本用法

# Proxy a Python MCP server module
mcp-streamablehttp-proxy python -m mcp_server_fetch

# Proxy an executable MCP server
mcp-streamablehttp-proxy /usr/local/bin/mcp-server-filesystem --root /data

# Proxy an npm-based MCP server
mcp-streamablehttp-proxy npx @modelcontextprotocol/server-memory

命令行选项

mcp-streamablehttp-proxy [OPTIONS]  [server_args...]

Options:
  --host TEXT         Host to bind to (default: 127.0.0.1)
  --port INTEGER      Port to bind to (default: 3000)
  --timeout INTEGER   Session timeout in seconds (default: 300)
  --log-level TEXT    Log level: debug/info/warning/error (default: info)
  --help             Show this message and exit

环境变量

• MCP_BIND_HOST -覆盖默认绑定主机
• MCP_PORT -覆盖默认端口
• LOG_FILE -启用文件记录到指定路径

运作原理

1. 客户端发送HTTP请求 向 /mcp 端点
2. 代理创建会话 首先 initialize 请求
3. 代理生成子流程 运行指定的MCP服务器
4. 代理翻译 HTTP和stdio协议之间
5. 客户端包含会话ID 在后续请求中
6. 会话超时 在一段时间不活动之后

API

端点

• POST/mcp -所有MCP协议消息的单一端点

标头

• Mcp会话Id -初始化后所有请求都需要
• 内容类型 -必须是 application/json

请求格式

标准JSON-RPC 2.0消息：

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  },
  "id": 1
}

响应格式

带有会话ID标头的JSON-RPC 2.0响应：

{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "serverInfo": {
      "name": "example-server",
      "version": "1.0.0"
    }
  },
  "id": 1
}

响应包括标题： Mcp-Session-Id:

例子

卷曲测试

# Start the proxy
mcp-streamablehttp-proxy python -m mcp_server_fetch

# Initialize session
SESSION_ID=$(curl -s -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05"},"id":1}' \
  -i | grep -i mcp-session-id | cut -d' ' -f2 | tr -d '\r')

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

Docker部署

FROM python:3.11-slim

RUN pip install mcp-streamablehttp-proxy mcp-server-fetch

# Bind to 0.0.0.0 for container networking
CMD ["mcp-streamablehttp-proxy", "--host", "0.0.0.0", "python", "-m", "mcp_server_fetch"]

使用Traefik编写Docker

services:
  mcp-fetch:
    build: .
    environment:
      - MCP_BIND_HOST=0.0.0.0
      - MCP_PORT=3000
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.mcp-fetch.rule=Host(`mcp-fetch.example.com`)"
      - "traefik.http.services.mcp-fetch.loadbalancer.server.port=3000"
      - "traefik.http.routers.mcp-fetch.middlewares=mcp-auth"
      - "traefik.http.middlewares.mcp-auth.forwardauth.address=http://auth:8000/verify"

会话管理

会话生命周期

1. 创造 -新会话创建于 initialize 请求
2. 活跃的 -会话通过请求保持活动状态
3. 超时 -会话在不活动后过期（默认值：300秒）
4. 清理 -子进程终止，资源释放

会话限制

• 每个会话一个子进程
• 会话彼此隔离
• 无内置会话限制（通过容器资源管理）

错误处理

常见错误

调试

启用调试日志记录：

mcp-streamablehttp-proxy --log-level debug python -m mcp_server_fetch

# Or with file logging
export LOG_FILE=/tmp/mcp-proxy.log
mcp-streamablehttp-proxy --log-level debug python -m mcp_server_fetch

性能注意事项

• 每个会话一个子进程 -相应地规划资源
• 30秒请求超时 -不适合长时间操作
• 异步I/O -处理会话内的并发请求
• 无请求排队 -并行处理的请求

对于高负载场景，请考虑：

• 在负载平衡器后面运行多个代理实例
• 根据使用模式调整会话超时
• 监控子流程资源使用情况

安全

⚠️ 此代理不提供身份验证或授权！

始终部署在像Traefik这样的身份验证反向代理后面：

• OAuth2/JWT身份验证
• 速率限制
• 访问控制
• HTTPS终止

切勿将代理直接暴露在互联网上！

与MCP OAuth网关集成

此代理旨在与MCP OAuth网关无缝协作：

1. 代理将MCP服务器暴露为HTTP端点
2. Traefik提供路由和身份验证
3. OAuth网关处理客户端注册和令牌
4. 客户端使用OAuth承载令牌访问MCP服务器

发展

运行测试

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with coverage
pytest --cov=mcp_streamablehttp_proxy tests/

类型检查

mypy src/

代码检查

ruff check src/
ruff format src/

故障排除

代理无法启动

• 验证MCP服务器命令是否正确
• 检查服务器是否已安装并处于PATH中
• 确保端口3000（或自定义端口）可用

会话立即超时

• 增加超时时间 --timeout 选项
• 检查服务器是否正在响应初始化
• 验证服务器stdout是行缓冲JSON

请求挂起

• 启用调试日志记录以查看通信
• 检查服务器是否实际响应
• 验证JSON-RPC请求格式

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

• 为 模型上下文协议
• 专为与HTTP基础设施集成而设计
• MCP OAuth网关生态系统的一部分