1. 项目概述：当大模型Agent学会“使用工具”

最近在折腾大模型应用开发的朋友，估计都绕不开一个词： Agent 。简单来说，Agent就是让大模型从一个“聊天高手”变成一个能“动手做事”的智能体。它不仅能理解你的指令，还能规划步骤、调用工具去执行任务，比如帮你查天气、订机票、分析数据，甚至写代码。但要让Agent真正“能干”，光靠大模型本身的“脑力”是不够的，它需要一双“手”——这就是 工具（Tools） 。

而 MCP（Model Context Protocol） ，正是为这双“手”和“大脑”之间建立高效、标准化连接的一套“神经协议”。你可以把它想象成电脑主板上的PCIe插槽标准。没有这个标准，每个工具（显卡、声卡）都得自己搞一套驱动和接口，混乱且低效。有了MCP，工具开发者可以遵循统一的协议来“制造”工具，Agent开发者则可以像“即插即用”一样，轻松地将各种工具集成到自己的Agent系统中。

所以，“为Agent添加MCP工具”这个项目，核心就是 打通大模型智能体与外部能力之间的标准化通道 。无论你是想做一个能自动处理邮件的个人助手，还是一个能调用专业软件进行设计的AI工程师，通过MCP，你都可以将现成的、或自己开发的工具，安全、规范地“装配”到你的Agent上，极大地扩展其能力边界。这不仅是当前AI应用落地的关键技术路径，也是每一个AI应用开发者必须掌握的实战技能。

2. 核心概念拆解：Agent、工具与MCP协议

在动手之前，我们必须把几个核心概念及其之间的关系彻底理清。这就像组装一台精密仪器，你得先认识每一个零件。

2.1 大模型Agent：从“思考者”到“执行者”

传统的对话大模型，是一个优秀的“思考者”和“信息重组者”。你问它“今天天气如何？”，它能基于训练数据，生成一段关于天气的、语法通顺的描述。但它仅限于“说”，无法“做”——它不能真的去调用一个天气API获取实时数据。

Agent的出现改变了这一点。一个典型的Agent架构包含几个核心模块：

  • 规划模块 ：将复杂任务分解为可执行的子步骤。例如，任务“帮我总结最近三篇关于AI的论文并制作PPT”，会被分解为：搜索论文、下载全文、总结内容、生成大纲、调用PPT生成工具。
  • 记忆模块 ：保存对话历史、工具调用结果和任务上下文，确保Agent有“连续记忆”。
  • 工具调用模块 ：这是最关键的部分，负责根据规划，选择并执行正确的工具。
  • 反思模块 ：评估工具执行结果，判断任务是否完成，或是否需要调整策略。

Agent的本质是 赋予大模型行动力 。而行动力，直接取决于其可调用的工具库是否丰富、强大。

2.2 工具（Tools）：Agent的“瑞士军刀”

工具，就是Agent可以调用的外部函数或服务。它可以是：

  • 一个API接口 ：如获取天气、查询股票、发送邮件。
  • 一个本地函数 ：如读写本地文件、执行一个Python脚本、操作数据库。
  • 一个专业软件接口 ：如通过代码控制Photoshop进行图片处理，或连接CAD软件进行图纸修改。

在没有标准协议之前，为Agent添加工具是个“脏活累活”。你需要：

  1. 为每个工具编写特定的调用封装代码。
  2. 在Agent的提示词（Prompt）中，以特定格式（如JSON Schema）手动描述这个工具的功能、参数。
  3. 处理每个工具独特的认证、错误返回格式。

当工具数量增多时，这套方法变得极其臃肿且难以维护。

2.3 MCP协议：工具生态的“通用插座”

MCP协议的核心思想是 标准化 。它定义了一套工具应该如何向Agent描述自己、如何被调用、如何返回结果的统一规范。

MCP的核心组件：

  • MCP Server（工具端） ：任何工具，只要按照MCP协议实现一个Server，就成为了一个“MCP工具”。这个Server负责向外界宣告：“我这里有哪些工具（函数）可用，每个工具需要什么参数”。当被调用时，它执行具体逻辑并返回结果。
  • MCP Client（Agent端） ：集成在Agent框架中的客户端。它的职责是发现、连接一个或多个MCP Server，获取工具列表，并按照协议格式转发调用请求。

