项目已经有一个查文档的函数。接进第一个助手时，需要写工具说明和调用逻辑；换到另一个应用，可能又要适配一遍。MCP 为这类连接提供共同协议，让客户端能发现服务提供的能力，再按约定调用。

执行任务的循环仍由应用组织。模型提出工具请求以后，程序决定是否执行，MCP 客户端负责与服务通信，服务返回真实结果。这几个职责分别看清，接入出了问题才容易定位。

顺着一次查询走一遍

以 search_project_docs 为例，服务声明工具名称、说明和输入 schema。客户端取得这些定义，把适合提供给模型的工具注册进去。

模型决定查询开发指南时，Agent 程序先验证这次调用，再通过客户端发给服务。服务搜索资料，返回片段与来源。应用把结果放回当前任务，模型才能继续回答。

MCP 还可以提供资源和提示模板。这里先只讨论工具，因为知识库助手当前需要的是可调用的检索能力。完整能力边界可以查看 MCP 架构文档。

先说明本文使用的协议范围

原教程通过初始化、能力发现和调用来解释 MCP。协议会演进，本文用 2025-11-25 版规范说明这条连接过程。真实项目应采用客户端与 SDK 支持的兼容版本，不要把这里的版本号视作始终最新。

按这版规范，客户端先发出 initialize，协商协议版本和能力；服务回应后，客户端发送初始化完成通知，再进入正常操作。生命周期规范 给出了具体消息要求。

随后可以通过 tools/list 读取工具定义，用 tools/call 请求执行。下面只展示一个调用请求。

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "search_project_docs",
    "arguments": { "query": "本地启动命令" }
  }
}

带 ID 的请求需要用对应 ID 返回响应。通知没有 ID，不要求响应。这里只是消息片段，正式实现还需要处理连接生命周期、错误、取消及协商能力，不能把它直接当成完整服务。

stdio 和 HTTP 各自怎样工作

stdio 方式通常由客户端启动子进程，通过标准输入输出交换协议消息。工具服务的普通调试日志应写到标准错误，避免混进协议通道。

Streamable HTTP 则连接一个正在运行的 HTTP 服务，也可以连接本机地址。它与 stdio 的差别在传输方式。身份认证、请求头和连接管理要按所用 SDK 处理。对应版本的传输规范 解释了两者要求。

先单独连一次服务，确认能列出工具、能用固定参数取得结果，再交给模型。这会把“连接失败”和“模型没有选对工具”分开。

如果服务能列出工具，却调用失败，先看参数 schema 和服务端错误。固定调用已经成功，模型仍没使用它，再检查工具说明是否清楚，以及本轮是否真的需要这个能力。

适配器减少了哪些工作

原教程通过 LangChain 的 MCP 适配器，把服务工具转换成 Agent 能使用的工具。调用侧可以继续使用同一套执行循环，工具的实现则由独立服务维护。

文件系统服务可以替换代码助手中手写的列目录和文件读取。自己的检查命令工具也可以继续保留。两种来源的能力可以放在同一个助手里，前提是输入输出与权限边界都明确。

短任务结束后，客户端要按 SDK 的方式释放连接和子进程。长期服务则需要处理连接复用、异常断开和重新发现。是否能重复调用，也要由实际行为验证。

连通以后，权限仍要看整体

文件服务限制在一个目录中，另一个任意命令工具却可能读取目录之外的内容。评估实际访问范围时，需要检查 Agent 的全部工具，以及这些工具进程拥有的系统权限。

工具描述也只是能力说明。读取敏感资料或修改文件时，服务端仍应校验用户、资源范围和业务条件。

这一篇的练习可以很小。先把只读文档搜索封成服务，用固定问题直接调用；记录返回的正文、来源和错误。然后接入助手，再用同一个问题询问。两份结果放在一起，能看清连接和模型使用之间多了哪些步骤。

延伸阅读

本篇依据冴羽《AI Agent 开发实战》学习整理稿中的 MCP 连接与手写协议章节重写，并核对上述版本规范。原教程见 MCP 工具接入 和 从零理解 MCP。

上一篇 · 系列目录 · 下一篇