mcp-webapi-bridge

MCP (Model Context Protocol) Streamable HTTP bridge. Connects stdio-based MCP clients to remote MCP servers via HTTP POST — using the Streamable HTTP transport (protocol 2025-11-25).

安装

全局安装

npm install -g mcp-webapi-bridge

本地安装

npm install mcp-webapi-bridge

使用方法

作为命令行工具

mcp-webapi-bridge <targetUrl> [token] [api_key]

作为本地依赖

npx mcp-webapi-bridge <targetUrl> [token] [api_key]

参数说明

• <targetUrl> 必填：MCP 服务器的目标 URL，例如 http://127.0.0.1:7001/mcp/task/168f2f91-150b-4480-b0f6-5166f4896245
• [token] 非必需：可选的认证令牌，如 Bearer your-token
• [api_key] 非必需：可选的 API 密钥

IDE 中的 MCP 配置

不需要 npm install，直接使用 npx：

{
  "mcpServers": {
    "law-search-server": {
      "command": "npx",
      "args": [
        "mcp-webapi-bridge",
        "http://127.0.0.1:7001/mcp/task/168f2f91-150b-4480-b0f6-5166f4896245"
      ],
      "env": {
        "Authorization": "Bearer your-token",
        "ApiKey": "your-api-key"
      }
    }
  }
}

示例

# 基本用法
mcp-webapi-bridge http://127.0.0.1:7001/mcp/task/xxx

# 带认证令牌
mcp-webapi-bridge http://127.0.0.1:7001/mcp/task/xxx "Bearer your-token"

# 带 API 密钥
mcp-webapi-bridge http://127.0.0.1:7001/mcp/task/xxx "Bearer your-token" "your-api-key"

# 使用环境变量
MCP_TARGET_URL=http://127.0.0.1:7001/mcp/task/xxx Authorization="Bearer your-token" ApiKey="your-key" mcp-webapi-bridge

功能特性

• 使用 Streamable HTTP 传输协议（单端点请求/响应）
• 从 stdin 读取 JSON-RPC 消息，通过 HTTP POST 转发到 MCP 服务器
• 支持 JSON 和 SSE（text/event-stream）响应格式
• 将服务器响应写入 stdout 供 MCP 客户端读取
• 支持 Authorization 和 ApiKey 认证头

工作原理

1. 工具启动后，从 stdin 读取 MCP 客户端发送的 JSON-RPC 消息（换行符分隔）
2. 每收到一条消息，通过 HTTP POST 发送到目标 URL
3. 服务器以 JSON 或 SSE 流形式返回响应
4. 将响应写入 stdout，MCP 客户端读取并解析

故障排除

常见问题

1. Error: targetUrl is required

   • 原因：未提供目标 URL
   • 解决：提供 MCP 服务器的 URL 作为命令行参数或设置环境变量

2. HTTP error

   • 原因：无法连接到 MCP 服务器
   • 解决：检查目标 URL 是否正确，服务器是否运行，网络连接是否正常

3. Request timeout

   • 原因：服务器响应超时（60 秒）
   • 解决：检查服务器端任务执行是否耗时过长

日志

工具会将连接状态、错误信息等输出到 stderr，便于调试。

注意事项

• 使用 Streamable HTTP 协议（单端点），无需 SSE 长连接
• 每个请求独立，天然支持多 Worker 负载均衡
• 请确保提供的 token 具有足够的权限访问 MCP 服务器

许可证

MIT License