如果你正在开发或使用 AI 智能体可能会遇到一个核心矛盾智能体需要访问外部工具和数据如数据库、API、文件系统来完成任务但直接将这些能力硬编码到智能体内部会导致它变得臃肿、难以维护且每次更新工具链都需要重新训练或部署整个智能体。这不仅仅是代码层面的问题更是工程架构的瓶颈。最近一个名为Model Context Protocol (MCP)的协议开始受到关注它提出了一种“无状态更新”的思路试图从根本上改变我们为 AI 智能体构建基础设施的方式。但 MCP 到底是什么它宣称的“无状态”又如何能扩展我们的智能体基础设施更重要的是作为一个开发者我该如何上手并利用它来解决实际问题本文将深入拆解 MCP 协议特别是其“无状态更新”的核心设计。我不会只停留在概念介绍而是会带你理解为什么传统的“有状态”工具集成方式是智能体规模化应用的绊脚石MCP 如何通过 Server/Client 分离和资源声明机制来解耦工具与智能体以及你如何通过一个具体的代码示例快速搭建一个 MCP Server 来扩展智能体的能力。无论你是 AI 应用工程师还是对智能体架构感兴趣的开发者这篇文章都将提供从原理到实践的完整路径。1. 智能体工具集成的困境为什么我们需要 MCP在深入 MCP 之前我们必须先看清它要解决什么问题。当前让 AI 智能体如基于 OpenAI Assistants API、LangChain Agent 或自定义 LLM 应用使用外部工具主流做法可以概括为两种硬编码集成在智能体的提示词Prompt或代码中直接定义工具的函数签名、描述和调用逻辑。例如直接写死一个search_web(query)的函数调用。框架封装使用 LangChain、LlamaIndex 等框架它们提供了大量的“Tool”抽象你需要将这些工具注册到你的智能体实例中。这两种方式都存在一个共同的本质问题强耦合与有状态。强耦合工具的能力、接口和智能体的核心推理逻辑绑定在一起。想新增一个操作数据库的工具你必须修改智能体的源代码或配置并重新部署。有状态智能体“拥有”这些工具。工具的变更如 API 端点更新、新增参数会直接影响到智能体的行为甚至可能因为一个工具的错误导致整个智能体不可用。当你的智能体只需要3-5个工具时这或许可以接受。但想象一下智能体平台化的场景你希望为不同部门、不同场景的智能体动态提供数十种工具——代码执行、SQL查询、Jira操作、内部CRM API、文件解析等等。传统的“有状态”集成方式会迅速变得难以管理成为开发和运维的噩梦。MCP (Model Context Protocol) 的核心价值就在于它试图将智能体Client和工具/数据源Server解耦。它定义了一套标准的通信协议让智能体可以在运行时动态发现、理解并调用外部服务提供的能力而无需在编译时或启动时就固化这些依赖。这就是“无状态更新”的精髓智能体本身不维护工具的状态工具能力的增、删、改可以通过更新独立的 MCP Server 来实现而智能体客户端几乎无需变动。2. MCP 核心概念协议、服务器、客户端与无状态2.1 什么是 Model Context Protocol (MCP)MCP 是一个开放协议用于在 AI 应用程序客户端和外部资源服务器之间建立标准化的通信。你可以把它想象成智能体世界的“USB 协议”。USB 设备MCP Server提供具体能力如U盘文件读写、键盘输入、打印机输出。每个设备都遵循 USB 标准告诉主机“我能做什么”。USB 主机MCP Client需要能力的计算机。它通过标准协议枚举、识别设备然后调用设备的功能。协议MCP规定了设备如何向主机宣告自己的能力toolsresources以及主机如何向设备发送指令、接收数据。在这个类比中智能体Client就是主机它不需要事先知道世界上有多少种 USB 设备。它只需要支持 USB 协议就能在插入新设备启动新的 MCP Server时立刻识别并使用其功能。设备的更新换代无状态更新不会影响主机本身。2.2 MCP 的核心组件MCP Server服务器角色能力提供者。它可以是任何进程封装了对特定工具、数据源或系统的访问逻辑。职责启动后向客户端宣告自己提供了哪些“工具”tools和“资源”resources。工具代表可执行的操作如run_query资源代表可读取的数据如file:///path/to/data.json。示例一个sqlite-mcp-server可以提供execute_sql工具一个filesystem-mcp-server可以提供read_file、list_directory工具和文件资源。MCP Client客户端角色能力消费者。通常是 AI 智能体应用程序或框架。职责连接到 MCP Server获取其提供的工具和资源列表。当智能体需要完成某项任务时客户端根据当前对话上下文选择合适的工具并调用它然后将结果返回给智能体。示例Claude Desktop、Cursor IDE、以及任何集成了 MCP 客户端库的 AI 应用。Transport传输层角色定义 Client 和 Server 如何通信。MCP 目前主要支持两种方式stdio标准输入输出通过管道通信适用于本地集成。SSEServer-Sent Events基于 HTTP 的通信适用于远程服务。无状态更新Stateless Updates这是 MCP 架构带来的关键特性而非一个独立的组件。含义智能体Client的功能扩展不再依赖于其自身的代码更新。要增加一个新工具例如接入公司内部的请假系统开发者只需编写或部署一个对应的 MCP Server。智能体在下次连接或发现该 Server 时就能自动获得这个新工具。好处解耦工具开发与智能体开发分离。动态性工具可以热插拔。可维护性单个工具的故障和更新影响范围被隔离。安全性权限可以控制在工具层面智能体无需拥有所有工具的原始权限。2.3 MCP 与 Function Calling、Skill 的区别这是一个容易混淆的点通过下表可以清晰区分特性Function Calling (如 OpenAI)Skill (如某些AI平台)MCP (Model Context Protocol)核心概念LLM 模型的一种能力用于触发预定义的函数。封装好的、可复用的AI能力模块通常包含提示词、逻辑和工具。通信协议用于在AI应用和外部服务间标准化工具/数据的发现与调用。集成方式在调用LLM API时将函数列表作为参数传入。通常需要导入/注册到特定的智能体框架或平台中。通过启动独立的Server进程Client通过标准协议动态连接。状态管理函数定义是调用的一部分与每次会话状态相关。Skill 通常作为智能体的一部分被加载和管理。无状态。Server独立维护工具实现Client无状态地发现和调用。关注点“如何告诉模型现在可以调用哪些函数”“如何打包和复用一套完整的AI交互流程”“如何让AI应用以标准化、松耦合的方式接入任意外部能力”类比给厨师LLM一张当前可用的菜谱清单。一个已经训练好的、会做意大利菜的厨师Skill。一套厨房设备接口标准MCP让厨师可以连接并使用任何符合标准的厨具Server。简单说Function Calling 是 LLM 的交互机制Skill 是业务逻辑的封装而 MCP 是底层的基础设施协议。MCP 可以成为 Skill 或 Function Calling 背后实际调用工具的标准方式。3. 环境准备构建你的第一个 MCP 工具理解了概念我们进入实战。我们将创建一个最简单的 MCP Server它提供一个工具get_weather用于查询模拟城市天气。然后我们会看到如何让一个 MCP Client 使用它。3.1 前置条件Python 3.10MCP 的官方 Python SDK 需要较新的 Python 版本。基础 Python 知识了解虚拟环境、包管理和基础语法。一个文本编辑器或 IDE如 VSCode。3.2 安装 MCP SDKMCP 提供了多种语言的 SDK我们使用最主流的 Python 版本。首先创建一个干净的目录并设置虚拟环境。# 1. 创建项目目录并进入 mkdir my-first-mcp-server cd my-first-mcp-server # 2. 创建并激活虚拟环境 (可选但强烈推荐) python -m venv venv # 在 Windows 上激活 # venv\Scripts\activate # 在 macOS/Linux 上激活 source venv/bin/activate # 3. 安装 MCP 核心 Python 库 pip install mcpmcp这个包包含了开发 Server 和 Client 所需的核心库。4. 核心流程拆解编写 MCP Server一个 MCP Server 的核心生命周期是启动 - 向 Client 宣告能力 - 等待调用 - 执行并返回结果。我们分步实现。4.1 定义工具Tools工具是 Server 提供的主要能力。每个工具需要定义name: 工具名称Client 调用时使用。description: 工具描述帮助 LLM 理解何时使用此工具。input_schema: 输入参数的 JSON Schema定义调用时需要传递的参数及其类型。我们在项目根目录创建server.py文件。# server.py import asyncio from mcp import Server, StdioServerParameters from mcp.types import Tool, TextContent import json # 1. 初始化 MCP Server app Server(weather-mcp-server) # 2. 定义我们的工具get_weather app.list_tools() async def handle_list_tools(): 列出本 Server 提供的所有工具 weather_tool Tool( nameget_weather, description获取指定城市的当前天气信息。, input_schema{ type: object, properties: { city: { type: string, description: 城市名称例如Beijing, Shanghai, New York } }, required: [city] } ) return [weather_tool] # 3. 处理工具调用 app.call_tool() async def handle_call_tool(name: str, arguments: dict) - list: 处理 Client 对工具的调用请求 if name get_weather: city arguments.get(city, Unknown) # 这里是模拟逻辑真实场景可以调用天气 API weather_info { city: city, temperature: 22°C, condition: Sunny, humidity: 65%, wind: 10 km/h NE } # 返回结果必须是一个 Content 对象的列表这里使用 TextContent return [TextContent( typetext, textf查询到{city}的天气{json.dumps(weather_info, ensure_asciiFalse)} )] else: # 如果收到未知工具调用返回错误 raise ValueError(fUnknown tool: {name}) # 4. Server 主入口 async def main(): # 使用 stdio 传输层这是与本地 Client如 Claude Desktop通信的常见方式 async with await StdioServerParameters().create() as (read_stream, write_stream): await app.run(read_stream, write_stream) if __name__ __main__: asyncio.run(main())代码关键点解释Server(weather-mcp-server)创建一个 Server 实例名称用于标识。app.list_tools()这是一个装饰器用于处理 Client 查询工具列表的请求。当 Client 连接时会首先调用这个函数。Tool对象我们定义了一个名为get_weather的工具它需要一个city字符串参数。app.call_tool()这个装饰器用于处理 Client 发起的实际工具调用。我们根据name判断调用哪个工具从arguments中获取参数执行逻辑并返回结果。TextContentMCP 定义的内容类型之一用于返回文本结果。还可以返回ImageContent、EmbeddedResource等。StdioServerParameters()配置 Server 使用标准输入输出进行通信这是与许多桌面 AI 应用集成的最简单方式。4.2 运行 MCP Server保存server.py后在终端运行它python server.py运行后你会发现程序并没有输出而是“挂起”了。这是正常的它正在等待来自标准输入stdin的客户端连接。此时你的第一个 MCP Server 已经就绪正在监听调用。5. 连接与测试使用 MCP Client 调用工具Server 跑起来了但我们还需要一个 Client 来测试它。我们可以写一个简单的 Python Client 脚本也可以使用现成的工具。这里介绍两种方法。5.1 方法一使用官方 MCP CLI 工具测试推荐首先安装 MCP 命令行工具它内置了一个方便的 Client。# 在另一个终端窗口全局安装或在本虚拟环境中安装 pip install mcp-cli安装后使用mcp命令连接我们的 Server 并进行测试。# 假设 server.py 仍在运行 # 打开一个新的终端导航到项目目录激活相同的虚拟环境 # 使用 mcp inspect 命令连接到正在运行的 Server 并检查其能力 # 注意这里需要通过子进程启动 server.pymcp cli 提供了便利方式 # 更简单的方式是使用 mcp dev 来同时启动和调试但我们先分步理解。 # 我们可以写一个简单的测试脚本 client_test.py5.2 方法二编写一个简单的 Python Client 进行测试创建client_test.py文件# client_test.py import asyncio import json from mcp import Client, StdioClientParameters import subprocess import sys async def main(): # 1. 定义如何启动我们的 Server 进程 # 我们将通过 subprocess 启动 server.py并与其 stdio 通信 server_process subprocess.Popen( [sys.executable, server.py], # 使用当前 Python 解释器运行 server.py stdinsubprocess.PIPE, stdoutsubprocess.PIPE, stderrsubprocess.PIPE ) # 2. 创建 MCP Client 并连接到该进程 client Client() transport_params StdioClientParameters( processserver_process, # 注意这里需要将进程的 stdout 作为 Client 的 stdin反之亦然 # StdioClientParameters 内部会处理这些流的重定向 ) # 这里有一个简化步骤实际上mcp 库的 Client 需要适配这种启动方式。 # 更标准的测试方法是使用 mcp dev 或 mcp run。 # 为了概念清晰我们暂时不深入复杂的进程间通信代码。 print(提示更实用的测试方法是使用 mcp-cli 或集成到 Claude Desktop。) if __name__ __main__: asyncio.run(main())直接编写底层 Client 代码较为复杂。对于学习和初步测试强烈建议使用现成的、支持 MCP 的客户端应用这样能立即看到效果。5.3 方法三集成到 Claude Desktop最直观的体验安装 Claude Desktop从 Anthropic 官网下载安装。配置 Claude Desktop 加载本地 MCP Server Claude Desktop 允许通过配置文件添加本地 MCP Server。macOS配置文件位于~/Library/Application Support/Claude/claude_desktop_config.jsonWindows配置文件位于%APPDATA%\Claude\claude_desktop_config.json编辑配置文件如果文件不存在就创建它。添加以下内容注意调整command路径为你的server.py绝对路径{ mcpServers: { weather: { command: /path/to/your/venv/bin/python, args: [/absolute/path/to/your/my-first-mcp-server/server.py] } } }Windows 示例{ mcpServers: { weather: { command: C:\\Users\\YourName\\my-first-mcp-server\\venv\\Scripts\\python.exe, args: [C:\\Users\\YourName\\my-first-mcp-server\\server.py] } } }重启 Claude Desktop重启后在聊天框中Claude 就会自动感知到get_weather工具。你可以尝试输入“请帮我查询一下北京的天气。” Claude 应该会识别并使用这个工具并返回模拟的天气结果。这是“无状态更新”的体现你不需要更新 Claude 的代码只需要在它的配置里指向一个新的 Server 进程它就获得了新能力。6. 运行结果与效果验证成功集成后在 Claude Desktop 中的交互可能如下你 上海今天的天气怎么样 Claude 我将使用天气查询工具来获取上海的最新天气信息。 Claude 调用 get_weather 工具参数 {city: Shanghai} 工具返回 查询到上海的天气{city: Shanghai, temperature: 22°C, condition: Sunny, humidity: 65%, wind: 10 km/h NE} Claude 根据查询结果上海当前的天气是晴天气温22摄氏度湿度65%东北风10公里/小时。验证成功的关键点Claude自动发现了get_weather工具无需你在对话中手动定义。Claude正确理解了工具的描述和参数生成了符合格式的调用。Server正确执行了模拟逻辑并返回了结构化的结果。Claude将结果整合到了回复中。至此你已经完成了一个完整的 MCP “无状态更新”循环部署独立 Server - 客户端动态发现 - 无缝调用。7. 常见问题与排查思路在搭建和使用 MCP 时你可能会遇到以下问题问题现象可能原因排查方式解决方案Server 启动后立即退出Python 脚本语法错误或依赖缺失。1. 直接在终端运行python server.py看错误输出。2. 检查mcp库是否安装在当前环境。1. 修复代码错误。2. 在正确的虚拟环境中安装依赖。Claude Desktop 无法识别工具配置文件路径错误或格式不对。1. 检查配置文件路径是否正确。2. 检查 JSON 格式是否合法。3. 查看 Claude Desktop 日志帮助菜单中可能有日志选项。1. 使用绝对路径。2. 确保command是可执行文件路径。3. 重启 Claude Desktop。工具调用失败返回错误Server 端call_tool处理逻辑有误或未处理该工具名。1. 在 Server 代码中添加日志打印收到的name和arguments。2. 检查工具名是否与list_tools中返回的一致。1. 确保handle_call_tool函数能处理所有声明的工具。2. 检查参数解析逻辑。连接超时或通信失败传输层配置不匹配如 Client 期待 SSEServer 用 stdio。1. 确认 Client 和 Server 使用的传输方式stdio/SSE一致。2. 对于 stdio确保 Client 正确启动了 Server 进程。1. 参考官方示例使用正确的传输层初始化方式。2. 使用mcp-cli的mcp dev命令进行调试。工具描述不清晰LLM 不会用Tool的description或input_schema中的description写得太模糊。回顾工具描述是否清晰说明了工具的用途、适用场景和参数意义。优化描述使其对 LLM 友好。例如“获取城市天气”改为“获取指定城市当前的温度、天气状况、湿度和风速信息。”8. 最佳实践与工程建议将 MCP 用于生产环境或严肃项目时需要考虑以下几点Server 设计单一职责一个 MCP Server 应专注于一类能力。例如database-mcp-server只处理数据库操作github-mcp-server只处理 GitHub API。这符合微服务理念便于维护和更新。错误处理与日志在 Server 的call_tool函数中务必进行完善的错误处理try-catch并返回对用户友好的错误信息。同时记录日志便于排查问题。async def handle_call_tool(name: str, arguments: dict) - list: try: if name get_weather: # ... 业务逻辑 return [TextContent(...)] else: raise ValueError(fUnknown tool: {name}) except Exception as e: logging.error(fTool {name} failed with args {arguments}: {e}) # 返回错误信息给 ClientLLM 可以理解并告知用户 return [TextContent(typetext, textf执行工具 {name} 时出错{str(e)})]安全性权限控制MCP Server 进程应该以最小必要权限运行。特别是访问文件系统、数据库或外部 API 的 Server。输入验证在call_tool中严格验证arguments参数防止注入攻击如 SQL 注入、命令注入。网络隔离如果使用 SSE 传输确保 Server 有适当的身份验证和授权机制。资源Resources的利用我们上面的例子只用了Tools。MCP 还有一个强大的概念叫Resources它允许 Server 声明一些可读的数据源如file:///reports/daily.md。Client 可以在需要时直接读取这些资源的内容作为上下文。这对于提供静态知识库、文档片段非常有用。版本化与兼容性当更新 MCP Server 的工具接口如增加参数时要考虑向后兼容。突然改变接口会导致已有的 Client 调用失败。可以通过添加新工具如get_weather_v2或使参数可选来平滑过渡。生产部署对于 stdio 模式需要可靠的进程管理如 systemd, supervisor。对于 SSE 模式需要将 Server 部署为标准的 Web 服务并考虑负载均衡和高可用。9. 总结与后续学习方向MCP 提出的“无状态更新”范式为 AI 智能体基础设施的构建提供了新的思路。它通过协议化、松耦合的方式将智能体的核心推理能力与外部工具/数据源解耦。这种架构带来的核心优势是可扩展性和可维护性你可以独立开发、部署、更新一个个能力提供者MCP Server而智能体客户端却能近乎零成本地获得这些新能力。通过本文你应该已经掌握了理解了 MCP 解决的核心问题传统智能体工具集成的强耦合与状态管理难题。清楚了 MCP 的核心组件Server能力提供者、Client能力消费者、Transport通信层以及“无状态更新”的含义。亲手实践了构建一个 MCP Server 的全过程从定义工具、编写处理逻辑到运行测试。学会了如何将其集成到现有生态如 Claude Desktop。了解了常见问题的排查方法和生产级的最佳实践。下一步你可以从这些方向继续深入探索官方和社区 ServerAnthropic 维护了一个 MCP Server 示例仓库 里面有 SQLite、文件系统、时钟等众多示例。这是学习更复杂 Server 实现的绝佳资料。尝试 SSE 传输将你的 Server 改造成一个 HTTP 服务使用 SSE 与远程 Client 通信这更适合云原生部署。利用 Resources为你 Server 管理的工具添加相关的资源声明。例如一个数据库 Server 除了execute_sql工具还可以声明resource://schemas/table_users资源让 Client 能直接读取表结构作为上下文。集成到你的 AI 应用研究如何在你自己的 Python、Node.js 或其它语言的 AI 应用项目中集成 MCP 客户端库动态加载外部工具。MCP 协议仍在快速发展中但它所代表的方向——标准化、模块化、动态化的智能体能力扩展——无疑是构建下一代 AI 应用基础设施的关键拼图。现在就开始尝试将它融入你的技术栈无疑是走在趋势前沿的明智之举。建议收藏本文在实践过程中如遇问题可随时回溯查看具体步骤和排查思路。
如果你正在开发或使用 AI 智能体可能会遇到一个核心矛盾智能体需要访问外部工具和数据如数据库、API、文件系统来完成任务但直接将这些能力硬编码到智能体内部会导致它变得臃肿、难以维护且每次更新工具链都需要重新训练或部署整个智能体。这不仅仅是代码层面的问题更是工程架构的瓶颈。最近一个名为Model Context Protocol (MCP)的协议开始受到关注它提出了一种“无状态更新”的思路试图从根本上改变我们为 AI 智能体构建基础设施的方式。但 MCP 到底是什么它宣称的“无状态”又如何能扩展我们的智能体基础设施更重要的是作为一个开发者我该如何上手并利用它来解决实际问题本文将深入拆解 MCP 协议特别是其“无状态更新”的核心设计。我不会只停留在概念介绍而是会带你理解为什么传统的“有状态”工具集成方式是智能体规模化应用的绊脚石MCP 如何通过 Server/Client 分离和资源声明机制来解耦工具与智能体以及你如何通过一个具体的代码示例快速搭建一个 MCP Server 来扩展智能体的能力。无论你是 AI 应用工程师还是对智能体架构感兴趣的开发者这篇文章都将提供从原理到实践的完整路径。1. 智能体工具集成的困境为什么我们需要 MCP在深入 MCP 之前我们必须先看清它要解决什么问题。当前让 AI 智能体如基于 OpenAI Assistants API、LangChain Agent 或自定义 LLM 应用使用外部工具主流做法可以概括为两种硬编码集成在智能体的提示词Prompt或代码中直接定义工具的函数签名、描述和调用逻辑。例如直接写死一个search_web(query)的函数调用。框架封装使用 LangChain、LlamaIndex 等框架它们提供了大量的“Tool”抽象你需要将这些工具注册到你的智能体实例中。这两种方式都存在一个共同的本质问题强耦合与有状态。强耦合工具的能力、接口和智能体的核心推理逻辑绑定在一起。想新增一个操作数据库的工具你必须修改智能体的源代码或配置并重新部署。有状态智能体“拥有”这些工具。工具的变更如 API 端点更新、新增参数会直接影响到智能体的行为甚至可能因为一个工具的错误导致整个智能体不可用。当你的智能体只需要3-5个工具时这或许可以接受。但想象一下智能体平台化的场景你希望为不同部门、不同场景的智能体动态提供数十种工具——代码执行、SQL查询、Jira操作、内部CRM API、文件解析等等。传统的“有状态”集成方式会迅速变得难以管理成为开发和运维的噩梦。MCP (Model Context Protocol) 的核心价值就在于它试图将智能体Client和工具/数据源Server解耦。它定义了一套标准的通信协议让智能体可以在运行时动态发现、理解并调用外部服务提供的能力而无需在编译时或启动时就固化这些依赖。这就是“无状态更新”的精髓智能体本身不维护工具的状态工具能力的增、删、改可以通过更新独立的 MCP Server 来实现而智能体客户端几乎无需变动。2. MCP 核心概念协议、服务器、客户端与无状态2.1 什么是 Model Context Protocol (MCP)MCP 是一个开放协议用于在 AI 应用程序客户端和外部资源服务器之间建立标准化的通信。你可以把它想象成智能体世界的“USB 协议”。USB 设备MCP Server提供具体能力如U盘文件读写、键盘输入、打印机输出。每个设备都遵循 USB 标准告诉主机“我能做什么”。USB 主机MCP Client需要能力的计算机。它通过标准协议枚举、识别设备然后调用设备的功能。协议MCP规定了设备如何向主机宣告自己的能力toolsresources以及主机如何向设备发送指令、接收数据。在这个类比中智能体Client就是主机它不需要事先知道世界上有多少种 USB 设备。它只需要支持 USB 协议就能在插入新设备启动新的 MCP Server时立刻识别并使用其功能。设备的更新换代无状态更新不会影响主机本身。2.2 MCP 的核心组件MCP Server服务器角色能力提供者。它可以是任何进程封装了对特定工具、数据源或系统的访问逻辑。职责启动后向客户端宣告自己提供了哪些“工具”tools和“资源”resources。工具代表可执行的操作如run_query资源代表可读取的数据如file:///path/to/data.json。示例一个sqlite-mcp-server可以提供execute_sql工具一个filesystem-mcp-server可以提供read_file、list_directory工具和文件资源。MCP Client客户端角色能力消费者。通常是 AI 智能体应用程序或框架。职责连接到 MCP Server获取其提供的工具和资源列表。当智能体需要完成某项任务时客户端根据当前对话上下文选择合适的工具并调用它然后将结果返回给智能体。示例Claude Desktop、Cursor IDE、以及任何集成了 MCP 客户端库的 AI 应用。Transport传输层角色定义 Client 和 Server 如何通信。MCP 目前主要支持两种方式stdio标准输入输出通过管道通信适用于本地集成。SSEServer-Sent Events基于 HTTP 的通信适用于远程服务。无状态更新Stateless Updates这是 MCP 架构带来的关键特性而非一个独立的组件。含义智能体Client的功能扩展不再依赖于其自身的代码更新。要增加一个新工具例如接入公司内部的请假系统开发者只需编写或部署一个对应的 MCP Server。智能体在下次连接或发现该 Server 时就能自动获得这个新工具。好处解耦工具开发与智能体开发分离。动态性工具可以热插拔。可维护性单个工具的故障和更新影响范围被隔离。安全性权限可以控制在工具层面智能体无需拥有所有工具的原始权限。2.3 MCP 与 Function Calling、Skill 的区别这是一个容易混淆的点通过下表可以清晰区分特性Function Calling (如 OpenAI)Skill (如某些AI平台)MCP (Model Context Protocol)核心概念LLM 模型的一种能力用于触发预定义的函数。封装好的、可复用的AI能力模块通常包含提示词、逻辑和工具。通信协议用于在AI应用和外部服务间标准化工具/数据的发现与调用。集成方式在调用LLM API时将函数列表作为参数传入。通常需要导入/注册到特定的智能体框架或平台中。通过启动独立的Server进程Client通过标准协议动态连接。状态管理函数定义是调用的一部分与每次会话状态相关。Skill 通常作为智能体的一部分被加载和管理。无状态。Server独立维护工具实现Client无状态地发现和调用。关注点“如何告诉模型现在可以调用哪些函数”“如何打包和复用一套完整的AI交互流程”“如何让AI应用以标准化、松耦合的方式接入任意外部能力”类比给厨师LLM一张当前可用的菜谱清单。一个已经训练好的、会做意大利菜的厨师Skill。一套厨房设备接口标准MCP让厨师可以连接并使用任何符合标准的厨具Server。简单说Function Calling 是 LLM 的交互机制Skill 是业务逻辑的封装而 MCP 是底层的基础设施协议。MCP 可以成为 Skill 或 Function Calling 背后实际调用工具的标准方式。3. 环境准备构建你的第一个 MCP 工具理解了概念我们进入实战。我们将创建一个最简单的 MCP Server它提供一个工具get_weather用于查询模拟城市天气。然后我们会看到如何让一个 MCP Client 使用它。3.1 前置条件Python 3.10MCP 的官方 Python SDK 需要较新的 Python 版本。基础 Python 知识了解虚拟环境、包管理和基础语法。一个文本编辑器或 IDE如 VSCode。3.2 安装 MCP SDKMCP 提供了多种语言的 SDK我们使用最主流的 Python 版本。首先创建一个干净的目录并设置虚拟环境。# 1. 创建项目目录并进入 mkdir my-first-mcp-server cd my-first-mcp-server # 2. 创建并激活虚拟环境 (可选但强烈推荐) python -m venv venv # 在 Windows 上激活 # venv\Scripts\activate # 在 macOS/Linux 上激活 source venv/bin/activate # 3. 安装 MCP 核心 Python 库 pip install mcpmcp这个包包含了开发 Server 和 Client 所需的核心库。4. 核心流程拆解编写 MCP Server一个 MCP Server 的核心生命周期是启动 - 向 Client 宣告能力 - 等待调用 - 执行并返回结果。我们分步实现。4.1 定义工具Tools工具是 Server 提供的主要能力。每个工具需要定义name: 工具名称Client 调用时使用。description: 工具描述帮助 LLM 理解何时使用此工具。input_schema: 输入参数的 JSON Schema定义调用时需要传递的参数及其类型。我们在项目根目录创建server.py文件。# server.py import asyncio from mcp import Server, StdioServerParameters from mcp.types import Tool, TextContent import json # 1. 初始化 MCP Server app Server(weather-mcp-server) # 2. 定义我们的工具get_weather app.list_tools() async def handle_list_tools(): 列出本 Server 提供的所有工具 weather_tool Tool( nameget_weather, description获取指定城市的当前天气信息。, input_schema{ type: object, properties: { city: { type: string, description: 城市名称例如Beijing, Shanghai, New York } }, required: [city] } ) return [weather_tool] # 3. 处理工具调用 app.call_tool() async def handle_call_tool(name: str, arguments: dict) - list: 处理 Client 对工具的调用请求 if name get_weather: city arguments.get(city, Unknown) # 这里是模拟逻辑真实场景可以调用天气 API weather_info { city: city, temperature: 22°C, condition: Sunny, humidity: 65%, wind: 10 km/h NE } # 返回结果必须是一个 Content 对象的列表这里使用 TextContent return [TextContent( typetext, textf查询到{city}的天气{json.dumps(weather_info, ensure_asciiFalse)} )] else: # 如果收到未知工具调用返回错误 raise ValueError(fUnknown tool: {name}) # 4. Server 主入口 async def main(): # 使用 stdio 传输层这是与本地 Client如 Claude Desktop通信的常见方式 async with await StdioServerParameters().create() as (read_stream, write_stream): await app.run(read_stream, write_stream) if __name__ __main__: asyncio.run(main())代码关键点解释Server(weather-mcp-server)创建一个 Server 实例名称用于标识。app.list_tools()这是一个装饰器用于处理 Client 查询工具列表的请求。当 Client 连接时会首先调用这个函数。Tool对象我们定义了一个名为get_weather的工具它需要一个city字符串参数。app.call_tool()这个装饰器用于处理 Client 发起的实际工具调用。我们根据name判断调用哪个工具从arguments中获取参数执行逻辑并返回结果。TextContentMCP 定义的内容类型之一用于返回文本结果。还可以返回ImageContent、EmbeddedResource等。StdioServerParameters()配置 Server 使用标准输入输出进行通信这是与许多桌面 AI 应用集成的最简单方式。4.2 运行 MCP Server保存server.py后在终端运行它python server.py运行后你会发现程序并没有输出而是“挂起”了。这是正常的它正在等待来自标准输入stdin的客户端连接。此时你的第一个 MCP Server 已经就绪正在监听调用。5. 连接与测试使用 MCP Client 调用工具Server 跑起来了但我们还需要一个 Client 来测试它。我们可以写一个简单的 Python Client 脚本也可以使用现成的工具。这里介绍两种方法。5.1 方法一使用官方 MCP CLI 工具测试推荐首先安装 MCP 命令行工具它内置了一个方便的 Client。# 在另一个终端窗口全局安装或在本虚拟环境中安装 pip install mcp-cli安装后使用mcp命令连接我们的 Server 并进行测试。# 假设 server.py 仍在运行 # 打开一个新的终端导航到项目目录激活相同的虚拟环境 # 使用 mcp inspect 命令连接到正在运行的 Server 并检查其能力 # 注意这里需要通过子进程启动 server.pymcp cli 提供了便利方式 # 更简单的方式是使用 mcp dev 来同时启动和调试但我们先分步理解。 # 我们可以写一个简单的测试脚本 client_test.py5.2 方法二编写一个简单的 Python Client 进行测试创建client_test.py文件# client_test.py import asyncio import json from mcp import Client, StdioClientParameters import subprocess import sys async def main(): # 1. 定义如何启动我们的 Server 进程 # 我们将通过 subprocess 启动 server.py并与其 stdio 通信 server_process subprocess.Popen( [sys.executable, server.py], # 使用当前 Python 解释器运行 server.py stdinsubprocess.PIPE, stdoutsubprocess.PIPE, stderrsubprocess.PIPE ) # 2. 创建 MCP Client 并连接到该进程 client Client() transport_params StdioClientParameters( processserver_process, # 注意这里需要将进程的 stdout 作为 Client 的 stdin反之亦然 # StdioClientParameters 内部会处理这些流的重定向 ) # 这里有一个简化步骤实际上mcp 库的 Client 需要适配这种启动方式。 # 更标准的测试方法是使用 mcp dev 或 mcp run。 # 为了概念清晰我们暂时不深入复杂的进程间通信代码。 print(提示更实用的测试方法是使用 mcp-cli 或集成到 Claude Desktop。) if __name__ __main__: asyncio.run(main())直接编写底层 Client 代码较为复杂。对于学习和初步测试强烈建议使用现成的、支持 MCP 的客户端应用这样能立即看到效果。5.3 方法三集成到 Claude Desktop最直观的体验安装 Claude Desktop从 Anthropic 官网下载安装。配置 Claude Desktop 加载本地 MCP Server Claude Desktop 允许通过配置文件添加本地 MCP Server。macOS配置文件位于~/Library/Application Support/Claude/claude_desktop_config.jsonWindows配置文件位于%APPDATA%\Claude\claude_desktop_config.json编辑配置文件如果文件不存在就创建它。添加以下内容注意调整command路径为你的server.py绝对路径{ mcpServers: { weather: { command: /path/to/your/venv/bin/python, args: [/absolute/path/to/your/my-first-mcp-server/server.py] } } }Windows 示例{ mcpServers: { weather: { command: C:\\Users\\YourName\\my-first-mcp-server\\venv\\Scripts\\python.exe, args: [C:\\Users\\YourName\\my-first-mcp-server\\server.py] } } }重启 Claude Desktop重启后在聊天框中Claude 就会自动感知到get_weather工具。你可以尝试输入“请帮我查询一下北京的天气。” Claude 应该会识别并使用这个工具并返回模拟的天气结果。这是“无状态更新”的体现你不需要更新 Claude 的代码只需要在它的配置里指向一个新的 Server 进程它就获得了新能力。6. 运行结果与效果验证成功集成后在 Claude Desktop 中的交互可能如下你 上海今天的天气怎么样 Claude 我将使用天气查询工具来获取上海的最新天气信息。 Claude 调用 get_weather 工具参数 {city: Shanghai} 工具返回 查询到上海的天气{city: Shanghai, temperature: 22°C, condition: Sunny, humidity: 65%, wind: 10 km/h NE} Claude 根据查询结果上海当前的天气是晴天气温22摄氏度湿度65%东北风10公里/小时。验证成功的关键点Claude自动发现了get_weather工具无需你在对话中手动定义。Claude正确理解了工具的描述和参数生成了符合格式的调用。Server正确执行了模拟逻辑并返回了结构化的结果。Claude将结果整合到了回复中。至此你已经完成了一个完整的 MCP “无状态更新”循环部署独立 Server - 客户端动态发现 - 无缝调用。7. 常见问题与排查思路在搭建和使用 MCP 时你可能会遇到以下问题问题现象可能原因排查方式解决方案Server 启动后立即退出Python 脚本语法错误或依赖缺失。1. 直接在终端运行python server.py看错误输出。2. 检查mcp库是否安装在当前环境。1. 修复代码错误。2. 在正确的虚拟环境中安装依赖。Claude Desktop 无法识别工具配置文件路径错误或格式不对。1. 检查配置文件路径是否正确。2. 检查 JSON 格式是否合法。3. 查看 Claude Desktop 日志帮助菜单中可能有日志选项。1. 使用绝对路径。2. 确保command是可执行文件路径。3. 重启 Claude Desktop。工具调用失败返回错误Server 端call_tool处理逻辑有误或未处理该工具名。1. 在 Server 代码中添加日志打印收到的name和arguments。2. 检查工具名是否与list_tools中返回的一致。1. 确保handle_call_tool函数能处理所有声明的工具。2. 检查参数解析逻辑。连接超时或通信失败传输层配置不匹配如 Client 期待 SSEServer 用 stdio。1. 确认 Client 和 Server 使用的传输方式stdio/SSE一致。2. 对于 stdio确保 Client 正确启动了 Server 进程。1. 参考官方示例使用正确的传输层初始化方式。2. 使用mcp-cli的mcp dev命令进行调试。工具描述不清晰LLM 不会用Tool的description或input_schema中的description写得太模糊。回顾工具描述是否清晰说明了工具的用途、适用场景和参数意义。优化描述使其对 LLM 友好。例如“获取城市天气”改为“获取指定城市当前的温度、天气状况、湿度和风速信息。”8. 最佳实践与工程建议将 MCP 用于生产环境或严肃项目时需要考虑以下几点Server 设计单一职责一个 MCP Server 应专注于一类能力。例如database-mcp-server只处理数据库操作github-mcp-server只处理 GitHub API。这符合微服务理念便于维护和更新。错误处理与日志在 Server 的call_tool函数中务必进行完善的错误处理try-catch并返回对用户友好的错误信息。同时记录日志便于排查问题。async def handle_call_tool(name: str, arguments: dict) - list: try: if name get_weather: # ... 业务逻辑 return [TextContent(...)] else: raise ValueError(fUnknown tool: {name}) except Exception as e: logging.error(fTool {name} failed with args {arguments}: {e}) # 返回错误信息给 ClientLLM 可以理解并告知用户 return [TextContent(typetext, textf执行工具 {name} 时出错{str(e)})]安全性权限控制MCP Server 进程应该以最小必要权限运行。特别是访问文件系统、数据库或外部 API 的 Server。输入验证在call_tool中严格验证arguments参数防止注入攻击如 SQL 注入、命令注入。网络隔离如果使用 SSE 传输确保 Server 有适当的身份验证和授权机制。资源Resources的利用我们上面的例子只用了Tools。MCP 还有一个强大的概念叫Resources它允许 Server 声明一些可读的数据源如file:///reports/daily.md。Client 可以在需要时直接读取这些资源的内容作为上下文。这对于提供静态知识库、文档片段非常有用。版本化与兼容性当更新 MCP Server 的工具接口如增加参数时要考虑向后兼容。突然改变接口会导致已有的 Client 调用失败。可以通过添加新工具如get_weather_v2或使参数可选来平滑过渡。生产部署对于 stdio 模式需要可靠的进程管理如 systemd, supervisor。对于 SSE 模式需要将 Server 部署为标准的 Web 服务并考虑负载均衡和高可用。9. 总结与后续学习方向MCP 提出的“无状态更新”范式为 AI 智能体基础设施的构建提供了新的思路。它通过协议化、松耦合的方式将智能体的核心推理能力与外部工具/数据源解耦。这种架构带来的核心优势是可扩展性和可维护性你可以独立开发、部署、更新一个个能力提供者MCP Server而智能体客户端却能近乎零成本地获得这些新能力。通过本文你应该已经掌握了理解了 MCP 解决的核心问题传统智能体工具集成的强耦合与状态管理难题。清楚了 MCP 的核心组件Server能力提供者、Client能力消费者、Transport通信层以及“无状态更新”的含义。亲手实践了构建一个 MCP Server 的全过程从定义工具、编写处理逻辑到运行测试。学会了如何将其集成到现有生态如 Claude Desktop。了解了常见问题的排查方法和生产级的最佳实践。下一步你可以从这些方向继续深入探索官方和社区 ServerAnthropic 维护了一个 MCP Server 示例仓库 里面有 SQLite、文件系统、时钟等众多示例。这是学习更复杂 Server 实现的绝佳资料。尝试 SSE 传输将你的 Server 改造成一个 HTTP 服务使用 SSE 与远程 Client 通信这更适合云原生部署。利用 Resources为你 Server 管理的工具添加相关的资源声明。例如一个数据库 Server 除了execute_sql工具还可以声明resource://schemas/table_users资源让 Client 能直接读取表结构作为上下文。集成到你的 AI 应用研究如何在你自己的 Python、Node.js 或其它语言的 AI 应用项目中集成 MCP 客户端库动态加载外部工具。MCP 协议仍在快速发展中但它所代表的方向——标准化、模块化、动态化的智能体能力扩展——无疑是构建下一代 AI 应用基础设施的关键拼图。现在就开始尝试将它融入你的技术栈无疑是走在趋势前沿的明智之举。建议收藏本文在实践过程中如遇问题可随时回溯查看具体步骤和排查思路。
安装与使用--生信工具107)