MCP带来的核心好处：

  1. 即插即用 ：Agent开发者无需关心工具的内部实现。只要工具提供了MCP Server，Agent就能通过标准方式发现并使用它。
  2. 动态扩展 ：工具可以独立开发、部署。Agent在运行时可以动态加载新的MCP Server，能力得到实时扩展。
  3. 安全隔离 ：工具运行在独立的Server进程中，与Agent主进程隔离。即使某个工具崩溃，也不会直接影响Agent核心。
  4. 生态繁荣 ：开发者可以专注于开发好用的工具（MCP Server），而AI应用开发者则可以像从应用商店选择App一样，轻松挑选工具集成到自己的Agent中。

理解了这三者的关系，我们就能明白，为Agent添加MCP工具，本质上就是 让我们的Agent（MCP Client）学会与一个或多个MCP Server通信，并将其提供的工具纳入自己的“技能列表” 。

3. 实战准备：环境、框架与工具选型

理论清晰后，我们进入实战环节。首先需要搭建我们的“工作台”。

3.1 开发环境与基础依赖

我推荐使用Python作为开发语言，这是目前AI领域最主流的生态。确保你的环境已安装Python 3.9+。

# 创建一个干净的虚拟环境是个好习惯
python -m venv mcp-agent-env
source mcp-agent-env/bin/activate  # Linux/macOS
# 或 mcp-agent-env\Scripts\activate  # Windows

# 安装核心依赖
pip install openai  # 或其他大模型SDK，如anthropic, litellm
pip install mcp  # 这是MCP协议的Python SDK，由协议制定方提供，是核心

注意 ： mcp 库是核心，但它可能处于快速迭代中。建议关注其官方GitHub仓库，以获取最新的稳定版本和文档。

3.2 Agent框架的选择

你需要一个支持工具调用的Agent框架。这里有几个主流选择，各有优劣：

框架名称 特点 适合场景 MCP集成难度
LangChain 生态最丰富，组件齐全，文档多。但抽象层次高，有时显得臃肿。 快速构建复杂、生产级的AI应用。 有官方和社区支持，集成相对容易。
LlamaIndex 最初专注于RAG，现已扩展为全功能Agent框架。对数据查询和结构化输出非常友好。 需要与大量文档、数据库交互的Agent。 支持MCP，集成流程清晰。
AutoGen 微软出品，专注于多Agent协作。框架设计优雅，但学习曲线稍陡。 构建需要多个Agent分工协作的复杂系统。 需要自行适配MCP Client，灵活性高但需更多工作。
Semantic Kernel 微软出品，与.NET生态结合紧密，但Python支持也已完善。强调“插件”概念，与MCP思想天然契合。 企业级应用，或与微软技术栈深度集成。 插件体系与MCP易于对接。
直接使用SDK 直接使用OpenAI/Anthropic等提供的Assistant API或Function Calling。 轻量级、定制化需求高的场景。 需要手动实现MCP Client到SDK的桥接，自由度最高。

我的选择与理由 ：对于本次演示和大多数入门及中级场景，我推荐 LangChain 。原因有三：第一，其 Tool 抽象与MCP的 Tool 概念几乎一一对应，集成直观；第二，社区活跃，遇到问题容易找到解决方案；第三，它屏蔽了底层大模型供应商的差异，方便我们切换不同的模型。我们将以LangChain为例进行后续演示。

pip install langchain langchain-openai

3.3 首个MCP工具的选择：一个简单的计算器

为了聚焦于集成过程本身，我们首先选择一个最简单的MCP工具——一个计算器。这个工具不依赖外部API，逻辑简单，能让我们清晰地看到从Server部署到Client调用的全链路。

我们将手动实现这个计算器MCP Server。在真实项目中，你可以直接使用社区已经开发好的MCP Server，比如：

  • tavily-mcp ：集成Tavily搜索API。
  • brave-search-mcp ：集成Brave搜索。
  • 文件系统操作、数据库查询等通用工具 。

实操心得 ：在项目初期，建议从最简单的自制工具开始。这能帮你彻底理解MCP数据流动的每一个环节，后续集成复杂第三方工具时，排查问题会更有方向。

4. 手把手实现：构建你的第一个MCP工具Server

