Agent Protocol 之 MCP C++ 客户端完全指南:Streamable HTTP 与 stdio 双传输模式调用技巧
Agent Protocol 之 MCP C++ 客户端完全指南:Streamable HTTP 与 stdio 双传输模式调用技巧
openJiuwen agent-protocol 的 MCP C++ SDK 提供了完整的 MCP 客户端实现,支持 Streamable HTTP 与 stdio 双传输模式,让你用 C++ 一行工厂调用即可连接任意 MCP 服务器、调用 Tool / Resource / Prompt。本文面向新手,带你从零完成环境准备、客户端创建、握手与工具调用,并深入讲解两种传输模式的选择技巧与高频坑点。
📦 先搞清楚:MCP 客户端能做什么?
MCP(Model Context Protocol)客户端负责与 MCP 服务器建立会话,核心能力包括:
| 能力 | 常用 API | 说明 |
|---|---|---|
| 握手与连通 | Initialize() / SendPing() |
建立会话、获取服务端能力 |
| 工具调用 | ListTools() / CallTool() |
列出并调用服务端注册的 Tool |
| 资源读写 | ListResources() / ReadResource() |
读取服务端提供的数据源 |
| Prompt 模板 | ListPrompts() / GetPrompt() |
获取并渲染提示词模板 |
| 反向交互 | SetSamplingCreateMessageCallback 等 |
响应服务端发起的采样、征询请求 |
所有 RPC 方法统一返回 std::future,通过 future.get() 阻塞取结果——这套"工厂 + future"的异步模型是 MCP C++ 客户端最核心的设计,源码见 mcp_client.h。
🧰 环境准备:三步完成依赖安装
SDK 要求 C++17 编译器 + CMake ≥ 3.15,运行依赖 OpenSSL、libcurl、libevent、nlohmann_json。各发行版安装命令的完整对照表见 docs/dependencies.md。
推荐在 MCP/cpp-sdk 目录下执行一键脚本(自动检测发行版并安装开发包):
cd MCP/cpp-sdk
bash scripts/install_deps.sh # 安装 OpenSSL、libcurl 开发包
随后编译 SDK:
bash scripts/build.sh # 产物:output/lib/libmcp.so
💡
install_deps.sh只装 OpenSSL 与 libcurl 开发包,编译器与 CMake 需要自行安装;nlohmann_json 优先用系统包,缺失时会自动拉取到third_party/。详见 scripts/install_deps.sh 与 README.md。
⚡ Streamable HTTP 模式:连接远程 MCP 服务器
Streamable HTTP 是基于 HTTP 长连接的传输方式,适合连接远程或常驻的 MCP 服务器,还支持鉴权与 TLS,是最常用的模式。
创建客户端的四步流程
第一步:定义客户端身份。 ClientConfig 只有名称与版本两个字段,默认值即可使用。
第二步:配置传输参数。 关键配置项 StreamableHttpClientConfig 中:
| 字段 | 作用 | 建议值 |
|---|---|---|
endpoint |
MCP HTTP 端点 URL | 如 http://127.0.0.1:8000/mcp |
timeout |
HTTP 请求超时 | 默认 30000ms |
sseTimeout |
SSE 流超时 | 长连接场景适当调大 |
headers |
附加 HTTP 头 | 自定义网关鉴权等 |
tlsConfig |
TLS 证书与校验 | 生产环境启用 |
第三步:通过工厂创建客户端。 第三个参数可选传入 AuthProvider 实现鉴权:
Mcp::ClientConfig config;
config.name = "MyClient";
config.version = "1.0.0";
Mcp::StreamableHttpClientConfig httpConfig;
httpConfig.endpoint = "http://127.0.0.1:8000/mcp";
auto client = Mcp::McpClientFactory::CreateStreamableHttpClient(
config, httpConfig, nullptr /* 可选 AuthProvider */);
第四步:握手。 调用 Initialize() 并完成 JSON-RPC 握手后才能发起其他请求:
auto initResult = client->Initialize().get(); // 阻塞等待握手完成
完整可运行示例见 tool_example.cpp,其中演示了 Initialize → SendPing → 分页 ListTools → CallTool 的完整链路。
调用 Tool:从列出到执行
CallTool 的参数是 JSON 字符串,可用 nlohmann::json 组装后 dump():
nlohmann::json arguments;
arguments["user_query"] = "Shenzhen weather";
auto callFuture = client->CallTool("echo", arguments.dump(), 30);
auto callResult = callFuture.get();
// 遍历 callResult->content 读取 TextContent / ImageContent 等
长耗时工具可传入第 4 个参数——进度回调,服务端每推进一点就会触发你的回调函数实现,无需轮询。
🐚 stdio 模式:驱动本地 MCP 服务器进程
stdio 传输通过标准输入/输出管道与本地子进程通信:SDK 自动 fork 出目标服务器进程,把 JSON-RPC 消息按行分帧写入其 stdin、从其 stdout 读取响应。适合服务器就是本机可执行程序的场景(例如 python my_mcp_server.py --stdio)。
配置只有三项:command(可执行文件路径)、args(参数列表)、env(环境变量):
Mcp::StdioClientConfig stdioConfig;
stdioConfig.command = "/path/to/mcp-server";
stdioConfig.args = {"--stdio"};
auto client = Mcp::McpClientFactory::CreateStdioClient(config, stdioConfig);
创建之后的 Initialize()、ListTools()、CallTool() 等调用方式与 HTTP 模式完全一致——这就是双传输模式的妙处:传输层可互换,业务代码零改动。
子进程生命周期由 SDK 托管(见 stdio_transport.h 中的 StartSubprocess / StopSubprocess),CloseGracefully() 会先停子进程再释放资源,你无需手动杀进程。
🎯 双传输模式怎么选?一张表说清
| 维度 | Streamable HTTP | stdio |
|---|---|---|
| 适用场景 | 远程服务器、微服务部署 | 本机命令行服务器 |
| 网络开销 | 有(可走 TLS 加密) | 无(进程内管道) |
| 鉴权支持 | 支持 AuthProvider(如 Bearer Token) |
无(信任本地进程) |
| 服务器生命周期 | 独立常驻,多客户端可复用 | 随客户端启动/停止 |
| 典型延迟 | 网络 RTT | 极低 |
选择口诀:服务器在别的机器上、需要鉴权 → Streamable HTTP;服务器是你自己代码起的本地进程、追求启动快 → stdio。
⚠️ 新手必知的 3 个高频坑点
坑 1:stdio 模式下日志污染协议通道。 SDK 默认把诊断日志打到 stdout,而 stdio 模式下 stdout 就是协议通道,日志会直接打断 JSON-RPC 消息。解决办法:stdio 客户端创建后立刻用 SetLogCallback(mcp_log.h)把日志重定向到 stderr 或文件。
坑 2:回调要在 Initialize 之前注册。 SetSamplingCreateMessageCallback、SetListRootsCallback 等回调决定握手时对外宣告的能力,必须在 Initialize() 之前注册,否则服务端看不到对应能力。
坑 3:未初始化就调用 RPC 会抛异常。 所有 RPC 方法在 Initialize() 之前调用会抛 std::runtime_error;服务端的 JSON-RPC 错误则在 future.get() 时以 Mcp::MCPError 抛出。建议对关键调用先用 future.wait_for(...) 做超时保护,再取结果。错误语义的完整说明见 docs/errors.md。
🚀 上手示例:跑通官方 Demo
仓库自带全套示例,位于 MCP/cpp-sdk/example/ 目录。首次验证推荐一键模式(自动后台起 Server 并依次跑全部 Client):
cd MCP/cpp-sdk
sh scripts/run_example.sh # 或 -t all:起 Server 后依次跑 Client
也可以双终端反复调试:
# 终端 1:前台常驻 Server(默认 http://127.0.0.1:8000/mcp)
sh scripts/run_example.sh -t server
# 终端 2:连接 Server 跑 Tool 客户端
sh scripts/run_example.sh -t tool
换端口只需加参数:sh scripts/run_example.sh -p 9000 -t all。各客户端示例分工清晰:Tool / Prompt / Resource / Sampling 分别位于 example/client_example/ 下的对应子目录,说明文档见 example/client_example/README.md。
📚 延伸学习路径
| 主题 | 资料位置 |
|---|---|
| 客户端 API 全表 | docs/api/client.md |
| 协议方法与 SDK API 对照 | docs/api/protocol-mapping.md |
| 服务端开发(注册 Tool/Prompt/Resource) | docs/api/server.md |
| 错误处理与 CallTool 双路径 | docs/errors.md |
| 日志级别与回调配置 | docs/logging.md |
| 单元测试与覆盖率 | docs/testing.md |
✅ 总结
MCP C++ 客户端的调用套路可以浓缩为一句话:选工厂(CreateStreamableHttpClient 或 CreateStdioClient)→ 注册回调 → Initialize() 握手 → future.get() 拿结果 → CloseGracefully() 收尾。记住两个核心决策点:按部署形态选传输模式、stdio 场景务必重定向日志,你就能用这套 SDK 快速接入任何 MCP 生态服务。