查看海报原图 · 放大阅读与扫码

【C++项目】官方 MCP SDK 还没有 C++？那就自己写一个

如果你想让 Codex、Cursor 这类 Agent 调起自己写的 C++ 程序，MCP 算得上是目前最规范、也最值得亲手走通的一条路。它把客户端如何发现工具、怎样传递参数、如何接收结果的标准定得很清楚，有了这层契约，我们原本写好的本地业务，就能顺理成章地接入 Agent 的工作流中。

去翻一下 MCP 官方的 SDK 列表就会发现，TypeScript、Python、C#、Go、Rust、Java 等语言都早早有了官方实现。但截至 2026 年 9 月 24 日，官方列出的 10 种 SDK 语言里，唯独还没有 C++。查看官方 SDK 列表

对 C++ 开发者来说，这恰恰是一个绝佳的实战切入点：既能保留现有的 C++ 业务代码，又能用 C++ 亲手实现一套标准的 MCP 服务端，最后交由真实的 Agent 来调用。无论是本地推理、图像处理、文件检索还是设备接口控制，都可以借由这个协议，从一个具体的操作开始稳步接入。

我们把整套实现梳理成了这个 MCP C++ Server SDK 实战项目。一共 21 篇图文教程，从第一条最基础的 JSON-RPC 请求讲起，一步步搭建出工具、资源、提示词管理、两套传输通道与请求控制机制，最后接入本地 ONNX 推理模块，让 Codex 真正调通你构建的服务。

做完这个项目，你最终拿出来演示的绝不是一段玩具脚本，而是一个实打实能跑的 C++ 服务：Agent 发起调用，服务在本地完成计算，结果实时流转回对话框。顺着这条链路深挖下去，SDK 的接口封装、多线程并发安全以及边界测试方法，也都能讲得清清楚楚。

注：文中所提“官方缺少 C++”仅指官方 SDK 清单现状；本项目为独立的教学与工程实现，不代表 MCP 官方立场。

先看效果：让 Codex 调用你写的识别工具

给 Codex 一个本地图片路径，让它去调用我们注册好的 recognize_mnist 工具。服务端的 C++ 逻辑读取文件后，通过 ONNX Runtime 完成推理，随后把预测数字、原始输入路径以及模型标识封装返回，Codex 拿到这些结构化数据后，再整合进对话中。

在下面这次真实调用中，服务准确返回了 digit: 7。整个过程既没有预先给模型投喂答案，也没有把图片当作视觉附件硬塞给大模型，真正的图片预处理和推理计算，完全是在本地的 C++ 服务进程内完成的。

你可以从 Agent 的最终回复，一路反向追溯到自己手写的工具回调函数。日志里清楚记录了工具发现过程、带有完整参数的 tools/call 请求，以及带有相同请求 ID 的响应包。你可以通过已知标签核对这张图片的预测是否正确，也能凭借完整的交互日志确认底层逻辑确实跑过了。

这两张截图取自 2026 年 9 月 22 日 Codex CLI 0.149.0 的实际运行日志（为了阅读体验，排版时做了一定的长路径与哈希折叠）；本地 MCP 服务使用 stdio 传输，握手协议版本为 2025-06-18。截图中出现的 HTTPS 回退属于 Codex 与远端模型服务之间的通信逻辑，后续任务依然平稳完成。

到了 M20，你会先构建识别服务、准备模型与已知标签的测试图片，再把本机可执行程序配置为 Codex 的 stdio MCP 服务。随后发起一次真实工具调用，核对请求参数和识别结果，并用错误输入检查服务能否继续处理下一次请求。这一整套链路跑通后，就有了可以向别人现场展示的项目成果。

亲手写 SDK，练的是哪些 C++ 能力

写业务代码和写基础库的感觉是截然不同的。这个项目会推着你站在“SDK 作者”的视角去推敲全局：业务端该如何以低成本注册？入参在什么时候校验才合理？业务回调究竟该由哪个线程触发？一旦外部发起取消，哪些对象必须继续保活才不会挂掉？

拿最基础的识别工具来说，SDK 负责解析底层协议帧、校验参数结构；具体业务负责加载文件并调用模型；等拿到结果后，还要核验一次输出契约。参数格式错误、图片文件损坏、返回字段缺失……这些异常应该分别由哪一层来拦截？你需要把这些权责切分得干干净净，抽象成合理的公共接口，这样别人接入新业务时才足够省心。

紧接着，两套不同的传输机制会进一步考验这套架构的设计弹性。在处理 stdio 时，你得妥善应对流式输入中的半包、黏包，以及多线程并发写回 stdout 时的同步问题；换到 Streamable HTTP，又得处理 /mcp 路由分发、SSE 响应流长连接、请求头与包体的一致性校验，还要兼容不同版本的会话策略。更关键的是，这两套差异巨大的传输层，底层必须无缝复用同一套业务调度核心。

在协议兼容性上，SDK 覆盖了 2026-07-28、2025-11-25 和 2025-06-18 三个主流版本。课程会带着你梳理清楚哪些协议逻辑可以通用、哪些细微差异必须做版本适配，确保同一份业务代码在面对不同版本的客户端时都能稳定运行。