现在，我们来创建这个计算器工具的MCP Server。

4.1 创建MCP Server项目结构

创建一个新的项目目录，例如 mcp-calculator-server 。

mcp-calculator-server/
├── server.py      # MCP Server 主程序
├── requirements.txt
└── README.md

requirements.txt 内容：

mcp>=0.1.0

4.2 编写MCP Server代码

在 server.py 中，我们实现一个支持加、减、乘、除的计算器。

# server.py
import asyncio
from typing import Any
from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationOptions
import mcp.server.stdio
from mcp.shared.models import Tool, TextContent

# 创建Server实例
server = Server("calculator-server")

# 1. 定义工具：加法
@server.list_tools()
async def handle_list_tools() -> list[Tool]:
    """向客户端声明本Server提供的所有工具"""
    return [
        Tool(
            name="add",
            description="Add two numbers together.",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number", "description": "The first number"},
                    "b": {"type": "number", "description": "The second number"},
                },
                "required": ["a", "b"]
            }
        ),
        Tool(
            name="subtract",
            description="Subtract the second number from the first.",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number", "description": "The minuend"},
                    "b": {"type": "number", "description": "The subtrahend"},
                },
                "required": ["a", "b"]
            }
        ),
        Tool(
            name="multiply",
            description="Multiply two numbers.",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number", "description": "The first factor"},
                    "b": {"type": "number", "description": "The second factor"},
                },
                "required": ["a", "b"]
            }
        ),
        Tool(
            name="divide",
            description="Divide the first number by the second.",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number", "description": "The dividend"},
                    "b": {"type": "number", "description": "The divisor (must not be zero)"},
                },
                "required": ["a", "b"]
            }
        ),
    ]

# 2. 实现工具调用处理函数
@server.call_tool()
async def handle_call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
    """执行具体的工具调用"""
    try:
        if name == "add":
            result = arguments["a"] + arguments["b"]
        elif name == "subtract":
            result = arguments["a"] - arguments["b"]
        elif name == "multiply":
            result = arguments["a"] * arguments["b"]
        elif name == "divide":
            if arguments["b"] == 0:
                return [TextContent(type="text", text="Error: Division by zero.")]
            result = arguments["a"] / arguments["b"]
        else:
            return [TextContent(type="text", text=f"Error: Unknown tool '{name}'.")]

        return [TextContent(type="text", text=str(result))]
    except KeyError as e:
        return [TextContent(type="text", text=f"Error: Missing argument {e}.")]
    except Exception as e:
        return [TextContent(type="text", text=f"Error: {str(e)}.")]

# 3. Server主循环
async def main():
    """运行Server，使用标准输入输出作为传输层"""
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="calculator",
                server_version="0.1.0",
                capabilities=server.get_capabilities(
                    notification_options=NotificationOptions(),
                    experimental_capabilities={},
                ),
            ),
        )

if __name__ == "__main__":
    asyncio.run(main())

代码关键点解析：

  1. @server.list_tools() : 这个装饰器下的函数，用于响应Client的“列出所有工具”请求。返回的是一个 Tool 对象列表，每个对象定义了工具的名称、描述和输入参数JSON Schema。 这是Agent理解工具功能的唯一依据 ，描述务必清晰准确。
  2. @server.call_tool() : 这个装饰器下的函数，是工具的实际执行逻辑。它接收工具名 name 和参数字典 arguments ，执行计算后，必须返回一个 TextContent 列表。MCP也支持返回图像等内容，但文本是最通用的。
  3. stdio_server() : 这里我们使用标准输入/输出作为通信通道。这是MCP支持的最简单的传输方式，适合本地调试。在生产中，可能会使用SSE或WebSocket。

4.3 运行与测试MCP Server

在终端中运行这个Server：

python server.py

运行后，程序会挂起，等待标准输入。这表明你的MCP Server已经启动，并准备接受来自MCP Client的连接和指令。你可以先保持它运行，我们接下来在Agent端连接它。

注意事项 ：MCP协议通信是双向的、持续的。不要以为启动Server后没输出就是错了。它正在安静地等待Client通过stdin发送过来的JSON-RPC请求。

5. 核心集成：在LangChain Agent中接入MCP工具

