★ FEATURED ARTICLE 这两年聊大模型应用绕不开一个词MCP。如果你正打算给大模型接个数据库、查个系统状态或者让它操作某个内部工具却又不确定MCP、Function Calling、Agent这几个概念到底谁是谁这篇文章就是冲这个来的。我会从一个已经落地过类似项目的开发者角度把MCP的来龙去脉、工作原理、完整调用链路以及一次可以照着复现的实验过程讲清楚。文章里有代码、有配置、有调试方法也有不少我实际踩过的坑。1. 先别急着装框架——搞清楚MCP解决的真实痛点很多人第一次接触MCP第一反应是“又一个新框架要学”。实际不是这样。MCP全称是Model Context Protocol翻译过来是模型上下文协议它要解决的并不是“怎么写AI应用”而是“大模型怎么跟外部工具和数据打交道”这件事上的标准缺失。你可以把它理解为AI世界里的USB-C接口过去各种外设各有各的接口现在大家约好用同一个插上就能用。1.1 为什么需要这样一套标准在MCP出现之前每个大模型应用要连接外部能力基本是各搞各的。聊天机器人要查天气开发者就要写一个天气查询函数把它塞进Prompt里让大模型生成参数再自己写代码去调用。这看起来不复杂麻烦的是每个场景都要这样来一遍而且每家应用、每个模型、每种工具的参数格式都不统一。等到接的东西变多比如要同时查数据库、读文件、调用内部API、操作浏览器问题就暴露了函数定义格式没有统一标准A应用里能用的一套B应用里要重写。工具多了以后上下文越来越长模型反而不知道优先调用哪个。工具的执行结果返回后没有规范模型拿到的是各种各样的JSON、纯文本、报错信息需要自己再做一层清洗和拼接。每次新增工具都要改业务代码改动范围不可控。我当初在做一个内部系统联动的时候就被这类问题折腾得不轻。当时我们把十几个工具塞进同一个Agent代码里表面上看功能都有实际维护起来非常痛苦改一个工具的输入格式可能要连带改调用的地方、改Prompt、改结果解析。后来换了MCP的思路重构才发现这套“约定优于配置”的方式确实省心。MCP的目标很明确把工具连接、资源访问、模型交互这些通用能力抽成一层标准化的协议让大模型应用不用关心对方到底怎么实现。1.2 传统Function Calling模式的局限很多人把Function Calling和MCP对立起来看问“哪个更好”。严格说两者不是同一个层面的东西。Function Calling是针对大模型自身的接口能力模型可以在对话过程中输出一个结构化的调用请求比如要调用get_weather(city杭州)然后由应用侧执行并返回结果。这解决的是“模型如何表达调用意图”的问题。MCP则更进一步它把“模型提出调用意图”之后的整条链路都标准化了。如果用MCP你不再需要自己定义一个私有格式告诉模型有哪些函数可以调也不用手写工具结果回填逻辑。MCP协议里规定了服务器怎么暴露工具、客户端怎么发现工具、模型怎么发起调用、结果怎么返回、出了问题怎么报错。也就是说Function Calling可以看作单个模型能力层面的东西MCP是应用架构层面的互操作标准。打个比方Function Calling像是“你能听懂我的指令”MCP则是“我们约好了一整套打电话、查资料、记录结果的流程”。前者解决智力后者解决协作。1.3 MCP到底改了哪里MCP的核心特征是它把传统上散落在应用代码里的“工具适配逻辑”剥离出来放到了独立进程或独立服务里。这些独立服务就是MCP Server。它们通过标准接口向大模型应用暴露三类能力Tools可执行的操作、Resources可读取的数据、Prompts可复用的提示模板。大模型应用则扮演MCP Host的角色负责跟用户交互、维护上下文并把MCP Server返回的结果拼回对话里。这种“命令式工具 可读资源 模板提示”的分类方式正是MCP的巧妙之处。它没有把所有能力都塞进“工具”这一个筐里而是允许开发者区分“让模型做一件事”和“让模型读一段数据”。很多数据类资源并不适合做成函数调用更适合作为可检索的上下文内容。MCP把这块单独拎出来等于在设计层面就替你规划好了。2. MCP是怎么工作的角色、原语与一次完整调用链路我在第一次接触MCP的时候看了半天文档脑子里还是一团浆糊。原因是它包含了太多角色名称Host、Client、Server还有Tool、Resource、Prompt。后来我把它们理成一条线发现其实不复杂。你只需要记住一个大模型应用可以同时连接多个MCP Server每个Server提供若干工具或资源应用层负责协调整体流程。2.1 三个核心角色先看角色。MCP架构里有三个基本角色MCP Host也就是用户直接面对的大模型应用层。它负责运行大模型、管理会话上下文、接收用户输入、展示结果。用户不需要直接跟哪个Server打交道所有交互都发生在Host里。MCP Client它是Host内部或者由Host创建的一个连接组件可以理解成Host派出去跟Server对话的信使。一个Host里通常可以同时存在多个Client分别连接不同的Server。MCP Server提供具体能力的一方。它可以是一个本地Python进程也可以是一个远程HTTP服务只要实现了MCP协议Host就能发现它、使用它。这里有个容易混淆的细节MCP协议是Client和Server之间的桥梁Host只是策略管理者。真正跑协议消息、握手、发现工具的是Client。整体上你可以把MCP想象成一个小型家政平台Host是雇主Client是经纪人Server是提供服务的各类师傅。雇主不会直接跟师傅打电话所有预约、确认、反馈都走经纪人。2.2 三种原语Tools、Resources、PromptsMCP协议把所有可被AI使用的能力抽象成三种原语Tools工具模型可以调用的函数比如查天气、发消息、提交表单。工具通常有输入参数和输出结果适合“执行一个动作”的场景。Resources资源模型可以读取的数据比如一个文件、一张表、一份配置。在MCP里资源通过URI定位可以静态存在也可以由代码动态生成。资源的意义是给模型提供上下文素材而不是直接执行操作。Prompts提示模板预定义的用户交互模板。你可以把一组常用的指令模式固化成模板方便在不同会话里复用。比如“把下面这段文字翻译成报告风格”就可以是一个Prompt模板。三种原语之间的关系有点像工具是“手”资源是“眼睛和耳朵”提示模板是“固定话术”。模型需要动手时调工具需要查资料时读资源需要开场或者收尾时套模板。2.3 一次完整的工具调用链路讲完角色和原语我把一次最简单的工具调用拆成七步这样你对MCP的运作会有个直观印象。假设我已经在本地跑了一个MCP Server里面注册了一个工具todo_add用户对AI客户端说“帮我记一条任务周五前完成项目周报”。第一步客户端启动时会跟Server建立连接完成握手交换双方支持的能力范围。这一步类似两个设备在蓝牙配对时互报型号和支持的协议版本。第二步握手完成后客户端会向Server询问“你能提供哪些工具”拿到工具清单包括工具名称、参数定义、描述信息。这个清单会影响后续大模型生成调用请求时的判断依据。第三步用户输入“帮我记一条任务周五前完成项目周报”后Host会把这句话连同工具清单一起交给大模型。第四步大模型看到工具清单里有个todo_add参数里有title和due于是生成一个结构化调用请求相当于心里想“我应该用这个工具”并填好参数。第五步客户端拿到这个调用请求按照协议格式发送给ServerJSON-RPC消息里会标明要调用的工具名和参数。第六步Server执行真实逻辑把任务存入本地数据结构然后返回一个结果比如“已添加项目周报”。第七步客户端把结果回传给大模型模型根据这个输出组织一句自然语言回复给用户“好的我已经记下了周五前完成项目周报。”整条链路里大模型本身并没有执行工具它只负责根据工具清单做决策真正执行的是Server。这就是MCP与“把所有逻辑都写死在Prompt里”的本质区别。3. 动手搭一个可复现的MCP服务端理论讲得再多都不如跑一个Demo来得实在。下面我带大家从零搭一个最简单的MCP Server用Python写一个小工具并在支持MCP的AI客户端里注册使用。整个过程不需要深入研究协议细节也不需要写一堆样板代码因为官方Python SDK已经封装好了高层API几行代码就能把一个服务端跑起来。3.1 准备环境与项目结构建议使用Python 3.10及以上版本我自己长期用3.11类型注解方面会舒服很多。先建一个目录并安装官方MCP库终端里执行mkdir mcp-demo cd mcp-demo python -m venv .venv source .venv/bin/activate pip install mcp装完之后确认一下版本mcp --version如果能看到版本号说明环境和命令行工具都已就绪。MCP的Python SDK中提供了一个叫FastMCP的高层封装类它专门用来简化服务端开发。你不需要手工处理JSON-RPC消息只要注册几个函数它就会自动生成工具定义、处理参数校验和结果序列化。3.2 用FastMCP写第一个工具我在这里做一个极简的“个人待办管理”服务端。功能也不需要多一个新增待办一个查看清单足以演示MCP Server的核心机制。新建文件todo_server.py写入from mcp.server.fastmcp import FastMCP # 声明服务名客户端里会以此标识这个Server mcp FastMCP(todo-server) # 用一个简单的列表模拟数据库 todos: list[dict] [] mcp.tool() def add_todo(title: str, due: str ) - str: 向待办清单中添加一条新任务。 todos.append({title: title, due: due, done: False}) return f已添加{title} mcp.tool() def list_todos() - list[dict]: 列出当前全部待办任务未完成的排前面。 todos.sort(keylambda item: item[done]) # 未完成的排前面 return todos if __name__ __main__: # 默认走 stdio 传输本地客户端用管道通信 mcp.run()这段代码里值得注意的有几个点。mcp.tool()装饰器会把被装饰的函数自动注册成MCP工具。函数的名称、docstring、参数签名都会被转成标准的工具定义供客户端发现。所以写函数的时候docstring一定要写清楚它会影响大模型判断什么时候该调用这个工具。类型注解也很重要。FastMCP会根据你的注解自动生成JSON Schema比如title: str会转成字符串参数due: str 会变成可选参数。如果你把类型写成int或者list生成的参数校验规则也会相应变化这一点在接复杂工具时尤其有用。3.3 在客户端里注册与调试服务端写好之后需要让一个AI客户端连接它。不同的客户端配置方式略有差异但大体思路一致客户端支持在配置文件中声明MCP Servers声明内容包括启动命令和参数。在某个支持MCP的AI客户端配置目录里找到类似mcpServers的配置段加入{ mcpServers: { todo-server: { command: python, args: [/absolute/path/to/todo_server.py], env: {} } } }这里有几个容易踩坑的细节需要注意。command不能只写python最好指定具体版本比如python3或者直接用虚拟环境里的解释器绝对路径。因为不同环境的默认Python指向不一定是同一个SSH、GUI应用的PATH跟终端往往不一样你终端里能跑客户端里未必能找到解释器。args里的路径建议写绝对路径。相对路径在不同工作目录下容易失效让我在这上面浪费过不少时间。MCP客户端启动Server的时候不一定会切到项目目录所以别依赖相对路径。写完配置后重启客户端。打开一个会话你应该能在工具列表里看到add_todo和list_todos两个工具。然后发一句“帮我添加一条周五完成周报的任务”模型如果判断正确就会自动调用add_todo并把参数提取成title周五完成周报。3.4 从stdio切换到HTTP传输默认的mcp.run()走的是stdio传输客户端会在本地启动一个Python进程通过标准输入输出跟它通信。这种方式对本地开发很友好但如果你想把MCP Server部署到远程或者同时给多个客户端提供服务就需要改成HTTP传输了。新版SDK里切换HTTP模式很简单if __name__ __main__: mcp.run(transporthttp, host127.0.0.1, port8000)启动后会看到一个监听端口。客户端的配置就不再是commandargs而是直接填URL一般是类似http://127.0.0.1:8000/mcp的形式。远程部署的时候还得加鉴权常见做法是放在网关后面或者用API Key中间件。不过鉴权的实现跟具体框架强相关MCP本身不做硬性约束身份验证就交给更擅长的东西去管。4. 连接外部数据与工具的安全边界与权限模型只要涉及“让模型调函数、让模型读数据”就必然要面对安全边界问题。MCP在这方面沿用了“最小权限”的朴素思路不是Server能做什么就暴露什么而是客户端只把它被允许做的暴露给模型。很多人以为接入MCP就像给模型开了一条超级通道其实并不是这样。4.1 工具权限是使用者的显式授权不是服务器的恩赐一个典型的误区是只要Server进程能访问某个系统文件模型就能读。实际并非如此。模型能调用哪些工具、能读哪些资源取决于这个Server向客户端暴露了什么。如果你在代码里只注册了add_todo模型根本不知道你服务器上还跑着一个数据库更不可能去操作它。工具本身的参数校验也需要自己把关。MCP协议会把参数传给函数但“参数是否合法”“值是否在允许范围内”完全看业务层实现。比如一个工具可以接收任意路径模型生成的路径可能不在预期目录下如果业务代码不做沙箱限制就会被撞到不该碰的地方。别把安全寄托在模型不会乱猜上要在Server端做好边界校验。这也是我在这个项目里反复提醒自己的一点模型只是入口防火墙在业务代码里。4.2 Resources如何管理外部数据MCP里的Resources抽象是把“外部数据”变成模型可读取、可引用的一种标准化方式。你可以把一个业务系统的数据通过Resource形式暴露模型需要的时候不是去执行一次“取数”工具而是直接“读取”这个资源。这样做的好处是权限模型更清晰。工具适合执行有副作用的动作比如写库、调API、发通知资源适合做只读的数据获取比如查当日报表、读客户资料。两者在语义上分离大模型在决策时也会区分需要动手就找工具需要了解情况就翻资源。在实际实现里资源可以声明为静态内容也可以通过回调动态生成。动态资源的逻辑有点类似网站的动态路由客户端请求的URI里带参数Server根据参数读取对应数据并返回。这样一份资源定义就能覆盖一批同类数据访问需求。4.3 最小权限原则的落地建议在MCP服务端设计时我习惯分成三步来做权限规划按场景拆分Server不要把“查天气”和“删订单记录”放在同一个Server里。连接越广模型的选择面越大误调的概率也越高。工具命名要体现作用范围比如read_sales_data比db_query要清晰得多大模型通过名字和描述就能判断何时用也减少误调用。不要滥用root或最高权限账号。Server进程用什么身份运行直接决定了它能触达哪些系统资源。注意MCP Server的权限范围取决于你的业务代码和启动用户而不是协议自动给的。凡是模型能接触到的能力都应当经过“这个能力如果真的被误调后果是否可接受”的评估。5. 常见问题与排查技巧实录写MCP Server不难难的是连接后的调试。因为MCP Server往往是被客户端进程拉起来跑的你看不到终端输出不能用print慢慢看很多问题就像在瞎子里摸象。我把实际项目中遇到的高频问题整理成一份速查基本都是可以直接对着症状抄作业的内容。5.1 客户端一直说找不到工具这是最典型的问题。代码明明写了mcp.tool()配置也写了客户端启动后却看不到任何工具。大多数情况下问题出在服务端进程根本没有被正常拉起来。拿stdio传输来举例客户端是通过执行command和args启动你的Python脚本然后用管道跟它通信的。如果脚本启动失败比如路径写错、某个依赖没安装、虚拟环境不对客户端那边通常只会收到一个空列表不会告诉你具体原因。这时候第一件事不是改配置而是手动在终端里执行一遍python /absolute/path/to/todo_server.py如果脚本能保持前台运行不退出那说明基本环境没问题。然后再检查你启动这个终端用的Python解释器跟客户端配置里command指向的解释器是不是同一个。很多时候解决方式就是换用虚拟环境里的绝对路径/Users/xxx/mcp-demo/.venv/bin/python /Users/xxx/mcp-demo/todo_server.py这种写法的确定性高得多。另外提一句修改了配置之后必须重启客户端很多客户端只在启动时读取并拉起MCP Server。我试过几次改完代码不重启、反复刷新界面都没反应最后被这个问题浪费时间。5.2 工具调用后立刻超时或崩溃Client能找到工具说明握手已经成功。但调用后超时或者客户端直接报错问题往往集中在工具函数本身。比如我早期在一个Server函数里忘了处理异常传入了空列表就执行下标访问结果进程直接退出客户端那边感知到连接中断报错信息很笼统。工具函数里务必加好异常捕获和返回值规范。无论内部发生什么至少返回一个描述性的字符串不要让异常抛到进程边界。MCP协议对结果格式有一定要求但业务错误尽量转成普通返回值。这不仅能避免进程崩溃也能让大模型更好地理解发生了什么进而向用户转述。调用本地文件、数据库这类有状态资源时还要考虑Server状态会不会被多个会话共享。如果客户端同时打开多个会话窗口同一份Server进程会被复用变量里存的数据是共享的。如果你希望每个会话独立就要在Server代码里维护会话级别的隔离逻辑。5.3 日志与调试技巧stdio模式下最让人头疼的就是print污染问题你在Server代码里打一句print(hello)这个输出会混进协议通道直接导致消息解析失败。所以调试不能用print。我用得最顺手的方式是写日志到文件Python自带logging模块就能解决import logging logging.basicConfig( filename/tmp/mcp-server.log, levellogging.DEBUG, format%(asctime)s %(message)s, )在工具函数里加一句logging.info(tool called with title%s, title)然后另开一个终端用tail -f盯日志。这样既能看清调用参数又不会干扰协议通信。如果你嫌文件日志麻烦新版本SDK支持Transport层的可插拔组件但排查问题够用就行不必一开始就上比重过大的监控。配合日志我一般按这样的思路定位先确认Server有没有收到请求再看收到的参数长什么样最后看返回结果被客户端解析成什么。三步各打一段日志基本没有查不出来的问题。5.4 HTTP模式的排查差异如果用的是HTTP传输排查方式会稍微不一样。因为进程是独立启动的你可以直接在终端跑Server看到所有访问日志。也可以用curl手动发JSON-RPC请求来验证工具是否注册正常。HTTP模式下的性能问题更明显。默认的SDK实现是同步的多个客户端同时调用会相互排队。如果后续并发量上来可以用异步模式或者多进程部署。不过对大多数内部工具场景来说同步模式完全够用不用过早引入复杂方案。还有一点HTTP模式默认监听127.0.0.1如果你的客户端跑在同一台机器上就没问题。想把服务暴露到别的主机要让监听地址和防火墙规则都匹配。我通常建议在开发阶段严格回环地址有跨机器需求时再通过内网域名访问而不是直接裸奔到公网地址。6. 这套协议对我的日常开发到底改变了什么写到这里如果只能用一句话总结MCP的价值我会说它把“工具连接”这个原本需要为每个应用定制的事情变成了一个通用基础设施。过去是每个AI应用各自实现一套“外设驱动”现在有了统一的接口标准工具开发者只管实现一份服务端协议就能被任何MCP兼容的AI客户端使用。这种变化对两类人最有价值。一类是做内部系统联调的人不需要再把一堆工具定义硬塞进Prompt里也不用手写结果回填逻辑了。另一类是工具提供方只要把API包成MCP Server就能被多个消费端使用不用针对每个厂商分别适配。我自己的体会是刚上手MCP的时候最痛苦的是转变思路不要再想“我该怎么让模型理解我的API”而是想“我该怎么把API设计成一个符合协议的Server”。思路一转过来后续开发就顺了。如果你打算把这套方案用到实际项目里第一个Demo建议从小处做起。不要一开始就想着接ERP、全量数据库先挑几个副作用小、逻辑清晰的功能比如搜索、待办、信息查询跑通整条链路再逐步加复杂工具。协议本身不难难的是边界划分和权限设计是否想清楚。只要把这个地基打好后续接多少工具都不会乱。
阅读完成 · 觉得有帮助？
