Session 12: MCP — wiring a hand-built agent to standardised capabilities

Research Agent 要完成一份研究报告,通常需要访问搜索引擎、网页、文件、数据库,或者企业内部系统。

Originally in ChineseThis article was written in Chinese. The body below is the Chinese original; the English translation is not available yet.

一、MCP 解决什么问题

Research Agent 要完成一份研究报告,通常需要访问搜索引擎、网页、文件、数据库,或者企业内部系统。最直接的做法,是给每个外部服务单独写一套接入代码:定义参数、调用接口、处理返回值,再把结果整理成模型能理解的格式。

当接入的工具越来越多时,代码里会出现大量相似但不兼容的适配逻辑。换一个模型框架,或者想把同一套能力提供给另一个 Agent,往往又要做一遍集成。

MCP(Model Context Protocol)试图把这部分连接工作标准化。它约定了客户端与外部能力服务之间如何发现能力、交换参数和返回结果。Agent 应用可以用统一方式连接不同的 MCP Server,而每个 Server 可以封装搜索、文件系统、数据库或其他服务。

MCP 本身不会替 Agent 做规划,也不会自动保证工具结果正确。它主要解决的是外部能力如何被发现、描述和调用的问题。

二、MCP 的三个角色

MCP 常见的架构包含三个角色:

  • Host:用户实际使用的 AI 应用,例如一个 Agent 客户端或 IDE。Host 负责管理模型交互、会话和权限等。
  • MCP Client:运行在 Host 内部,负责与某个 MCP Server 建立连接,并按协议交换消息。
  • MCP Server:向外提供一组能力,例如搜索资料、查询数据库或读取文件。

一个 Host 可以管理多个 Client,每个 Client 通常连接一个 Server。模型并不一定直接连接 MCP Server;常见做法是 Host 把 Server 暴露的工具描述转换成模型 API 所需要的工具格式,再由 Host 根据模型返回的 tool call 发起实际调用。

三、MCP 暴露哪些能力

MCP 的常见能力可以分为三类。


能力 用途 Research Agent 示例


Tools 执行一个动作,通常由模型决定何时调用 搜索网页、查询数据库、读取文件

Resources 暴露可读取的数据或上下文 某份研究资料、项目文档、数据库中的只读内容

Prompts 提供可复用的提示模板 研究报告模板、资料分析模板

其中 Tools 最容易和现有 Agent 的 tool calling 对接。Resources 和 Prompts 也有价值,但是否使用取决于客户端和业务设计。MCP Server 可以提供这些能力中的一部分,不要求每个 Server 都实现全部功能。

需要注意,MCP 中的 Tool 与模型 API 中的 tool calling 不是同一个层次。模型 API 的 tool calling 描述模型如何提出一次工具调用;MCP 描述应用如何连接到一个提供工具的外部服务。Agent 应用经常需要把两者桥接起来。

四、一次 MCP 工具调用发生了什么

以 Research Agent 搜索资料为例,整体过程大致如下:

  1. Agent 应用启动,并连接搜索类 MCP Server。
  2. MCP Client 向 Server 查询可用工具及其输入参数结构。
  3. Host 把这些工具转换成模型 API 支持的工具定义,和用户的研究主题一起发送给模型。
  4. 模型返回一个工具调用请求,例如调用 search_web,参数是关键词。
  5. Host 根据工具名称找到对应的 MCP Client,并向 Server 发起调用。
  6. Server 执行搜索,将结果返回给 Client。
  7. Host 把工具结果作为后续消息交给模型。
  8. 模型继续分析资料,可能再发起工具调用,也可能生成报告。

这条链路里有两层协议边界:模型和 Host 之间使用模型供应商定义的 API;Host 和 MCP Server 之间使用 MCP。Host 负责把它们连接起来。

MCP 基于 JSON-RPC 风格的消息交换。工具发现与工具调用通常涉及 tools/list 和 tools/call 等方法。实际开发时,消息的完整结构、传输方式以及 SDK 接口应以当前所用 MCP SDK 版本的官方文档为准。

五、用 Python 写一个 MCP Server

下面用 Python 展示一个最小化的 Server 结构。MCP Python SDK 的接口会随版本变化,项目落地时应先确认安装版本,并对照该版本官方示例调整导入方式和启动入口。

python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("research-tools")


@mcp.tool()
def search_research_materials(query: str, limit: int = 5) -> list[dict]:
    """Search research materials by keyword."""
    # 示例数据:实际项目中可以替换为搜索 API、搜索引擎或内部知识库。
    materials = [
        {
            "title": "Agent system architecture",
            "url": "https://example.com/agent-architecture",
            "snippet": "An overview of agent runtime and tool orchestration.",
        },
        {
            "title": "Evaluation of LLM applications",
            "url": "https://example.com/llm-evaluation",
            "snippet": "Methods for evaluating model-based applications.",
        },
    ]

    query_lower = query.lower()
    matched = [
        item for item in materials
        if query_lower in item["title"].lower()
        or query_lower in item["snippet"].lower()
    ]
    return matched[:limit]


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

这个例子展示了关键结构:创建 Server、声明一个工具、定义工具参数和返回值,再启动服务。搜索逻辑只是示例数据过滤,真正的业务实现还需要考虑超时、外部 API 错误、结果数量限制和数据校验。