现在，我们切换到Agent项目，将刚刚启动的计算器MCP Server集成进去。

5.1 创建LangChain Agent项目

在另一个终端（或另一个项目目录），创建Agent环境。

# 激活之前创建的虚拟环境
source mcp-agent-env/bin/activate
# 确保已安装 langchain, langchain-openai, mcp

5.2 编写MCP Client连接代码

我们需要编写一个脚本，作为LangChain和MCP Server之间的桥梁。这个脚本的核心是使用 mcp 库的Client功能，发现MCP Server的工具，并将其转换为LangChain能识别的 Tool 对象。

创建一个文件 mcp_client_bridge.py ：

# mcp_client_bridge.py
import asyncio
from typing import List
from langchain.tools import Tool
from mcp import ClientSession, StdioServerParameters
from mcp.client import stdio

async def load_mcp_tools(server_command: List[str]) -> List[Tool]:
    """
    连接指定的MCP Server，并将其提供的所有工具转换为LangChain Tool列表。
    
    Args:
        server_command: 启动MCP Server的命令列表，如 ["python", "/path/to/server.py"]
    
    Returns:
        List[Tool]: LangChain可用的工具列表
    """
    tools = []
    
    # 1. 配置Server连接参数（使用标准输入输出）
    server_params = StdioServerParameters(command=server_command[0], args=server_command[1:])
    
    # 2. 创建Client会话并连接
    async with stdio.stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # 3. 初始化会话
            await session.initialize()
            
            # 4. 请求Server列出所有可用工具
            listed_tools = await session.list_tools()
            
            # 5. 为每个MCP工具创建一个LangChain Tool包装器
            for mcp_tool in listed_tools.tools:
                langchain_tool = Tool(
                    name=mcp_tool.name,
                    description=mcp_tool.description or f"A tool named {mcp_tool.name}",
                    # 这里定义LangChain Tool的执行函数
                    func=self._create_tool_func(session, mcp_tool.name),
                    # 提供参数schema，有助于Agent更好地理解和使用
                    args_schema=self._create_args_schema(mcp_tool)
                )
                tools.append(langchain_tool)
    
    return tools

    def _create_tool_func(session: ClientSession, tool_name: str):
        """创建一个异步函数，用于调用指定的MCP工具"""
        async def func(**kwargs):
            # 调用MCP Server的call_tool方法
            result = await session.call_tool(tool_name, arguments=kwargs)
            # 假设返回的是TextContent，拼接所有文本
            text_result = ""
            for content in result.content:
                if content.type == "text":
                    text_result += content.text + "\n"
            return text_result.strip()
        return func

    def _create_args_schema(self, mcp_tool):
        """根据MCP Tool的inputSchema创建Pydantic模型（简化示例）"""
        # 这是一个简化版。在实际中，你可能需要根据JSON Schema动态生成Pydantic模型。
        # 这里我们返回None，LangChain会使用函数签名推断。
        return None

5.3 构建并运行集成了MCP工具的Agent

现在，我们编写主Agent脚本，使用OpenAI的模型，并集成我们刚刚桥接过来的计算器工具。

创建一个文件 run_agent_with_mcp.py ：

# run_agent_with_mcp.py
import asyncio
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from mcp_client_bridge import load_mcp_tools  # 导入我们写的桥接函数

async def main():
    # 0. 设置OpenAI API Key (请替换成你的)
    import os
    os.environ["OPENAI_API_KEY"] = "your-api-key-here"
    
    # 1. 加载MCP工具
    # 指定你的计算器Server路径
    server_cmd = ["python", "/绝对路径/to/your/mcp-calculator-server/server.py"]
    print("正在连接MCP Server并加载工具...")
    mcp_tools = await load_mcp_tools(server_cmd)
    print(f"成功加载 {len(mcp_tools)} 个MCP工具: {[t.name for t in mcp_tools]}")
    
    # 2. 初始化大模型（使用支持Function Calling的模型）
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    
    # 3. 定义Agent的提示词模板
    prompt = ChatPromptTemplate.from_messages([
        ("system", "你是一个乐于助人的助手，可以调用工具来帮助用户解决问题。当你需要计算时，请使用计算器工具。"),
        ("user", "{input}"),
        MessagesPlaceholder(variable_name="agent_scratchpad"), # 用于存放工具调用历史
    ])
    
    # 4. 创建Agent
    agent = create_openai_tools_agent(llm, mcp_tools, prompt)
    
    # 5. 创建Agent执行器
    agent_executor = AgentExecutor(agent=agent, tools=mcp_tools, verbose=True)
    
    # 6. 运行一个示例查询
    print("\n--- Agent开始执行 ---")
    result = await agent_executor.ainvoke({"input": "请计算一下 (15.5 加上 27.3) 乘以 2 等于多少？"})
    print(f"\n最终结果: {result['output']}")
    
    # 再试一个复杂点的
    print("\n--- 第二个查询 ---")
    result2 = await agent_executor.ainvoke({"input": "我有一个数字100，先减去35，再除以得到的结果的平方根是多少？请分步计算并告诉我每一步的结果。"})
    print(f"\n最终结果: {result2['output']}")