到了工程交付阶段，我们还会把 SDK 打包成标准的 CMake 安装构件，让另一个完全独立的 C++ 项目通过 find_package 和 mcp::sdk 目标直接依赖使用。从公共头文件隔离、依赖项导出到跨模块生命周期管理，每一个细节都必须经得起下游工程的调用检验。

协议解析、现代 C++ 规范、多线程并发以及基础库的交付标准，在这一次次真实的接口调用中被牢牢串联在了一起。这些都不是空谈理论，每一条都有对应的代码实现与必须攻克的工程坑点。

工具之外，把业务数据交给 Agent

实际开发中，光有工具（Tools）往往不够。比如面对一份长篇报告分析任务，Agent 既要知道“读什么”，也要知道“按什么套路来分析”。在教程里，我们用一份具体的业务报告，把 MCP 规范里的三类核心能力全部落了地：

接口	报告示例	客户端拿到什么
Tools	set_report	执行“修改报告”这一动作后的操作状态与结果
Resources	report://current	当前最新报告的正文内容
Prompts	analyze_report	按照特定分析诉求组装好的一组预设提示词与上下文

客户端可以先读取报告正文，再按需调取分析提示词；当后台或工具修改了报告内容后，已注册的订阅链路会立刻收到变更事件，进而主动发起二次拉取。这样一来，通知机制只负责告知“内容有变”，具体的正文依然走资源接口获取。至于怎样搭配提示词、何时交由模型处理，决策权依然交还给客户端。

在此基础之上，教程还会进一步补全 URI 模板动态匹配、资源目录分页机制以及参数的自动补全功能。当业务资源暴增时该怎么准确定位、分页拉取时怎样杜绝漏项、客户端输入参数时如何智能提示候选值，都有落地的代码示范。

这部分逻辑完全不依赖复杂的本地模型或 GPU 环境，借助一个轻量级的测试客户端就能快速调试。你可以先从一个简明的业务数据结构做起，把服务端的协议特性一步步搭稳，再去对接真实的 Agent。

取消、断连、慢客户端：项目里值得深挖的难点

如果一个耗时很久的工具正在后台计算，上层的用户却突然点了“取消”，你的服务端能优雅停下来吗？

如果 I/O 读取线程被底层的慢速业务一直霸占着，客户端发来的取消通知根本连进来的机会都没有。要解决这个问题，就必须把业务移入异步调度流，并且要确保“先登记请求状态、后执行业务”，否则稍后到达的取消信号很可能连目标都搜寻不到。这看似平淡无奇的几行派发逻辑，背后卡着非常严格的线程执行序和状态机约束。

又比如，某个订阅了更新流的客户端突然卡顿或不读数据了，而后台的业务更新还在源源不断地产生，这时候内存该怎么防爆？

课程里会带你设计一个有界队列，把业务侧的通知派发和网络侧的真实发送拆开解耦。当队列积压打满时，关闭受影响的流通道；发送回调尚未返回时，请求名额仍可能被占用。再考虑到共享 stdio 场景下天然的阻塞特质，很多边界问题必须通过实机注入测试才能看得真切。光靠盲目堆砌线程或者把缓冲区无脑开大，是解决不了根本问题的。

类似的技术陷阱在服务正常下线时同样存在：当系统发出停止信号时，某个业务回调可能还在别的线程跑着。服务端本身以及回调所引用的资源，绝不能随随便便提前析构，必须稳妥等待所有在途任务安全退场。正在执行的同步推理无法被外层取消标记强制打断；服务端需要等待它自然返回，并在计算前后检查协作式取消状态。

此外，课程中还实现了一套实用的多轮交互机制。当某个工具发现入参不够、需要客户端补齐信息时，它会先返回一个补充输入的交互请求以及一份显式状态标识，结束当前轮次；等下一轮客户端把缺失信息补齐带回后，再重新恢复上下文继续执行。为了防止状态在客户端被篡改，我们还会使用 HMAC 来守护状态凭证的完整性，而具体权限与幂等校验则交由业务层兜底。

去跟面试官聊项目时，这些点往往就是最能展现工程内功的硬核素材。你完全可以直接运行测试脚本，现场模拟取消、超时、通道打满与客户端异常断连等极端场景，然后顺着代码解释互斥锁、任务队列、请求生命周期与对象安全销毁是如何咬合运作的。有了实际的实验支撑，面对深度追问时自然胸有成竹。

ONNX 收尾，把接入方法用到真实业务上

到了尾声阶段，我们用一个真实的计算型任务来检验此前沉淀下来的这套 SDK。这里采用 OpenCV 负责图像的前置解码与规整，选用 ONNX Runtime 承载模型的前向推理，而我们手写的 C++ 工具模块，就负责把整套处理流干净地桥接到 MCP 的体系中。

模型权重的完整性与有效性会在服务启动阶段统一做前置校验，而创建好的推理 Session 则由后续的所有请求长效复用。在单次识别链路里，代码会逐一检查图片路径合法性、文件体积与实际解码像素，严格走完灰度转换、28×28 缩放与归一化等预处理流程，最终将预测结果规范化输出。我们还会使用自动化脚本发起连续的恶意输入和合规请求交替轰炸，以此验证主服务进程在遭遇脏数据时是否依然稳如泰山。

