1. 从一次踩坑说起MCP 到底解决了什么问题去年下半年我接手了一个内部工具链整合的活儿需求说起来很简单让团队里的 AI 助手能直接读取我们自研工单系统的数据顺便把设计稿的标注信息也拉进来。当时我的第一反应是写几个函数调用用 LangChain 的 tool 机制包一层就完事了。结果真动手才发现光是让模型稳定地选对工具、传对参数就折腾了整整两周。更别提后面要接入 Figma、蓝湖、Playwright 这些第三方能力时每接一个都要重新写一遍适配层代码里全是胶水逻辑。后来接触到MCPModel Context Protocol才意识到这套协议想干的事情本质上就是给模型和外部能力之间定一套统一的插座标准。你可以把它理解成 USB-C以前每个设备一个接口现在大家都用同一个口插上就能用。MCP 要解决的就是 AI 应用和外部工具、数据源之间那种每接一个都要重新造轮子的混乱局面。这篇文章我打算把 MCP 从概念到落地完整捋一遍重点讲清楚三件事MCP 的协议设计到底长什么样、FastMCP 这类框架怎么帮你快速写出一个 MCP Server、以及在实际 Agent 项目里 MCP 和 LangChain 这类框架怎么配合使用。适合已经写过一些 Agent demo、但被工具集成折磨过的开发者也适合刚听说 MCP 想搞清楚它和传统 function calling 区别的朋友。文中涉及的操作步骤和参数配置都是我在实际项目里跑通过的方案可以直接抄作业。2. MCP 协议的核心设计与选型逻辑2.1 为什么不是简单的 function calling很多人第一次听说 MCP 会问这不就是 function calling 换了个名字吗我一开始也这么想直到把两者的边界理清楚。Function calling 本质上是模型侧的能力——你告诉模型有这么几个函数你根据需要调用模型返回一个结构化的调用请求剩下的执行、结果回传、多轮编排全靠你自己写。它解决的是模型知道该调什么但没解决这个函数从哪来、怎么被发现、怎么被复用。MCP 站的位置不一样它是协议层的东西。它规定了 Server 怎么描述自己有哪些能力tools、resources、promptsClient 怎么发现这些能力双方怎么交换数据。换句话说function calling 是模型说我要调这个MCP 是这个能力本身怎么被标准化地暴露出来。我打个比方function calling 像是你打电话点外卖你得知道每家店的电话MCP 像是外卖平台所有店都按统一格式上架你打开 App 就能看到全部菜单。前者是调用动作后者是能力市场。这个区别带来的实际影响很大。用 function calling 时每换一个模型、每换一个框架工具定义就得重写一遍用 MCP 时Server 写一次任何支持 MCP 的 Client 都能接。这就是为什么现在 Figma MCP、Playwright MCP、蓝湖 MCP 这些第三方 Server 能快速铺开——大家遵循同一套协议接入成本被摊薄了。2.2 MCP 的三个核心原语MCP 协议里最需要搞明白的是三个原语Tools、Resources、Prompts。这三个词看着简单但用错场景会让你的 Server 设计得很别扭。Tools是模型可以主动调用的动作比如查询工单创建任务执行一段 Playwright 脚本。它对应的是有副作用的操作模型决定什么时候调、传什么参数。这是用得最多的原语也是和 function calling 最像的部分。Resources是模型可以读取的数据比如一个文件内容、一条数据库记录、一份设计稿的标注 JSON。它和 Tools 的关键区别是Resources 是被动读取的通常由 Client 决定要不要塞进上下文而不是模型主动去调。我见过不少人把查询类操作也做成 Tool其实如果只是读数据、没有副作用做成 Resource 更符合协议语义。Prompts是可复用的提示模板Server 可以提供一些预设的 promptClient 让用户选择后填充参数。这个原语用得相对少但在一些需要固定工作流的场景里很有用比如代码审查周报生成这类模板化任务。提示新手最容易犯的错是把所有东西都做成 Tool。判断标准很简单——有副作用、需要模型决策的用 Tool纯读取、由上下文驱动的用 Resource固定模板的用 Prompt。2.3 传输层stdio 还是 HTTPMCP 支持多种传输方式实际项目里最常用的是两种stdio和HTTP含 SSE。stdio 是本地进程间通信Client 启动 Server 子进程通过标准输入输出交换 JSON-RPC 消息。它的优点是简单、无需网络配置、天然隔离适合本地工具类 Server比如文件操作、本地数据库查询。你在 Claude Desktop 里配置的那些 MCP Server绝大多数走的就是 stdio。HTTP 传输适合远程 Server比如团队共享的服务、需要鉴权的第三方能力。它支持 SSEServer-Sent Events做流式推送适合长任务场景。选哪种取决于你的部署形态本地单机工具选 stdio团队共享或云端能力选 HTTP。我个人的经验是开发阶段一律先用 stdio因为调试方便日志直接打到终端等逻辑稳定了再考虑要不要改成 HTTP 部署。很多教程一上来就讲远程部署反而把简单问题复杂化了。3. FastMCP 快速上手从零写一个可用的 Server3.1 环境准备与依赖选择FastMCP 是目前写 Python MCP Server 最顺手的框架它把协议细节都封装好了你只需要关注业务逻辑。安装很直接pip install fastmcp如果你用 conda 管理环境LangChain 项目里很常见建议单独建一个环境避免和主项目的依赖打架conda create -n mcp-dev python3.11 conda activate mcp-dev pip install fastmcpPython 版本我建议 3.10 以上因为 MCP 的异步特性和类型注解用到了不少新语法。3.11 在性能和错误提示上都更友好实测下来启动速度比 3.9 快一截。依赖方面FastMCP 本身很轻核心就依赖 pydantic 和 httpx。如果你要写的是对接第三方 API 的 Server按需装对应的 SDK 就行不用一股脑全装上。3.2 最小可运行 Server 的结构一个最小的 FastMCP Server 长这样from fastmcp import FastMCP mcp FastMCP(demo-server) mcp.tool() def add(a: int, b: int) - int: 两数相加 return a b if __name__ __main__: mcp.run()就这么几行。FastMCP(demo-server)创建实例mcp.tool()装饰器把一个普通函数注册成 Tool类型注解自动转成参数的 JSON Schemadocstring 自动变成工具描述。mcp.run()默认走 stdio 传输。这里有个细节值得说类型注解和 docstring 不是可选项是协议的一部分。模型能不能正确调用你的工具很大程度上取决于这两样写得好不好。我见过有人写def query(sql)然后 docstring 就一句查询结果模型根本不知道该传什么格式的 SQL调用失败率极高。3.3 参数设计与描述撰写的心得工具的参数设计直接决定了模型的调用准确率。我踩过的坑总结下来有几条第一参数名要自解释。start_date比sd好user_id比uid好。模型是靠语义理解来填参数的缩写会让它猜。第二枚举值要显式列出。如果某个参数只能是几个固定值用Literal类型标注FastMCP 会自动生成 enum 约束from typing import Literal mcp.tool() def set_priority(task_id: str, level: Literal[low, medium, high]) - str: 设置任务优先级 return f任务 {task_id} 优先级已设为 {level}第三docstring 要写清楚什么时候用而不只是是什么。比如查询工单状态当用户询问某个工单当前进展时使用比查询工单有用得多。模型选工具时看的就是这段描述。第四参数数量控制在 5 个以内。超过 5 个参数的工具模型填错的概率会明显上升。如果业务确实复杂拆成多个工具或者用一个结构化的对象参数。注意FastMCP 会把函数返回值自动序列化。如果你返回的是自定义对象确保它能被 JSON 序列化否则会报错。我一般直接返回 dict 或 str省心。4. 把 MCP 接进 LangChain Agent 的完整流程4.1 MCP 与 LangChain 的定位关系这里要先厘清一个常见困惑MCP 和 LangChain 是竞争关系吗不是。它们在不同的层次上。LangChain 是应用编排框架负责把模型、工具、记忆、流程串起来MCP 是能力接入协议负责标准化外部能力的暴露方式。一个 LangChain Agent 完全可以把 MCP Server 提供的工具当作自己的工具来用。实际项目里我常用的组合是用 FastMCP 写业务相关的 Server对接内部系统用 LangChain 写 Agent 的编排逻辑中间用一个适配层把 MCP 的工具转成 LangChain 的 Tool 格式。这样业务能力可以独立演进Agent 逻辑也能灵活调整。LangGraph 在这里的角色又不一样它是 LangChain 生态里做有状态、多步骤流程的库。如果你的 Agent 需要循环、分支、人工介入这些复杂控制流LangGraph 比裸的 LangChain Agent 更合适。MCP 和这两者都不冲突它只是工具来源。4.2 用 MCP 客户端加载工具LangChain 生态里有现成的 MCP 适配器可以自动发现并加载 MCP Server 的工具。核心思路是启动一个 MCP Client连上 Server拉取工具列表转成 LangChain 的 StructuredTool。from langchain_mcp_adapters.client import MultiServerMCPClient client MultiServerMCPClient({ demo: { command: python, args: [demo_server.py], transport: stdio, } }) tools await client.get_tools()get_tools()返回的就是一组 LangChain 兼容的工具可以直接塞进 Agent。MultiServerMCPClient支持同时连多个 Server这对实际项目很重要——你可能有对接工单系统的 Server、对接设计稿的 Server、对接浏览器的 Server一次性全加载进来。配置里的command和args是启动 stdio Server 的方式transport指定传输类型。如果连的是远程 HTTP Server改成对应的 url 和 transport 就行。4.3 组装 Agent 并跑通第一个任务工具加载好之后组装 Agent 就是常规操作from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate llm ChatOpenAI(modelgpt-4o, temperature0) prompt ChatPromptTemplate.from_messages([ (system, 你是一个助手可以调用工具完成任务。), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools, verboseTrue) result await executor.ainvoke({input: 帮我查一下工单 12345 的状态})跑通之后你会看到 verbose 日志里模型先决定调用哪个工具、传什么参数然后工具返回结果模型再组织成自然语言。这个过程和纯 function calling 看起来一样但底层工具是通过 MCP 协议动态发现的换一个 Server 不用改 Agent 代码。4.4 多 Server 协同的编排技巧实际项目里往往要同时接好几个 Server。我遇到的一个典型场景是用户说把这个设计稿的标注同步到工单系统需要先调设计稿 Server 拿标注再调工单 Server 创建任务。这种跨 Server 的编排靠模型自己规划是可以的但稳定性一般。我的做法是在 system prompt 里明确告诉模型这类任务的步骤或者干脆用 LangGraph 写一个固定的流程把 MCP 工具当作节点里的执行单元。前者灵活但容易飘后者稳定但不够通用看具体场景选。还有一个技巧是给工具加命名空间前缀。多个 Server 可能有同名工具加载时加个前缀比如design_get_annotation、ticket_create能避免模型选错。5. 常见问题与排查实录5.1 Server 启动失败怎么定位最常见的问题是 Server 起不来Client 那边报连接超时。排查顺序我一般是这样的先单独跑 Server确认它能正常启动。stdio Server 直接python server.py如果卡住不动是正常的它在等输入但如果报错就要先解决。常见错误是依赖没装全、Python 版本不对、或者 import 路径有问题。再确认 Client 配置的 command 和 args 正确。这里有个坑command用的是系统 PATH 里的可执行文件如果你在 conda 环境里可能要用环境的绝对路径比如/opt/conda/envs/mcp-dev/bin/python。我因为这个坑浪费过一下午。最后看日志。FastMCP 默认把日志打到 stderrClient 那边通常会捕获。如果看不到可以在 Server 里加日志输出到文件方便排查。5.2 工具调用参数错误的处理模型传错参数是高频问题。表现是工具执行报错或者返回结果不符合预期。解决思路分两层一层是把工具定义写清楚前面讲过的类型注解、枚举、docstring 都是干这个的。参数描述里最好带上示例比如日期格式 YYYY-MM-DD。另一层是在工具内部做防御性校验。不要假设模型一定传对参数进来先校验不合法就返回一个清晰的错误信息让模型有机会重试。比如mcp.tool() def query_ticket(ticket_id: str) - dict: 根据工单 ID 查询工单详情ticket_id 格式为纯数字字符串 if not ticket_id.isdigit(): return {error: fticket_id 必须是数字收到的是 {ticket_id}} # ... 实际查询逻辑返回结构化错误比直接抛异常好因为异常会中断 Agent 流程而错误信息能让模型自我纠正。5.3 性能与超时问题MCP 调用本身开销很小瓶颈通常在工具背后的实际操作。如果某个工具要跑几秒甚至几十秒比如 Playwright 打开浏览器、调用慢速 API要注意超时设置。stdio 传输下Client 和 Server 是同一台机器网络不是问题但工具执行时间长了会阻塞。我的做法是给耗时工具加异步支持FastMCP 支持 async 函数mcp.tool() async def slow_query(param: str) - str: 耗时查询 result await some_async_operation(param) return result异步工具不会阻塞事件循环多个调用可以并发。实测下来把几个耗时工具改成异步后整体响应时间降了一半以上。5.4 常见问题速查表问题现象可能原因排查方向Client 连接超时Server 未启动或路径错误单独跑 Server检查 command 绝对路径工具列表为空装饰器未生效或 import 失败检查mcp.tool()是否加在函数上模型不调用工具docstring 描述不清补充何时使用的场景描述参数类型错误类型注解缺失补全类型注解用 Literal 约束枚举返回值序列化失败返回了非 JSON 对象统一返回 dict 或 str多 Server 工具冲突工具重名加载时加命名空间前缀提示调试 MCP 时我习惯先用 MCP Inspector 这类工具单独测 Server确认工具能正常列出和调用再接进 Agent。这样能把问题隔离在协议层还是编排层。6. 从能跑到好用几个进阶实践6.1 工具粒度的取舍工具拆得太细模型要调很多次才能完成一个任务容易中途出错拆得太粗参数复杂模型填不对。我的经验是按业务动作划分一个工具对应一个完整的业务操作而不是一个技术步骤。比如创建工单应该是一个工具而不是打开表单填标题填描述提交四个工具。前者模型一次调用搞定后者要四次中间任何一步出错整个流程就断了。但也不能太粗。如果一个工具要处理十几种情况参数一大堆那就要拆。判断标准是这个工具的参数能不能用一句话说清楚能就合适不能就拆。6.2 错误处理与重试策略Agent 场景下工具报错是常态。好的错误处理能让 Agent 自我恢复差的错误处理会让整个流程崩掉。我的原则是可预期的错误返回结构化信息不可预期的错误抛异常。可预期的比如参数不合法、资源不存在返回{error: ...}让模型重试不可预期的比如网络断了、服务挂了抛异常让上层处理。重试策略上LangChain 的 AgentExecutor 支持配置max_iterations防止模型陷入死循环。我一般设 10 到 15够用又不会失控。6.3 安全边界的设计MCP Server 暴露的能力直接对模型开放安全边界必须提前设计。几条硬性规则写操作要有确认机制。删除、修改这类操作不要让模型直接执行加一层确认或者限制在特定条件下。敏感数据要脱敏。Server 返回的数据里如果有用户隐私、密钥之类返回前处理掉。权限要隔离。不同 Server 对应不同权限不要让一个 Server 什么都能干。这些不是 MCP 协议强制要求的但实际项目里不做会出大事。我见过有人把数据库直连的 Server 暴露出去模型一个误操作就把表清了。6.4 可观测性建设Agent 跑起来之后你得知道它到底干了什么。MCP 层面我建议在 Server 里加调用日志记录每次工具调用的参数和结果。LangChain 层面用 LangSmith 或者自己打日志记录 Agent 的决策过程。这两层日志合起来出问题时能快速定位是模型决策错了还是工具执行错了。没有日志的 Agent 项目调试起来就是盲人摸象。7. 我对 MCP 落地的一点个人体会MCP 这套协议刚出来的时候我其实有点怀疑——又是一个标准会不会像很多标准一样说得好听但落地困难。但实际用下来它在工具集成这个场景上确实解决了真问题。以前接一个第三方能力要写一堆适配代码现在只要对方提供了 MCP Server配置几行就能用。不过我也想提醒一句MCP 不是银弹。它解决的是能力如何标准化暴露的问题不解决Agent 如何聪明地使用能力的问题。工具描述写得好不好、参数设计合不合理、错误处理到不到位这些还是得靠人。我见过有人以为接了 MCP 就万事大吉结果工具描述一塌糊涂模型调用成功率还不如手写的 function calling。最后分享一个我最近在用的做法把常用的 MCP Server 配置抽成一个独立的配置文件不同项目共享。这样新起一个 Agent 项目时工具层几乎零成本。配合 LangGraph 做流程编排MCP 做能力接入目前是我觉得比较顺手的组合。至于后面 MCP 生态会怎么演进第三方 Server 会不会像 npm 包一样丰富还得再观察但至少现在它值得你花时间搞明白。