if __name__ == "__main__":
    asyncio.run(main())

运行这个Agent：

  1. 确保你的计算器MCP Server ( server.py ) 正在运行。
  2. 在 run_agent_with_mcp.py 中正确设置 server_cmd 的路径和你的OpenAI API Key。
  3. 运行Agent脚本： 
    python run_agent_with_mcp.py

如果一切顺利，你将看到类似以下的输出（verbose模式）：

正在连接MCP Server并加载工具...
成功加载 4 个MCP工具: ['add', 'subtract', 'multiply', 'divide']

--- Agent开始执行 ---
> 进入新的Agent执行链...
思考：用户要求计算 (15.5 + 27.3) * 2。我需要先计算加法，再计算乘法。
行动：调用工具 `add` 计算 15.5 + 27.3
观察：42.8
思考：得到了和42.8，现在需要乘以2。
行动：调用工具 `multiply` 计算 42.8 * 2
观察：85.6
思考：计算完成。
最终结果: (15.5 加上 27.3) 乘以 2 等于 85.6。

恭喜！你的Agent已经成功通过MCP协议，调用了外部工具来完成数学计算。

6. 进阶集成：连接社区MCP工具（以Tavily搜索为例）

连接自制工具只是第一步。MCP的强大在于庞大的社区工具生态。让我们以集成一个真实的网络搜索工具 tavily-mcp 为例。

6.1 安装并运行Tavily MCP Server

首先，你需要一个Tavily的API Key（可在其官网免费注册获取）。

# 安装 tavily-mcp
pip install tavily-mcp

# 设置API Key环境变量
export TAVILY_API_KEY="your-tavily-api-key"

# 运行Tavily MCP Server
# 它默认会启动一个SSE服务器，我们可以用stdio模式连接
python -m tavily_mcp.server

运行后，这个Server会在后台启动。但为了像之前一样通过stdio连接，我们更常用的是通过 mcp CLI来桥接。社区通常提供更便捷的方式。

更通用的方法：使用 mcp CLI 连接任意Server 许多MCP Server设计为通过 stdio 或 sse 运行。我们可以使用官方 mcp 包提供的CLI工具来发现和管理它们。假设 tavily-mcp 可以通过一个命令启动stdio服务：

# 假设 tavily-mcp 提供了这样的启动方式（请查阅其具体文档）
python -m tavily_mcp.cli stdio

6.2 修改桥接代码以支持多Server

我们的 load_mcp_tools 函数可以很容易地扩展为连接多个Server。我们修改Agent主脚本，同时加载计算器和搜索工具。

# run_agent_with_multiple_mcp.py
import asyncio
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from mcp_client_bridge import load_mcp_tools