走完这一遭，你就能完整体会一次把现实业务搬上 Agent 调度的标准流程：怎样划定工具职责、怎样严控入参契约、怎样管理底层重资源、怎样映射并返回友好错误，以及最后怎样在 Agent 端核对每一次调用的正确性。掌握了这套范式，日后想把它换成内部的文件检索引擎、实时报表生成服务或是工业通信协议，无非也就是依样画葫芦的事。

说明：该示例基于本地 CPU 推理，针对的是 MNIST 风格的手写数字识别。模型文件与测试图片需要自行准备，请务必核实数据源、商用权限以及预处理契约；课程本身不附带任何可直接分发的预训练权重包。前面的 SDK 核心与报告服务完全可以先独立开发，ONNX 相关依赖留到后半段按需配置即可。

21 篇图文课，最后交付一套自己的项目

整个实战的编排非常注重“循序渐进”。M00 会带你先整体跑通一次现成服务，对整体数据流有个宏观认知；紧接着从 M01 开始，便是一行一行拆解并手写 SDK 的各项细节。每一项新功能的加入都有具体的业务场景支撑，写每一段代码都有清晰的验证标准：

课程	学习内容	能完成什么
M00	跑通完整 MCP 服务	观察报告业务，并让 Codex 实际调用一次工具
M01–M04	工程入口、JSON-RPC、工具契约与版本适配	追踪一条请求如何进入回调、校验结果并返回
M05–M06	stdio 与 Streamable HTTP	用两种传输连接同一业务，处理消息和会话
M07–M11	资源、URI 模板、提示、分页与补全	向客户端提供可发现、可读取的业务上下文
M12–M16	进度、取消、订阅、容量与多轮交互	管理长请求与通知流，让缺少输入的工具分轮继续
M17	CMake 安装与独立消费	让另一个 C++ 工程通过公共接口使用 SDK
M18–M20	ONNX 适配、客户端接入与真实识别	构建业务工具，核对 Codex 的调用及计算结果

每一节课都配备了详尽的源码剖析、架构原理图、可直接复制的命令以及验证方案；对于有实际输出的位置，教程中也附带了运行结果节选。M19 集中讲解 Codex、Cursor 等客户端的配置对接和验证方法；本文展示的真实 Agent 调用证据来自 Codex CLI。

为了帮助大家把学到的技术真正转变成求职或项目面试里的筹码，相关的辅助资料也已经梳理停当：

学习安排按 21 个课程学习日加 4 个总结复盘日设计，每天都有具体的编码任务与完成标准。按每天投入 3～5 小时、每周学习 5 天计算，大约需要 5 周；前期会留出时间准备环境和巩固基础。

项目经历可以根据实际完成范围来写：如果你深入实现了 SDK，就重点说明协议处理、传输抽象与并发设计；如果你主要完成业务接入，就写清 ONNX 工具的输入校验、推理流程和真实客户端调用；如果只是跟着教程复现，就如实描述复现、测试和分析工作。配套的 36 道项目面试题围绕网络协议、并发控制、内存与生命周期管理，以及 Agent 接入展开，帮助你用自己真正做过的代码回答追问。

以后到了面试或项目答辩的场合，你大可以先把 Codex 调通识别工具的终端演示作为抓手，随后顺理成章地切入自己实现的 C++ 代码：解释核心模块的设计权衡、现场复现边界错误的处理链路，再聊聊向外拓展的思路。整个项目的含金量与代码细节，立刻就能立起来。

给想用 C++ 做 AI 工程的你

如果你已经系统学过了 C++ 的类、STL、智能指针以及 Lambda 表达式，正发愁如何把它们串联到一个结构完整的现代化服务端项目里；抑或是你本身就有 C++ 开发基础，想借着当前大火的 Agent 浪潮探探 AI Infra 和工具集成的门道，这个项目都会是一个扎实而聚焦的实践场。

建议开始前具备基础的 CMake、Git 以及终端操作经验，这样上手会更加平顺；涉及到多线程并发的细节，随着课程一步步遇到问题再针对性查漏补缺也完全来得及。当前教程的测试基准基于 macOS 环境，SDK 本身面向通用的 POSIX 系统设计。调用真实的 Codex 需要你有相应的账号与额度，相关的文本与识别数据会流经模型服务；如果是用于公网多租户场景，后续则需要额外补充认证鉴权和运维监控设施。

用地道的 C++ 写出一套规范的服务端，让真实的 Agent 调起来，并且把背后的每一个技术细节讲得明明白白。这便是这个项目自始至终想要带你达成的目标。

课程从 M00 的一次完整调用开始：先构建报告服务，再让 Codex 通过 stdio 发现并调用 set_report，观察请求如何进入 C++ 工具、结果怎样返回 Agent。看过这条链路，再从 M01 逐步拆开 SDK 的实现会更容易。如果你打算把它放进接下来的 C++ 进阶日程中，扫描下方二维码，联系程序喵即可了解具体的课程与训练营规划。