大概是2026年了MCP早就不是新鲜词。但我发现一个很有意思的现象现在网上搜“MCP协议入门”翻来覆去就是那老三篇——告诉你MCP是Model Context Protocol是Anthropic提出的能连接大模型和外部工具。看完吧脑子里留下三个字母真到自己搭一个server或者接入Claude Code、Cursor的时候照样卡壳。所以这篇算是“入门补丁包”把那些入门教程默认你懂、但实际操作时一定会踩的东西讲清楚。我尽量不重复基础概念重点放在MCP到底站在哪一层、消息是怎么跑的、三个核心原语怎么区分、怎么真的把一个server跑起来以及几个特别容易翻车的细节。适合已经看过一遍MCP基础介绍、准备动手实操的人刚接触的读者也能靠这篇少走弯路。另外先纠个题外话MCP里的P就是Protocol所以“MCP协议”是个叠字表达但大家都这么搜、这么念约定俗成就别较真了。下面我统一用“MCP”称呼它。1. 先搞清楚MCP解决的是什么问题——不然连“在哪里用”都拎不清好多人学MCP上来就背定义“模型上下文协议”背完还是懵。我说个更直白的理解在没有MCP之前一个AI应用想调用外部工具比如查天气、查数据库、操作浏览器每对接一个工具就要写一套接口逻辑。工具方要适配每家AI应用AI应用要适配每个工具N乘M的对接矩阵越来越乱。MCP干的事就是把这道对接矩阵压扁成“NM”工具方只需要实现一个MCP ServerAI应用只需要有一个MCP Client两边按统一协议说话就能互相理解。这很像USB-C口统一了充电线你不需要给每台设备带一根专用线了。协议解决的是“标准”问题不是某一个具体功能问题。1.1 MCP的三层角色Host、Client、ServerMCP体系里只有三个角色Host运行AI大模型的应用比如Claude Desktop、Cursor或者你自己的Python程序。Host是用户直接接触的那一层。ClientHost内部与Server建立会话的组件负责把Host的请求翻译成MCP协议消息再把Server的响应翻译回去。Server暴露工具、资源、提示词的一方背后可能是数据库、文件系统、蓝湖设计稿、浏览器DevTools等等。一句话概括Host是你Client是翻译Server是干活的。实际使用中Client和Host通常在一个进程里你不需要单独启动Client需要单独启动的是Server。这个划分一定要先记清楚因为后面所有配置、调试都围绕它。很多人搞不清“为什么我的工具没反应”最后发现是Server没启动、或者Host根本连不到Server。我见过不只一次工具列表为空是因为配置的command路径不对Server压根没起来跟协议本身一点关系没有。1.2 MCP和Modbus、MQTT、SPI那些“协议”不是一回事再澄清一个网上讨论很多的话题。热搜词里同时出现了Modbus、MQTT、CAN、SPI、IIC、Ymodem这些词经常有人问“MCP和MQTT哪个好”。说实话这俩压根不是一个维度。MCP是应用层协议运行在AI应用和工具服务之间走的是现代开发环境常见的stdio或HTTP通道。Modbus、MQTT是物联网/工业设备领域的数据传输协议解决的是设备怎么把数据发到网关或平台的问题。SPI、IIC是芯片之间的硬件总线协议比网络协议更低层。放在OSI模型里SPI/IIC偏物理层和数据链路层MQTT/Modbus偏应用层但面向设备MCP面向的是AI Agent的工具调用。强行拿MCP和MQTT做比较就像问“普通话和公路哪个更好”。MCP的Server一般跑在PC、服务器或者云主机上就算要对接IoT设备也是MCP Server去调MQTT网关让AI通过网关再控制硬件而不是让设备直接说MCP。搞清楚这个问题能帮你避免选型方向错误。2. JSON-RPC底座与消息传输方式理解消息格式比抄代码更重要不少教程会把MCP描述得很玄乎其实剥开外壳它就是基于JSON-RPC 2.0的应用层协议。所有MCP消息都是JSON格式的请求-响应报文——这意味着你抓到的每一条消息都能对照JSON-RPC规范去读排错时有章可循。2.1 JSON-RPC 2.0的基本报文格式一次标准调用长这样{ jsonrpc: 2.0, id: 1, method: tools/call, params: { name: get_weather, arguments: { city: 上海 } } }响应是{ jsonrpc: 2.0, id: 1, result: { content: [ { type: text, text: 上海晴28度 } ] } }理解这个格式很多概念就通了。比如“工具调用”不是什么魔法就是一条method为tools/call的消息一个JSON-RPC的id发出去了却等不到对应响应客户端就会超时一个方法名拼错了返回的就是method not found。入门阶段掌握这一个心智模型就够了MCP协议本质是一套规定的“请求-响应词汇表”方法名、参数结构都已经被协议定义好了你只是把参数填进去。2.2 stdio、SSE、Streamable HTTP三种传输方式消息格式统一了接下来是消息怎么传。MCP支持三种传输方式stdioServer作为子进程通过标准输入输出传JSON-RPC消息。本地开发最常用配置简单不用开端口。SSEServer-Sent Events基于HTTP的单向推送通道配合客户端发起的POST请求构成双向通信。早期远程Server的主流方案。Streamable HTTP较新的方案在普通HTTP上实现了流式响应和双向消息目前官方推荐用于生产环境的远程通信。本地搭demo用stdio就够了一条命令就能拉起ServerHost自己管理进程生命周期。远程部署再考虑HTTP方式。我在局域网里试过把Server部署在一台NAS上、客户端在笔记本上跑用HTTP做远程MCP延迟主要取决于你调用的工具本身协议开销并不大。如果只是个人玩本地stdio完全够用别为了“看起来专业”强行上HTTP。2.3 初始化握手先打招呼再干活MCP还有个容易被忽略的阶段——初始化握手。Client连上Server后第一件事不是调用工具而是发一条initialize请求交换协议版本和双方能力Client - Server: initialize Server - Client: 协议版本、服务端能力列表 Client - Server: initialized 通知握手完毕才能继续发tools/list、resources/list这些请求。这个机制解释了常见的怪问题“我明明配好了Server工具列表却是空的”——八成是握手阶段就挂了。排查的时候先看Server日志有没有收到initialize再看返回的版本号是否兼容要比直接在工具列表上找原因高效得多。我自己的习惯是配好Server后第一眼不看UI先看启动日志输出日志里通常会把握手失败的原因直接写出来。3. Tools、Resources、Prompts三兄弟入门最容易混淆的概念MCP Server能往外暴露三类东西协议里叫“原语”Tools、Resources、Prompts。入门文章提过三者的名字但讲清区别的很少。分不清它们写Server的时候就会纠结“我这个功能到底该暴露成工具还是资源”。3.1 一张表看懂三者的区别原语作用调用方典型例子Tools工具执行动作对世界产生副作用AI模型主动调用查询数据库、发邮件、创建文件Resources资源提供只读数据上下文Client或AI按需读取项目文档、配置文件、数据库SchemaPrompts提示词模板提供可复用的交互模板用户或Client触发按周报模板总结本周工作简单记忆法Tools是“手”会干活、有副作用Resources是“书”只读、供查阅Prompts是“剧本”给出固定格式的对话开场。三者在Server端都是注册式的各自的声明方式不同但在客户端看来都是“能力清单”里的一项。举个具体的例子帮助理解假设你做一个运维MCP Server。把“查询服务器CPU使用率”做成Tool因为AI要根据不同IP去动态查询把“服务器清单、告警规则说明”做成Resource因为AI需要这些背景信息来理解业务把“故障排查流程”做成Prompt用户点一下就能让AI按标准流程走一遍。同一个Server里三类原语覆盖了“查、读、走流程”三个不同需求。3.2 为什么很多人把Tools和Resources搞混一个典型的混淆例子是文件读取。有人说“AI要读文件那文件就是Resources”。但你要让AI自己决定读哪个文件、读完返回内容这个动作其实更适合做成Tool因为读取哪个文件是个动态参数返回值也是个动态结果这正好命中Tool的“动态、带参、有返回”特征。而Resources适合暴露相对静态的内容比如项目的README、代码规范说明、固定的配置模板。AI在需要了解背景时把它作为上下文读入内容基本不变也不需要传参。我自己的判断标准很简单如果这个数据内容是“给模型看的背景资料”用Resources如果是“要让模型干的一件具体事”用Tools。实在拿不准先做成Tool因为Tool的使用场景更广。3.3 Prompts在MCP里的定位Prompts跟前两者不太一样它更像给Host用的快捷指令。比如你定义了一个“项目巡检”Prompt用户在主界面选中它Host就会把对应的模板和上下文塞给模型。实际用得好的场景是固定输出格式比如周报、缺陷单、会议纪要。AI拿到的是一套结构输出自然稳定。很多本地调试工具比如Claude Desktop还没完全开放Prompts入口所以Server里有Prompts一时看不到效果是正常的不代表你写错了。我见过有人以为Prompts没生效删了重新写白折腾半天。判断Prompts有没有写对直接用官方Inspector看返回的prompts列表即可比在客户端里盲试高效。4. 半小时搭起第一个MCP Server Demo附完整可跑通的代码理论讲再多不如亲手跑一个。这部分我用Python官方SDK给你一个最小可用的MCP Server包含工具、资源、提示词三类内容。你在本地跑通它后面接Claude Code、Cursor就顺了。4.1 准备环境我的环境是Python 3.11macOS。Windows下同样适用命令差别不大。先建虚拟环境装官方SDKmkdir mcp-demo cd mcp-demo python -m venv .venv source .venv/bin/activate # Windows下用 .venv\Scripts\activate pip install mcp[cli]注意老教程会教你装mcp这个包然后还要单独装mcp-server、fastmcp之类的那是早期版本拆分太乱导致的。现在官方推荐单包安装直接用FastMCP的封装接口写代码量少得多。如果装的是很老的版本建议先升级到最新版再继续。4.2 Server端代码新建server.pyfrom mcp.server.fastmcp import FastMCP # 创建MCP Server实例name会在客户端工具列表里显示 mcp FastMCP(my-demo-server) mcp.tool() def add(a: int, b: int) - int: 计算两个整数的和注意只支持整数。 return a b mcp.tool() def search_files(keyword: str, path: str .) - list: 在指定目录下搜索文件名包含关键字的文件。 import os results [] for root, dirs, files in os.walk(path): for f in files: if keyword in f: results.append(os.path.join(root, f)) return results[:20] mcp.resource(docs://guide) def get_guide() - str: 返回一份项目使用说明供模型阅读。 return ( 这是一个MCP演示服务。可用工具add整数加法、 search_files按文件名关键字搜索。 ) mcp.prompt() def weekly_report(name: str, done_items: str) - str: 生成周报模板。 return f# {name}的周报\n\n完成事项\n{done_items}\n\n下周计划\n if __name__ __main__: # 本地调试用stdio传输 mcp.run(transportstdio)是否觉得很短这就对了。FastMCP把协议细节封装掉了你只需要声明函数、写清docstring和类型注解。docstring尤其重要因为模型是根据docstring和函数签名来决定“什么时候调用这个工具、传什么参数”的。写得模糊AI就乱调或者不调——这是我在实际项目里反复体会到的。4.3 用MCP Inspector调试Server写完后别急着接到客户端先用官方调试工具验证npx modelcontextprotocol/inspector python server.py浏览器会打开一个调试面板。在面板里可以看到协议握手是否成功工具列表里有没有add和search_files手动调用某个工具直接看返回结果资源列表和提示词列表这一步极其值得养成习惯。MCP Server的问题十有八九出在函数签名、docstring、返回格式上Inspector能让你在客户端介入之前就把问题定位掉。我见过太多人跳过这一步直接去配置Claude Code结果一报错排查链路长到怀疑人生。先用Inspector把Server本身验证干净再接客户端问题面一下就缩小了。4.4 一个常见坑docstring写得太短很多人写MCP Tool时函数名、参数名都有但docstring只写一句“add two numbers”。模型理解能力有限它需要在docstring里知道“这个工具干什么、参数含义是什么、有没有副作用、什么时候不该用”。实践下来docstring多写两句模型调用准确率会有肉眼可见的提升。比如上面search_files的docstring我特意写了“按文件名关键字搜索”因为如果不强调“文件名”模型很可能以为它能搜文件内容。这种语义歧义是工具设计里最常见的坑。另一个技巧是给函数参数加默认值模型拿不准的时候会倾向用默认参数去调用而不是直接放弃。5. 在Claude Code和Cursor里验证你的MCP服务配置与排坑Server跑通了接下来是把它接到真实客户端里看效果。这也是热搜词里最大的一类需求尤其集中在“Claude Code安装MCP读取数据库”“Cursor连接蓝湖MCP”这些具体场景。5.1 通用的客户端配置方式Claude Code和Cursor目前都支持通过JSON文件声明MCP Server核心字段是command、args和env。以刚才的demo为例在Claude Code里一般在项目根目录的.mcp.json或者全局配置里写{ mcpServers: { my-demo-server: { command: python, args: [server.py], env: {} } } }一个极其容易踩的坑command里的可执行文件必须用绝对路径。如果写的是“python”而系统里有多个Python版本客户端拉起的进程很可能不是你虚拟环境里的那个。稳妥做法是把Python解释器的绝对路径填进去。用which python或where python查一下就知道。{ mcpServers: { my-demo-server: { command: /Users/yourname/mcp-demo/.venv/bin/python, args: [/Users/yourname/mcp-demo/server.py] } } }启动后在Claude Code里敲/mcp能看到Server状态变成connected在Cursor的设置MCP列表里同样能看到。状态显示failed时先看进程能不能在shell里手动跑起来再回头看配置里的绝对路径和环境变量大部分问题出在这两块。5.2 Claude Code连数据库的实操思路热搜词里有“claude code 安装mcp读取数据库”这个场景很有代表性。其实你不需要去现成市场找一个数据库MCP自己写一个小Server往往更贴合需求。核心思路在Server里暴露一个query工具内部用SQLAlchemy或pymysql连数据库把查询结果以文本形式返回。为了安全建议只开放只读查询或者把工具封装成“按表查前N行”“执行预编译SQL”不要让模型随便拼接SQL。mcp.tool() def query_table(table_name: str, limit: int 10) - str: 查询指定表的数据最多返回limit行。只允许SELECT。 import re, json if not re.fullmatch(r[a-zA-Z_][a-zA-Z0-9_]*, table_name): return 非法表名 with get_connection() as conn: with conn.cursor() as cur: cur.execute(fSELECT * FROM {table_name} LIMIT %s, (limit,)) rows cur.fetchall() return json.dumps(rows, ensure_asciiFalse, defaultstr)这里最关键的是两层约束第一层工具函数内部强制只读第二层表名用正则白名单校验防止注入。模型再智能你也不能把数据库裸奔给它。这类安全设计在入门资料里很少被强调但生产环境必须做。顺带说一句如果你要连的是带密码的库密码千万别写进args里用env传更稳妥。5.3 Cursor连蓝湖、Figma这类“MCP生态”怎么看热搜词里“cursor连接蓝湖mcp”“figma插件open figma mcp”指向的是另一类玩法设计协作平台自己推出MCP Server让你能通过AI直接读取设计稿、生成前端代码。蓝湖、MasterGo都有官方MCP服务。Unity、Blender、Cocos Creator这些专业软件也陆续出了MCP插件说明MCP生态已经从“AI工具圈”扩散到专业软件领域了。这类现成MCP Server的接入方式和自建几乎一样区别只是Server跑在对方云上。配置时需要获取一个API Token写到env环境变量里{ mcpServers: { lanhu: { command: npx, args: [-y, lanhu/mcp-server], env: { LANHU_API_TOKEN: 你的token } } } }接入后你在Cursor里让AI“把蓝湖第X页设计稿还原成页面”AI会通过MCP工具去拉设计稿数据再生成代码。整体感受和本地MCP一致只是背后走了网络请求。注意token的权限范围别把有写权限的token直接配给本地客户端。我在实际项目中见过token被翻开后被人恶意修改设计稿的情况权限最小化是必须养成的习惯。6. MCP与Computer Use的区别两条不同的路别混为一谈热搜词里还有个高频疑问computer use和mcp的区别是什么。这个确实值得单独说说因为不少产品宣传把两者混在一起讲。6.1 一句话区分MCP是“给AI一个标准接口去调用工具”本质是代码到代码的协议通信。Computer Use是“让AI像人一样看屏幕、点鼠标、敲键盘”本质是视觉识别加操作系统交互。打个比方MCP像你给AI一把钥匙AI直接开门进房间里拿文件Computer Use像AI透过监控摄像头看你的屏幕学着用手操控电脑。前者高效、精准、需要工具方配合后者笨重但泛化不用等任何工具方适配就能操作任意软件。6.2 实际场景里怎么选如果你的目标是“让AI查询内部数据库、调用公司API生成报表”别用Computer Use直接上MCP效率高一个量级。如果目标是“让AI帮忙操作某个没有API的遗留桌面软件”Computer Use是唯一出路。两类技术不是替代关系而是按场景互补能用协议的走协议协议覆盖不到的地方再让AI“看屏幕操作”。现在很多Agent产品里两者会同时存在MCP负责高可靠的核心操作Computer Use兜底那些“没接口也要硬上”的场景。我在做一个流程自动化项目时70%的步骤走了MCP剩下30%的系统没有对外接口只能用Computer Use。理解这一层你做技术选型时就不容易被宣传话术带偏。6.3 选型时的三个判断问题如果还是拿不准问自己三个问题这个系统有没有公开API或者命令行接口有走MCP没有考虑Computer Use。操作对精度要求高不高比如财务系统录入差一位数都不行走MCP如果是浏览页面、翻资料这种容错高的场景Computer Use可以接受。你希望AI操作的是黑盒软件还是白盒数据白盒数据优先MCP黑盒界面只能Computer Use。这三个问题基本能帮大多数人做决定。至少我遇到的场景还没有超出这三个问题的边界。7. 容易被遗漏的三个细节采样、Roots与传输层安全最后补几个入门教程几乎不讲的冷门点到中后期一定会碰到。7.1 采样能力让Server反过来请求模型MCP协议里有个叫做sampling的扩展能力允许Server在运行过程中向Client发起“帮我把这段内容交给模型生成回复”的请求。典型场景是工具执行到一半发现需要模型判断结果于是把上下文回传给模型拿到回复再继续。这个设计让MCP不只是单调的“模型调工具”还能“工具问模型”。比如一个代码评审工具扫描完代码后请求模型给出修改建议再把建议写回PR整个流程闭环。不过采样能力默认通常是关闭的因为涉及模型调用成本和权限问题需要Client端显式授权。如果你发现Server里写了sampling相关代码但在客户端不生效先检查客户端的权限配置。7.2 Roots限定工具的“管辖范围”Roots是客户端告诉服务器“你只能访问这些目录/资源”的机制。比如你在Claude Code里打开/project/backendMCP客户端会把后端目录作为root传给数据库Server或文件Server。设计上Server应该检查所有路径是否落在root范围内防止AI通过工具去读项目以外的文件。如果你自己写文件类MCP Server记得实现这个检查。别觉得多余模型没有天然的路径边界感你在对话里让它读其他项目文件它真敢去读。Roots就是给模型套上缰绳让所有工具调用都限制在用户授权的范围内。7.3 传输层安全本地靠进程隔离远程靠TLSstdio模式下Server是Host拉起的一个子进程通信不经过网络安全性靠操作系统进程隔离来保证。但如果把MCP Server部署到远程走HTTP传输那就必须上TLS否则工具调用内容等于明文裸奔。这里顺便回应一下热搜词里的“ssl/tls协议信息泄露漏洞(cve-2016-2183)【原理扫描】”——这是另一个维度的问题说的是TLS协议本身被扫描到的老版本加密套件风险跟MCP无直接关系但提醒我们任何走HTTP的远程MCP服务上线前都要做一次TLS配置检查禁用弱加密套件别给中间人留机会。8. 额外补两个经常被问到的高频实操问题最后补充两个热搜里出现频率很高、但我看过的入门文章很少展开的点。8.1 Skills如何调用MCP工具先分清“思考流程”和“执行动作”“skills如何调用mcp工具”这个问题我在好几个社区都看到过。这里的skills通常指的是Claude Code等产品里的“技能”功能比如自定义指令集合。它和MCP确实存在功能重叠的部分skills管“怎么思考”MCP管“能做什么”。理解方式skills是给模型的提示词和流程模板告诉它在这种场景下先做什么、再做什么、输出格式长什么样MCP是给模型的实际动作工具让它能真正执行查询、调用、修改。一个项目里skills和MCP经常会搭配使用skill定义流程流程里涉及具体动作时模型去调MCP工具。所以“skills如何调用MCP工具”这个问法更准确地说应该是“如何在自定义skill的指令里指定让模型去调用某个MCP工具”。操作上你不需要写代码只需要在skill的指令文本里写明“完成这一步时调用xxx工具传入yyy参数”模型读到指令后会自己完成调用。这个配合默契度取决于你对工具能力的描述是否清晰跟我前面强调的docstring质量是同一个道理。8.2 MCP Server的选型参考SDK封装和自写JSON-RPC怎么选另一个高频问题是Server该用什么写。官方SDK有Python和TypeScript两套都提供FastMCP这种高层封装绝大多数场景用它们就够了。我自己常用Python版因为它对数据类工具友好pandas、SQLAlchemy生态直接就能用。但我也见过有人直接在代码里实现JSON-RPC接口不依赖官方SDK。这在Server要嵌入到已有服务时挺合理比如你的工具本来就是个Spring Boot服务直接在服务上加一个MCP端点就行不用再单开一个进程。这点对于“matlab mcp”“solon ai mcp springboot”这类场景尤其实用——老系统不需要推倒重来在现有进程里暴露一套协议端点即可。FastMCP封装虽香但要知道它替你做了什么才能判断什么位置该用封装、什么位置该自己写这也是理解协议本身的价值所在。到这儿MCP入门阶段的隐藏知识点就补得差不多了。我个人的体会是MCP的价值不在于协议本身多高深而在于它把“AI调用外部能力”这件事标准化了生态从最初的Claude生态一路扩散到蓝湖、Unity、Blender、Matlab这些专业软件这本身就是标准的胜利。真正难的永远是工具设计、权限边界和场景抽象这些没有捷径只能一个个项目去磨。如果你正准备动手搭第一个MCP Server别纠结选型先用官方FastMCP跑通最小demo再围绕自己的真实场景去加工具这条路我替很多人验证过走得通。