async def main():
    os.environ["OPENAI_API_KEY"] = "your-api-key"
    os.environ["TAVILY_API_KEY"] = "your-tavily-key"
    
    all_tools = []
    
    # 加载计算器工具
    calculator_cmd = ["python", "/path/to/calculator/server.py"]
    print("连接计算器Server...")
    calculator_tools = await load_mcp_tools(calculator_cmd)
    all_tools.extend(calculator_tools)
    
    # 加载Tavily搜索工具
    # 注意：这里需要根据tavily-mcp的实际启动命令调整
    # 例如，它可能是一个独立的可执行文件，或者需要用`python -m`启动
    tavily_cmd = ["python", "-m", "tavily_mcp.cli", "stdio"] # 假设命令如此
    print("连接Tavily搜索Server...")
    try:
        tavily_tools = await load_mcp_tools(tavily_cmd)
        all_tools.extend(tavily_tools)
        print(f"成功加载搜索工具: {[t.name for t in tavily_tools]}")
    except Exception as e:
        print(f"连接Tavily Server失败，可能命令不对或未安装: {e}")
        # 作为备选，我们可以直接使用LangChain内置的Tavily工具
        from langchain_community.tools.tavily_search import TavilySearchResults
        search_tool = TavilySearchResults()
        all_tools.append(search_tool)
        print("已使用备选的LangChain Tavily工具。")
    
    print(f"总计加载 {len(all_tools)} 个工具.")
    
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    prompt = ChatPromptTemplate.from_messages([
        ("system", "你是一个强大的助手，可以计算，也可以上网搜索最新信息。请根据问题合理选择工具。"),
        ("user", "{input}"),
        MessagesPlaceholder(variable_name="agent_scratchpad"),
    ])
    
    agent = create_openai_tools_agent(llm, all_tools, prompt)
    agent_executor = AgentExecutor(agent=agent, tools=all_tools, verbose=True, handle_parsing_errors=True)
    
    # 测试混合任务
    queries = [
        "请搜索一下‘LangChain’的最新版本是什么，然后告诉我这个版本号乘以10是多少？",
        "今天北京天气怎么样？如果气温是25摄氏度，相当于多少华氏度？（请先搜索天气，再计算）"
    ]
    
    for query in queries:
        print(f"\n=== 查询: {query} ===")
        result = await agent_executor.ainvoke({"input": query})
        print(f"答案: {result['output'][:500]}...") # 截断长输出

if __name__ == "__main__":
    asyncio.run(main())

这个Agent现在具备了 计算 和 联网搜索 两种能力，并且它能自主决定何时使用哪种工具。例如，对于第一个查询，它会先调用搜索工具获取“LangChain最新版本号”（比如是 0.1.0 ），然后调用计算器的乘法工具计算 0.1.0 * 10 。当然，这里版本号不是数字会出错，但这展示了Agent的规划能力。

实操心得 ：集成社区工具时，第一步永远是仔细阅读其文档，了解正确的启动方式和参数。很多MCP Server项目在GitHub上会提供清晰的 README 。如果stdio模式连接失败，可以尝试查看Server是否支持SSE，并使用 mcp install <server-name> 等方式安装和运行。

7. 避坑指南与效能优化

在实际集成MCP工具的过程中，你会遇到各种问题。以下是我踩过坑后总结出的核心要点。

7.1 常见问题与排查清单

问题现象 可能原因 排查步骤
Agent无法识别MCP工具 1. MCP Server未启动或启动失败。
2. server_cmd 命令或路径错误。
3. MCP Client和Server协议版本不兼容。		 1. 单独运行 server.py ，看是否有报错。
2. 检查 server_cmd 是否为有效的可执行命令。
3. 确保 mcp 库版本在Client和Server端尽量一致。
工具调用超时或无响应 1. 工具执行本身耗时过长（如网络请求）。
2. Agent等待响应的超时时间设置太短。
3. MCP Server进程卡死。		 1. 在MCP Server实现中添加超时和日志。
2. 在LangChain的 AgentExecutor 中调整 max_execution_time 参数。
3. 检查Server进程状态和资源占用。
参数传递错误 1. Agent生成的参数格式与MCP Tool定义的 inputSchema 不匹配。
2. 参数类型错误（如字符串传给了数字类型）。		 1. 在 handle_call_tool 函数开头打印 arguments ，检查收到的数据。
2. 确保 inputSchema 定义精确，利用 type 和 description 约束。
大模型不调用工具 1. 工具描述 ( description ) 不够清晰，模型不理解何时使用。
2. 系统提示词 ( system prompt ) 未鼓励或指导模型使用工具。
3. 模型能力不足。		 1. 优化工具描述，包含明确的关键词和使用场景。
2. 在系统提示词中明确告知模型“你可以使用以下工具：...”。
3. 尝试更换更强大的模型（如gpt-4-turbo）。
MCP连接意外断开 1. Server进程异常退出。
2. 网络波动（对于SSE/WebSocket连接）。		 1. 在Client端增加重连机制。
2. 实现心跳检测，断线后自动重启Server或重连。