Server 端的工具定义通常会包含名称、描述以及输入参数 schema。描述会影响 Host 如何呈现这个工具,也可能被转换后提供给模型,因此应写清楚工具适合什么场景、参数代表什么、结果包含什么。

六、Agent 应用如何接入 MCP 工具

接入 MCP 后,Agent 仍然需要处理模型消息、工具调用循环和状态。MCP 不会替代这些逻辑。

可以把桥接过程拆成几个职责:

  • 启动或连接 MCP Client。
  • 获取 Server 提供的工具定义。
  • 把工具定义转换成当前模型 API 的格式。
  • 解析模型返回的 tool call。
  • 根据工具名称路由到对应 MCP Client。
  • 把执行结果转成模型可继续处理的消息。
  • 处理调用失败、超时、权限拒绝和 Server 断开等情况。

示意代码如下。这里用抽象接口表达桥接逻辑,避免把特定 SDK 版本的客户端方法误当成通用 API:

python
def convert_mcp_tool_to_model_tool(mcp_tool: dict) -> dict:
    """将 MCP 工具描述转换为模型 API 所需的工具定义。"""
    return {
        "type": "function",
        "function": {
            "name": mcp_tool["name"],
            "description": mcp_tool.get("description", ""),
            "parameters": mcp_tool["inputSchema"],
        },
    }


async def dispatch_tool_call(tool_call, mcp_clients):
    """根据模型提出的工具调用,路由到对应 MCP Client。"""
    tool_name = tool_call.name
    arguments = tool_call.arguments

    client = find_client_for_tool(tool_name, mcp_clients)
    if client is None:
        raise ValueError(f"Unknown tool: {tool_name}")

    # call_tool 是伪代码;实际调用方式取决于所用 MCP SDK 版本。
    return await client.call_tool(tool_name, arguments)

其中 find_client_for_tool 需要维护工具名到 MCP Client 的映射。真实项目里还应考虑重名工具:两个 Server 都提供 search 时,单独用工具名称可能不够,需要在内部使用稳定的工具 ID 或命名空间。

如果使用 LangGraph,可以把 MCP 调用封装成工具节点或普通业务节点,再由图控制后续流程。MCP 负责外部能力连接,LangGraph 负责状态流转、分支、循环和 checkpoint,两者解决的是不同问题。

七、MCP 接入后的工程问题

1. 工具数量和上下文

连接的 Server 越多,发现的工具也可能越多。把所有工具定义始终塞进每一次模型请求,会增加上下文开销,也可能让模型难以选择合适的工具。

可以根据当前任务筛选工具,或者先检索工具目录,再把少量候选工具提供给模型。工具描述也要控制长度,避免把大量实现细节写进描述中。

2. 失败处理

MCP Server 可能超时、崩溃、返回错误,或者与 Host 断开连接。应用需要定义超时、有限重试、降级和错误返回策略。重试前要确认操作是否安全;对于写入或有副作用的工具,不能不加区分地重复执行。

错误信息可以交给模型尝试调整参数或选择替代工具,但程序仍应限制重试次数和总执行时间。模型不应拥有无限重试的权限。

3. 权限与安全

MCP Server 能接触什么数据、执行什么动作,取决于它的实现和运行权限。接入文件系统、数据库或外部服务时,应限制可访问范围,验证参数,并对高风险操作增加审批。

工具返回的网页内容和文件内容都属于外部数据,可能包含恶意指令。不能因为它们经由 MCP 返回,就把内容当成可信指令。Agent 仍需区分系统指令、用户请求和外部资料。

4. 连接生命周期与可观测性

生产环境需要明确 Server 的启动、关闭、健康检查、连接恢复和版本管理策略。日志中至少应能关联用户请求、工具名称、目标 Server、执行时长、错误类型和调用结果摘要。敏感参数与返回内容要按数据安全要求脱敏。

5. MCP 不会自动解决业务语义

两个 Server 即使都符合 MCP 协议,返回数据的含义也可能不同。比如一个搜索工具返回标题、摘要和 URL,另一个返回原始网页片段;Agent 仍然需要理解字段、处理重复结果、判断来源质量,并维护研究证据。

标准化连接接口,能减少集成成本,但不会替代业务层的数据模型和质量控制。

八、MCP、Tool、Skill 和 Workflow 的关系


概念 主要解决的问题 Research Agent 中的例子


Tool Agent 能执行什么操作 搜索网页、查询数据库

MCP 外部能力如何以标准协议连接和发现 通过 MCP Server 接入搜索服务

Skill 一类任务应该按什么方法完成 研究资料筛选、证据核验、报告结构

Workflow 任务步骤如何被控制和编排 搜索、分析、证据检查、补充搜索、生成报告

它们可以同时出现在一个系统里。例如,Research Agent 使用 Skill 规定研究方法,使用 Workflow 控制主要步骤,通过 MCP 连接搜索服务,并把搜索动作作为 Tool 暴露给模型。

九、我的理解

MCP 最有价值的地方,是把外部能力接入的接口约定下来。应用不必为每个外部服务都重新设计一套完全不同的调用方式,Server 也能把能力提供给多个兼容的 Host。

但从 Agent 工程的角度看,MCP 只是工具接入层的一部分。工具选择、执行策略、状态管理、失败恢复、权限控制和结果质量,仍然需要应用自己设计。协议解决了连接方式,系统能否可靠完成任务,还要看协议之上的工程实现。

希望这篇文章能对你有所帮助。关注我,持续分享更多实用、好用的 AI 干货。

On this page