Agent-10-03.MCP协议与Server开发

系列：00 索引 · 上一篇：02 Tool Calling · 下一篇：04 配置驱动 Agent

---

1. 行业常见问题

现象	痛点
每个 Host（Cursor、Claude、自研）各写一套 tool 适配	重复劳动
工具逻辑与 Agent 代码耦合	无法独立测试、无法复用
本地脚本 vs 远程 API 混用	权限边界不清
升级工具破坏所有 Agent	缺版本化与契约

段末注释：MCP（Model Context Protocol，模型上下文协议）由 Anthropic 等推动，用于 Host 与 Tool/Resource Server 的标准通信。

---

2. 该技术如何解决

MCP 把「能力提供方」独立为 Server 进程/服务，Host 通过标准握手发现 tools / resources / prompts，以 JSON-RPC 风格调用。

好处：

• 一次实现，多 Host 复用
• 进程隔离（stdio 子进程或 HTTP 服务）
• 权限在 Server 侧集中（如只允许读某目录）

---

3. 核心原理

3.1 传输

传输	场景
stdio	本地 IDE 拉起子进程，简单、安全边界清晰
Streamable HTTP	远程共享、需鉴权（Bearer/OAuth）
SSE（旧）	逐步被 Streamable HTTP 取代

3.2 生命周期（简化）

Host 启动 Server → initialize → tools/list → tools/call → （可选 resources/read）

HTTP 模式需 会话（如 initialize 后带 session id）

3.3 Server 职责边界

• 做：参数校验、IO、返回结构化结果、错误码
• 不做：多 Agent 编排、长对话记忆（除非显式提供 resource）

---

4. 典型实现与代码示例

本仓库 MCP 采用 FastMCP 写 Server，StdioMcpClient（MCP Python SDK）作 Host，经 AgentRuntime._tool_impls() 接入 run_tool_loop。

4.1 Server：mcp/mcp_rag_gene/server.py（FastMCP）

from mcp.server.fastmcp import FastMCP
from rag.store import GeneRagStore

mcp = FastMCP("rag-gene", instructions="基因文献混合检索。")
_store = GeneRagStore()

@mcp.tool()
def query_hybrid(query: str, top_k: int = 5) -> dict:
    """混合检索：BM25 + 向量，返回 chunks 与 citation。"""
    return _store.query_hybrid(query, top_k=top_k)

if __name__ == "__main__":
    mcp.run(transport="stdio")

同类 Server：mcp_rag_methods（GraphRAG）、mcp_argo_sirna（Argo 作业）、mcp_ncbi、mcp_literature。

4.2 Host：agent/uni/mcp_client/stdio.py

# MCP tools/list → OpenAI function schema
def _mcp_tool_to_openai_schema(tool: dict) -> dict:
    return {"type": "function", "function": {"name": tool["name"], ...}}

# tools/call 经 MCP session 远程执行
async def call_tool(self, name: str, arguments: dict) -> Any:
    return await self._session.call_tool(name, arguments=arguments)

AgentRuntime 在启动时 StdioMcpClient.connect()，把返回的 tool_impls() 注入 ReAct 循环（见 Agent-10-02）。

4.3 工程验收

# 单独测 MCP Server（stdio，可用 MCP Inspector 或 Agent CLI）
uv run python mcp/mcp_rag_gene/server.py

# Literature Agent 经 MCP 调 query_hybrid
uv run python -m agent.literature.cli ingest-samples
uv run python -m agent.literature.cli chat --mock-llm "用 query_hybrid 查 BRCA1 转录本"

agent.yaml 中 mcp.servers 声明 command/args，Runtime 按配置拉起子进程。

---

5. 替代方案与优缺点

方案	优点	缺点
MCP	跨 Host 标准、社区工具多	较新，HTTP 鉴权需自建
OpenAPI + 自研 tool 包装	与 REST 生态一体	每个 Host 仍要适配
LangChain Tool 仅进程内	开发快	难跨进程/跨语言复用
gRPC 微服务	性能、类型强	Agent 侧集成成本高
直接 subprocess/bash	极简	安全与可移植性差

---

6. 自检题

1. stdio 与 HTTP MCP 分别适合什么部署形态？
2. 为什么 Tool 的 docstring 会出现在 MCP tools/list 里？
3. 远程 MCP 401 与 400 Missing session 分别说明什么？

---

7. 延伸阅读

• modelcontextprotocol.io
• Python SDK
• 下一篇：Agent-10-04 配置驱动 Agent 与人格 Skills