7.2 性能与安全优化建议

  1. 连接池与长连接 ：对于需要频繁调用的工具，不要每次调用都新建连接。应该在Agent初始化时建立与MCP Server的长连接，并在整个生命周期内复用。我们的示例中 ClientSession 的上下文管理器已经实现了这一点。
  2. 工具权限管控 ：不是所有工具都应对Agent无条件开放。特别是删除文件、发送邮件、执行系统命令等高危工具。应在MCP Server端实现权限校验，例如检查调用来源、要求附加令牌、或对操作进行二次确认。
  3. 结果缓存 ：对于耗时较长或结果变化不频繁的工具（如某些数据查询），可以在MCP Client或Server端实现缓存机制，避免重复计算和网络请求。
  4. 结构化输出 ：让工具返回结构化的JSON数据，而不仅仅是文本。这样Agent可以更容易地提取其中的字段进行后续推理。MCP协议支持 TextContent 和 ImageContent ，未来可能会支持更丰富的类型。目前可以在 TextContent 中返回JSON字符串。
  5. 异步并发调用 ：如果一个任务可以并行调用多个独立工具，LangChain的某些Agent类型（如 Plan-and-Execute ）支持并发工具调用，可以显著提升效率。确保你的MCP Server和Client代码是异步友好的。

7.3 调试技巧：深入MCP协议层

当问题棘手时，你需要查看原始的MCP协议通信数据。可以在启动MCP Client时启用调试日志。

import logging
# 设置MCP库的日志级别为DEBUG
logging.basicConfig(level=logging.DEBUG)

这会在控制台打印出所有在Client和Server之间传递的JSON-RPC请求和响应，对于诊断协议级别的错误（如字段缺失、格式错误）至关重要。

8. 项目扩展与展望

成功集成基础工具后，你的AI Agent已经具备了“动手”的潜力。接下来，你可以从以下几个方向深化：

1. 构建私有工具库 将公司内部系统（CRM、ERP、数据库、内部API）封装成MCP Server。这是Agent在企业场景落地的关键一步。例如，一个 Salesforce MCP Server 可以让Agent帮你查询客户信息；一个 Jira MCP Server 可以让Agent创建或更新任务。

2. 探索复杂Agent框架 尝试更高级的Agent框架，如 AutoGen 或 CrewAI 。这些框架专注于多Agent协作，你可以为不同角色的Agent配备不同的MCP工具集。例如，一个“研究员”Agent配备搜索和论文总结工具，一个“分析师”Agent配备数据查询和可视化工具，让它们协作完成一份市场报告。

3. 实现工具的动态发现与加载 实现一个“工具管理中心”，Agent在运行时可以查询一个注册中心，发现新的MCP Server并动态加载其工具，无需重启Agent服务。这需要更复杂的MCP Client实现和工具管理逻辑。

4. 关注MCP协议发展 MCP协议本身在快速演进中，关注其官方仓库，了解新特性，如更好的资源管理、流式响应、工具调用链追踪等。这将帮助你构建更健壮、功能更强大的Agent系统。

为Agent添加MCP工具，不是一个一次性的集成动作，而是为你的大模型应用打开了一扇通往无限可能的大门。从今天这个简单的计算器开始，一步步将现实世界的能力接入你的数字智能体，这才是AI应用开发中最令人兴奋的部分。

Logo
亚马逊云科技技术品牌专区

更多推荐

cover

我做了一个 AI 原生安全测试 Skill：让 Claude Code/Cursor 直接进入安全工程模式

avatar 亚马逊云科技技术品牌专区

2026年AI编程工具排行榜：10款主流产品深度横评，谁才是真正的提效之王

三个月实测10款AI编程工具，从代码生成质量、Agent能力、过程可控性、性价比、IDE兼容性五个维度打分排名。文心快码以SPEC规范驱动+Multi-Agent矩阵在可控性上拉满，附完整对比表和选型建议。

avatar 亚马逊云科技技术品牌专区
cover

深入理解 AI Agent · MCP 子系列 #02：MCP Server 开发实战—从工具注册到无状态新规范

avatar 亚马逊云科技技术品牌专区