Agent Protocol 之 MCP C++ 客户端完全指南:Streamable HTTP 与 stdio 双传输模式调用技巧

原创2026-09-22 14:59:091,981 阅读
文章标签:人工智能AI Agent服务注册发现认证鉴权后端

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 生态服务。

登录后查看全文
agent-protocol