mcp-proxy与StreamableHTTP集成：新一代传输协议实战
项目地址: https://gitcode.com/gh_mirrors/mc/mcp-proxy mcp-proxy是一款强大的传输协议转换工具，能够实现stdio与SSE/StreamableHTTP之间的无缝桥接。本文将详细介绍如何通过mcp-proxy实现StreamableHTTP协议的集成与应用，帮助开发者轻松构建高效的跨协议通信系统。
什么是StreamableHTTP传输协议？
StreamableHTTP是一种基于HTTP的流式传输协议，专为实时数据交换设计。与传统的请求-响应模式不同，它支持持续的双向数据流传输，非常适合需要低延迟通信的场景。mcp-proxy通过src/mcp_proxy/streamablehttp_client.py模块提供了对该协议的完整支持。
mcp-proxy的核心功能与架构
mcp-proxy主要提供两种工作模式：
stdio到SSE/StreamableHTTP的转换
这种模式允许像Claude Desktop这样的客户端通过stdio与远程SSE/StreamableHTTP服务器通信，即使客户端本身不原生支持这些协议。
SSE/StreamableHTTP到stdio的转换
这种模式允许远程客户端通过SSE/StreamableHTTP协议连接到本地stdio服务器，实现远程访问本地服务的功能。
快速安装mcp-proxy的方法
使用PyPI安装（推荐）
# 使用uv安装（推荐）
uv tool install mcp-proxy
# 或者使用pipx安装
pipx install mcp-proxy
从源码安装
git clone https://gitcode.com/gh_mirrors/mc/mcp-proxy
cd mcp-proxy
uv install
使用Docker容器
docker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --help
StreamableHTTP客户端模式实战
基本用法
要将mcp-proxy配置为StreamableHTTP客户端模式，只需提供目标URL并指定传输类型：
mcp-proxy --transport streamablehttp http://localhost:8080/mcp
带认证的连接
如果服务器需要认证，可以使用以下命令：
mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' --transport streamablehttp http://localhost:8080/mcp
或者使用OAuth2认证：
mcp-proxy --client-id CLIENT_ID --client-secret CLIENT_SECRET --token-url https://auth.example.com/token --transport streamablehttp http://localhost:8080/mcp
Claude Desktop配置示例
对于Claude Desktop，可在配置文件中添加以下内容：
{
"mcpServers": {
"mcp-proxy": {
"command": "mcp-proxy",
"args": [
"--transport", "streamablehttp",
"http://example.io/mcp"
],
"env": {
"API_ACCESS_TOKEN": "your-access-token"
}
}
}
}
StreamableHTTP服务器模式实战
基本用法
要将mcp-proxy配置为StreamableHTTP服务器模式，监听特定端口并连接到本地stdio服务器：
mcp-proxy --port=8080 --transport streamablehttp uvx mcp-server-fetch
高级配置
启用CORS支持
mcp-proxy --port=8080 --allow-origin='*' --transport streamablehttp uvx mcp-server-fetch
自定义暴露头信息
mcp-proxy --port=8080 --allow-origin='*' --expose-header Custom-Header --transport streamablehttp uvx mcp-server-fetch
命名服务器配置
可以定义多个命名服务器，通过不同路径访问：
mcp-proxy --port=8080 --named-server fetch 'uvx mcp-server-fetch' --named-server github 'npx @modelcontextprotocol/server-github' --transport streamablehttp
或者使用配置文件config_example.json：
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"transportType": "stdio"
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
},
"transportType": "stdio"
}
}
}
然后使用以下命令启动：
mcp-proxy --port=8080 --named-server-config config_example.json --transport streamablehttp
测试StreamableHTTP集成
可以使用以下步骤测试mcp-proxy的StreamableHTTP集成：
- 启动带StreamableHTTP支持的mcp-proxy服务器：
mcp-proxy --port=8080 --transport streamablehttp uvx mcp-server-fetch &
- 使用另一个mcp-proxy实例作为客户端连接：
mcp-proxy --transport streamablehttp http://127.0.0.1:8080/mcp
- 通过MCP Inspector工具发送测试请求，验证数据流是否正常传输。
常见问题与解决方案
问题：连接远程StreamableHTTP服务器时出现SSL错误
解决方案：使用--no-verify-ssl选项禁用SSL验证（仅在测试环境中使用）：
mcp-proxy --no-verify-ssl --transport streamablehttp https://server.local/mcp
问题：Claude Desktop无法启动mcp-proxy，日志中出现ENOENT错误
解决方案：使用完整路径指定mcp-proxy可执行文件：
{
"mcpServers": {
"mcp-proxy": {
"command": "/full/path/to/bin/mcp-proxy",
"args": ["--transport", "streamablehttp", "http://localhost:8932/mcp"]
}
}
}
问题：Docker容器中运行时出现" No interpreter found "错误
解决方案：添加--pass-environment参数传递环境变量：
docker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --pass-environment --port=8096 --transport streamablehttp uvx mcp-server-fetch
总结
mcp-proxy提供了StreamableHTTP协议与stdio之间的无缝桥接，使开发者能够轻松构建跨协议的通信系统。通过本文介绍的方法，您可以快速实现StreamableHTTP协议的集成，为您的应用程序带来高效、低延迟的实时数据传输能力。无论是将本地服务暴露为StreamableHTTP接口，还是让不支持StreamableHTTP的客户端能够与远程服务器通信，mcp-proxy都是一个强大而灵活的工具选择。
想要了解更多细节，可以查看项目源代码，特别是src/mcp_proxy/streamablehttp_client.py和src/mcp_proxy/mcp_server.py文件。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
