最近很多做 AI 应用和工具链的朋友都在聊 MCP无论是 Trae、Cursor 这类编辑器还是 Figma、蓝湖这类设计协作平台都在往 MCP 上靠。热搜词里也经常出现“mcp是什么”“mcp server”“mcp协议”“figma mcp怎么运用在trae”这类问题。这篇就来把 MCP 的原理拆开讲清楚顺便带大家从零跑通一个 MCP Server把概念落到能用的代码上。MCP 全称 Model Context Protocol模型上下文协议。它要解决的核心问题是 AI 应用和外部数据、工具之间的连接标准问题。在没有 MCP 之前每个 AI 应用要接入一个工具几乎都得定制一套接口接文件系统写一套接数据库写一套接 Figma 再写一套开发和维护成本都很高。MCP 出现之后AI 宿主应用Host通过统一协议去发现和调用能力提供方Server暴露的工具和数据相当于给 AI 外设装了一个标准的 USB 接口。这篇文章适合谁看如果你在用 Trae、Cursor、Claude Desktop 或其他支持 MCP 的 AI 编程工具想接设计稿、浏览器、本地文件等能力或者你想给自己的产品做一个 MCP Server让别的 AI 应用能调用你的服务又或者你只是好奇这个被炒得很热的协议底层到底怎么工作这篇都能给你一个相对完整的答案。1. MCP 是什么一个让 AI 工具接上外部世界的通用协议1.1 背景为什么需要 MCPMCP 由 Anthropic 在 2024 年底开源推出。它的初衷是把大语言模型与外部工具、数据源的接入方式标准化。在它之前业界主要靠 Function Calling 让模型调用预定义的函数但函数调用通常由应用方自己实现、自己管理每个应用和每个工具之间都是一种点对点的定制关系。你可以想象成一个房间里堆满了各种充电线micro USB、Lightning、Type-C 各管各的MCP 做的就是那个统一成 Type-C 的事情。具体到实际开发里你会发现这几类问题几乎天天遇到模型本身没有实时数据大模型的训练数据有截止日期它不知道你数据库里最新的订单状态。模型不能直接操作工具模型能生成一段“调用搜索函数”的代码但真正去发起 HTTP 请求的还得是你自己的应用。接入一个工具就要写一遍胶水代码文件系统、GitHub、Slack、设计稿平台不同工具暴露能力的方式完全不同接入成本不可复用。权限和安全难以统一管理每次接入都要单独设计授权、作用域、审计方式。MCP 在架构上把 AI 应用拆成两个角色Host 是使用模型的宿主应用Server 是暴露数据和工具的服务端。中间通过一套标准协议通信这样同一个 Host 可以接任意 MCP Server同一个 Server 也可以被任意支持 MCP 的 Host 使用。这就是它最核心的价值一次接入处处可用。顺带说一句网上搜索“mcp原理”的时候经常会把计算机组成原理、编译原理、自动控制原理、粒子群算法原理、PCA原理这类完全不相干的话题混在一起它们只是共用了“原理”这个词。MCP 的原理不是那种硬件电路或算法数学层面的原理而是一个工程协议的机制设计读的时候注意区分。1.2 MCP 与 Function Calling 的区别很多人会把 MCP 和 Function Calling 混为一谈其实它们解决的是不同层面的问题。Function Calling 是模型层面的一种能力指模型在生成回复时能从你给出的函数列表中挑一个合适的函数输出结构化的调用参数。它解决的是“模型如何决定调用什么、传什么参数”的问题但函数本身由谁提供、怎么执行它不管。MCP 是应用层面的一个协议它解决的是“这些函数从哪来、怎么被发现、怎么被安全地调用”的问题。MCP Server 可以把它想要暴露的所有函数通过 tools/list 这个接口告诉 HostHost 再把它们整理成模型能理解的函数列表交给模型决定调用哪个最后 Host 通过 tools/call 让 Server 真正执行。两者的关系简单说MCP 是水管网络Function Calling 是水龙头。MCP 管道把外部世界的能力运到 Host 跟前Function Calling 负责让模型决定打开哪个水龙头。实际工程里MCP 底层往往就是借助 Function Calling 的能力来实现工具调用的。理解了这层你再看 MCP SDK 的代码会顺很多。1.3 MCP 的典型使用场景从目前社区的使用热度来看MCP 用得最多的是这四类场景第一类本地数据访问。让 AI 工具直接读写本地文件、SQLite 数据库、PDF 文档比如 DevSpace MCP、本地文件 MCP 就属于这类。第二类设计稿协作。Figma MCP、蓝湖 MCP 把设计稿的图层、标注、切图信息暴露给 AI编辑器里的 AI 能基于设计稿直接生成代码这也是热搜里“figma mcp怎么运用在trae”的现实背景。3D 方向的 Blender MCP 也是类似思路只是数据源变成了建模文件。第三类浏览器自动化。Playwright MCP 把浏览器控制能力暴露给 AIAI 可以打开网页、点击、输入、截图适合做页面测试和数据采集。第四类运维与测试工具链。比如 Codex 联动 Burp MCP 做接口安全测试、IDA MCP 做逆向辅助、Kettle MCP 做数据流程控制这类偏专业的场景也在快速起来。一个共同点这些场景都需要模型在“对话之外”获取信息或操作外部系统而 MCP 提供了统一的接入方式。1.4 MCP 的通信基本形态与适用人群MCP 的通信基本形态非常简洁底层是一条消息通道Host 和 Server 之间通过 JSON-RPC 2.0 格式的消息进行请求和响应。可以把它理解成两个进程之间走了一套 HTTP/RPC 风格的约定一边发请求一边回结果。由于消息格式统一理论上任何语言都可以实现 MCP官方也提供了 TypeScript 和 Python 的 SDK社区里 Rust、Go、Java 的 SDK 也都在跟进。适用人群方面我建议分三类去看如果你只是使用方想接别人写好的 MCP Server那重点看配置文件怎么写、权限怎么配原理知道个大概就够如果你是开发者要自己写 MCP Server 暴露业务能力那协议原理、生命周期、原语设计必须吃透如果你在做 AI 框架或平台想把 MCP 内嵌到自己的产品里那除了协议还要研究 Host 端能力协商、传输层实现、并发与安全策略这些是后面几节的深入内容。2. 核心架构拆解Host、Client、Server 三者的职责边界2.1 从一次调用看清三个角色为了不把架构讲成抽象名词我先描述一个具体场景你在 Trae 里装了 Figma MCP然后对 AI 说“按照设计稿第 3 帧实现这个页面”。这一刻发生了什么MCP Host 是 Trae 本身。它是用户直接面对的 AI 应用负责调用大模型、把用户意图转化成模型能处理的形式也负责管理所有 MCP 连接的配置和生命周期。MCP Client 是 Host 内部的协议客户端组件每个 Host 可以同时维护多个 Client每个 Client 对应一个 Server 连接。Client 负责把 Host 的意图翻译成 MCP 协议消息发给 Server再收回来。MCP Server 是提供能力的服务端Figma MCP Server 负责连接 Figma 的 API它通过协议的 tools/list 向 Client 声明自己有什么工具比如“获取设计稿图层”“读取选中节点”“导出切图”等。一次调用的粗略链路是这样的用户在 Trae 输入需求大模型发现需要了解设计稿信息Trae 里的 MCP Client 调用 tools/call参数里带上“获取设计稿图层”这个工具名和相关参数Figma MCP Server 收到请求去请求 Figma 官方 APIServer 把结果通过 JSON-RPC 响应返回给 ClientClient 把结果交给大模型大模型基于这些信息生成页面代码。整个过程模型不用知道 Figma API 的细节它只是通过 MCP 的标准化接口拿到了“它需要的信息”。2.2 一句话理解 Host有模型有对话界面的应用MCP Host 的定义其实很简单任何通过 MCP 向外部能力请求数据或工具的 AI 应用都可以叫 Host。它必须具备两个基础条件第一能调用大模型第二能承载用户与模型的交互界面。常见的 Host 有 Claude Desktop、Trae、Cursor、Zed、IntelliJ 的 AI 插件以及各类自研的 Agent 平台。Host 端的核心工作不只是转发请求。它还要负责管理 Server 的注册和配置、在启动时建立连接并协商能力、把 Server 暴露的 tools/resources/prompts 整理成语义给模型、把模型的调用意图映射到具体协议请求、处理错误和超时、维护安全边界。所以 Host 不只是一个壳它承担了协议交互中面向用户的那一层复杂性。2.3 MCP Client被很多人忽略的协议翻译层MCP 协议文档里专门定义了 Client 角色它和 Host 是分开的。Host 内部往往有一个连接管理器每连一个 Server 就实例化一个 Client。这个拆分在工程上很有意义Host 的界面和业务逻辑可以保持稳定新增一个 Server 只是新增一个 Client 连接不用改动上层。具体到 SDK 实现里Client 负责协议握手、发送初始化请求、维护会话状态、订阅服务端的能力列表并把收到的结果反序列化成 Host 能用的对象。你在配置里写 server 名字和启动命令Host 就会在内部创建对应的 Client 并启动连接。这也是为什么 MCP 的配置文件本质上是一张“Client 连接表”。2.4 MCP Server对外暴露能力的最小单元Server 端更灵活。它可以是本地子进程也可以是远端服务。关键是它要实现 MCP 协议定义的那几个核心方法initialize、tools/list、tools/call、resources/list、resources/read、prompts/list、prompts/get 等。一个 Server 不需要实现所有原语它只要把想暴露的能力声明出来即可。比如一个简单的天气 MCP Server可以只实现 initialize 和 tools/list、tools/call一个做知识库的 Server可能主要实现 resources 相关接口。协议允许“按能力协商”初始化时双方告诉对方自己支持什么后续只调用双方都支持的能力。3. 协议原理细节传输层、消息格式与生命周期MCP 原理性最强、面试容易被追问的部分基本都集中在协议层。我把三块拆开消息格式、传输方式、生命周期。3.1 消息格式JSON-RPC 2.0MCP 的协议消息基于 JSON-RPC 2.0这是一种轻量级的远程过程调用协议。你可以把它理解成一张标准化的快递面单里面要有 method要做什么、params参数是什么、id这是第几个请求、result 或 error结果或错误。一个典型请求长这样{ jsonrpc: 2.0, id: 1, method: tools/call, params: { name: fetch_design_file, arguments: { fileKey: abc123 } } }对应的响应长这样{ jsonrpc: 2.0, id: 1, result: { content: [ { type: text, text: 设计稿文件 abc123 包含 3 个图层... } ] } }用 JSON-RPC 而不是自定义二进制协议好处是调试成本低、跨语言友好。你可以直接在日志里看到双方发了什么出了问题一眼就能定位。坏处是 JSON 序列化和反序列化有一定性能开销但 MCP 的场景大多不是高频实时通信这个代价可以接受。MCP 在 JSON-RPC 基础上增加了一些约定不是所有消息都需要响应通知类消息不带 id所有由 Server 主动发给 Client 的消息比如日志、进度更新都走 notification 通道。3.2 传输层stdio 和 Streamable HTTP在具体传输上MCP 主要支持两类通道。第一类是 stdio。Server 以子进程方式启动Host 通过标准输入输出和它通信。配置里常见的写法是{ mcpServers: { local-files: { command: node, args: [path/to/server.js], env: { TOKEN: xxx } } } }stdio 方式最稳因为进程由 Host 拉起不存在网络端口、CORS、鉴权的问题适合本地工具类 Server。它的局限也很明显只能本机用不能跨机器调用。第二类是 Streamable HTTP早期版本里是 HTTP 加 SSE 的组合。Server 部署在远端Client 通过 HTTP 请求发起调用通过 SSE 接收服务的流式推送。适合把 MCP Server 做成一个对外服务让多个 Host 通过 URL 接入。配置里对应写成{ mcpServers: { remote-service: { url: https://mcp.example.com/mcp, headers: { Authorization: Bearer xxx } } } }选型上的经验是本地文件、单机工具、开发辅助优先 stdio跨团队共享服务、云端部署、需要统一鉴权审计走 HTTP。3.3 初始化握手与能力协商MCP 连接建立后的第一个动作是初始化握手。Client 会发一个 initialize 请求带上自己支持的协议版本和客户端能力信息Server 响应时返回自己支持的协议版本和服务端能力信息。然后 Client 再发一个 initialized 通知表示启动信息已经确认之后双方才进入正常的会话通信。握手过程中有个关键行为是版本协商。MCP 协议版本在迭代双方必须取一个都支持的版本。SDK 里通常会自动处理但你如果自己实现协议这一块容易踩坑比如 Server 说我支持 2024-11-05 版本Client 只支持更老的版本那就得升级或降级对齐。能力协商用到的字段大致如下{ protocolVersion: 2024-11-05, capabilities: { tools: { listChanged: true }, resources: { subscribe: true }, prompts: { listChanged: true } } }Server 在这里声明自己实现了哪些会话能力Client 会根据这个字段来安排后续请求。Handshake 没有做好后面再调用 tools/list 就可能出现“Server 不支持”之类的异常。3.4 生命周期从连接、会话到关闭一个完整的 MCP 连接生命周期大概是创建连接、初始化握手、能力协商、正常运行期、关闭连接。在运行期Host 可以不定期地重新调用 tools/list确认 Server 的工具列表是否变化。协议里通过 notifications/tools/list_changed 这个通知让 Server 主动告知 Client“我的工具列表变了请你刷新。”实际开发中如果你在 Server 里动态注册了新的工具记得在注册完成后发这个通知否则 Host 端一直在用旧的工具快照新工具永远不会被发现。会话状态需要 Client 维护因为 HTTP 场景下请求是无状态的MCP 在协议层通过会话标识来关联同一连接内的多次消息。如果你自己实现 Server要特别注意会话的处理握手成功后生成 session后续请求都带着这个 session关闭时再做清理。4. 四大原语原理Tools、Resources、Prompts、SamplingMCP 的核心设计亮点在四大原语。理解这四样你基本就掌握了这个协议的扩展思路。4.1 Tools让模型能动手做事Tools 是 MCP 里最常被使用的原语。它的定位是“动作”即让模型能够主动去执行某个操作。一个 Tool 有三个要素名称、描述、输入参数的定义。名称和描述会直接影响模型能否正确选中它所以命名要明确描述要写清楚使用场景参数定义用 JSON Schema 描述。示例定义一个获取天气的 Tool{ name: get_weather, description: 根据城市名查询实时天气信息适合回答今天北京天气怎么样这类问题, inputSchema: { type: object, properties: { city: { type: string, description: 城市名称如北京、上海 } }, required: [city] } }模型看到这个定义后会在需要时发起 tools/call。Server 收到调用后执行真实逻辑再把结果以文本、图片或资源内容等形式返回。工具调用的返回内容里可以包含多条 content每条有 type 字段text 是普通文本image 是图片。我在本地写过不少 MCP Server一个很深的体会是工具描述写得好不好直接决定模型调用准确率。描述里应该包含触发场景、参数含义、返回内容概览。如果你只写三五个字模型很容易在多个相似工具之间选错。4.2 Resources把数据暴露给模型读Resources 的定位是“数据”。它让 Server 能把一些稳定的、可读取的数据暴露给模型。可以理解为一组“可读文件”每个资源有 URI 和 MIME 类型比如 file:///config.json、figma:///frame/xxx。模型或用户可以通过读取资源来获得某类上下文信息。resources 和 tools 的区别我习惯这样记tool 是动词resource 是名词。用户问“当前项目目录下有什么文件”那是一个资源列表用户说“帮我读一下 config.json 的内容”那是一次资源读取用户说“把这几个文件内容整理成摘要”模型才需要去遍历资源而真正做文件操作比如改写文件那就需要工具了。resources/list 返回资源清单resources/read 返回具体内容。在知识库类 MCP 场景通常用 resource 来暴露文档目录用 tool 来实现检索和写入。4.3 Prompts可复用的提示词模板Prompts 原语解决的是“重复性指令怎么写”的问题。Server 可以提供一批提示词模板模板里有变量占位符Host 或用户可以在合适时机填充变量、生成完整提示词。这在需要固定流程的场景里很实用比如“代码评审”“SQL 生成”“PDF 摘要”。一个 prompt 定义大致是{ name: code_review, description: 生成一段代码审查摘要的提示词模板, arguments: [ { name: filePath, description: 要审查的文件路径, required: true } ] }Host 调用 prompts/get 拿到模板内容后可以把模板内容拼到对话上下文中。这个原语不像 tools 和 resources 那么高频但在构建企业内部 AI 流程时很实用它能把团队的评审规范、编码风格固化下来。4.4 Sampling让 Server 反向请求模型Sampling 是四大原语里最特殊的一个。它允许 Server 在会话中反向请求 Host“请帮我调用一次模型补全结果用于我的内部逻辑。”这在某些场景下非常有用比如一个 Server 需要针对用户的输入做语义判断才能决定返回什么数据。实际工程中Sampling 的使用频率远低于前三个原语而且因为涉及安全问题Server 在请求模型时可能消耗 Host 的额度也可能绕过用户意图很多 Host 默认不开放或需要用户授权。我建议在自己实现 Server 时先不要依赖 Sampling能用 tool 和 resource 解决的就不要引入反向请求。4.5 如何选用原语一个判断清单我给自己定过一个选择清单分享出来供参考如果模型需要执行一次性操作比如发请求、改文件、查数据库用 Tool。如果模型需要持续读取一类结构化数据作为上下文用 Resource。如果需要把一段固定的高质量指令按变量复用用 Prompt。如果 Server 自己需要模型推理能力才能完成逻辑才考虑 Sampling同时确认 Host 支持并授权。5. 实操手写一个最小 MCP Server 并在本地跑通原理讲再多不跑一遍很难真正建立感觉。这节从零开始带你写一个能用的 MCP Server并在本地客户端里跑通。5.1 环境准备与选型我选 TypeScript 官方 SDK因为生态最完整。你需要先安装 Node.js 18 以上版本然后初始化项目mkdir my-mcp-server cd my-mcp-server npm init -y npm install modelcontextprotocol/sdk如果你想用 Python官方 SDK 是pip install mcp实现思路一样。下面我以 TypeScript 为例因为社区里绝大多数现成 Server 都是 TS 写的你后续读别人的代码也更容易。这个示例是最小演示实现SDK 的具体 API 会随版本微调但整体结构和概念是稳定的。5.2 用 SDK 实现一个文件读取工具我们写一个最简 Server暴露两个能力读取文件内容、列出目录下的文件。代码里最关键的是创建一个 server 实例用server.registerTool注册工具然后调用connect建立传输。import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; import fs from fs/promises; const server new McpServer({ name: local-files, version: 0.1.0, }); server.registerTool( read_file, { title: 读取文件内容, description: 读取指定路径的文件内容适合回答这个文件里写了什么这类问题, inputSchema: { filePath: z.string().describe(文件的绝对路径), }, }, async ({ filePath }) { const content await fs.readFile(filePath, utf-8); return { content: [{ type: text, text: content }] }; } ); server.registerTool( list_directory, { title: 列出目录内容, description: 列出指定目录下的所有文件和子目录名称, inputSchema: { dirPath: z.string().describe(目录的绝对路径), }, }, async ({ dirPath }) { const entries await fs.readdir(dirPath); return { content: [{ type: text, text: entries.join(\n) }] }; } ); const transport new StdioServerTransport(); await server.connect(transport);这段代码做的事很直白创建 Server注册两个工具然后挂到标准输入输出传输上。运行时客户端会通过 stdin 发 JSON-RPC 请求Server 处理完通过 stdout 返回响应。注意不要在生产代码里直接对任意路径做文件读取必须有目录白名单之类的安全约束我这里是演示最小逻辑。5.3 在 Trae / Claude Desktop / Cursor 里配置启动脚本先编译一下npm run build node dist/index.js确认能启动后在客户端配置文件里添加 MCP Server。Trae 的 MCP 配置入口一般在设置里的 MCP 面板或者在项目里放一个配置文件。Claude Desktop 则是编辑claude_desktop_config.json。通用的配置长这样{ mcpServers: { local-files: { command: node, args: [/absolute/path/to/dist/index.js] } } }配置好后重启客户端在对话里问一句“帮我看看 /tmp 目录下有什么文件”如果客户端显示工具被调用说明整个链路已经通了。我第一次跑通这个流程时最直观的感受是协议本身不神秘就是两个进程之间的一问一答SDK 把大多数细节封装好了。5.4 验证与调试方法MCP 的调试比想象中友好因为消息是 JSON 文本。我常用的验证方式有三种。第一种用 SDK 自带的 MCP Inspector 工具。启动方式是在项目里执行npx modelcontextprotocol/inspector node dist/index.js然后打开浏览器面板可以看到协议消息的实时日志还能手动调用 tools/list、tools/call。第二种直接在终端里跑 Server手动往 stdin 塞 JSON-RPC 消息看看 stdout 返回什么。这种方式虽然原始但能帮你理解协议结构。第三种在 Host 界面看日志。Trae 和 Claude Desktop 都会有 MCP 连接的日志或状态显示连接失败或调用失败会给出错误码和消息排查效率很高。6. 常见配置场景Figma、蓝湖、Playwright 怎么接6.1 Figma MCP设计稿到代码的关键一跳Figma MCP 是设计领域最典型的 MCP Server。它把你的 Figma 文件、图层、样式、切图信息通过协议暴露给 AI 助手。配上 Trae 或 Cursor 后AI 可以直接读取设计稿的节点结构生成对应的前端代码而不需要你手动去看标注、量尺寸。配置 Figma MCP 时你需要先拿到 Figma 的 Personal Access Token。在 Figma 后台生成 token 后配置里把这个 token 作为环境变量传给 Server{ mcpServers: { figma: { command: npx, args: [-y, figma-developer-mcp, --stdio], env: { FIGMA_API_KEY: 你的token } } } }实际使用中的经验连接成功后最好先让 AI 列出文件的主框架和页面结构再让它针对某一个 Frame 生成代码。如果直接把整份设计稿塞给 AI信息量太大生成结果往往很散。另外Figma MCP 对切图的支持要看具体实现能读节点也能导出图片但“一键切图”这种需求通常还是需要设计侧的命名和分组配合。如果你在 Codex 里配置 Figma MCP思路完全一样只是把配置文件放到对应的工作区即可。6.2 蓝湖 MCP国内设计协作平台的接入蓝湖是国内主流的设计协作平台它的 MCP Server 思路和 Figma MCP 类似把设计稿的标注、切图、颜色、文本等信息暴露给 AI。配置时根据蓝湖官方文档获取访问凭据然后在客户端配置中添加对应的 MCP Server。配置方式基本和其他 MCP 一样关键是确认 Server 的启动命令和参数。不同的蓝湖版本和不同的客户端配置细节可能不同我建议以官方文档为准。如果遇到连不上优先检查 token 权限和网络代理配置。6.3 Playwright MCPAI 控制浏览器Playwright MCP 非常实用。它把浏览器自动化能力封装成 MCP ServerAI 助手可以直接驱动真实浏览器打开页面、点击、填表单、截图、读取 DOM。在测试场景里你可以对 AI 说“打开这个页面登录然后截图首页”它就能真的操作浏览器完成。配置通常这样写{ mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest] } } }运行后AI 会启动一个浏览器实例。需要注意会话隔离如果你同时跑多条浏览器自动化任务要确保各自独立否则标签页互相干扰。另外这类能力权限很大建议只在受控环境开启不要在生产环境给非授权用户开放。6.4 通用配置文件写法与常见陷阱MCP 客户端配置本质上是同一个结构mcpServers 对象下每个 server 名对应一组启动参数。常见陷阱我列三个。一是路径问题。在 Windows 下使用 npx 或 node 时如果路径带空格或特殊字符需要正确转义。跨平台的路径分隔符也要注意很多配置在 Mac 上能跑到 Windows 就报命令找不到基本都是路径写法问题。二是环境变量。很多 MCP Server 需要 API Key配置文件里的 env 字段是给它用的。不要让 Server 代码里硬编码凭据环境变量注入更安全也方便后续轮换 token。三是版本匹配。MCP 协议版本和 SDK 版本在迭代旧版 Server 配新版客户端可能出现“初始化失败”“能力不兼容”这类问题。遇到时先检查版本再排查配置。7. 我踩过的坑和排查思路MCP 相关的搜索热词里有一条“你需要来自administrators的权限才能删除什么原理”这类系统权限问题经常和 MCP 卡在一起。我把自己在 Windows 和 Mac 上踩过的坑整理成一个速查表。7.1 常见问题速查表现象可能原因排查思路MCP Server 启动失败日志显示 command not found命令路径不在 PATH 中在配置里用绝对路径或先在终端确认命令能执行连接一直转圈无错误握手超时或版本不兼容查看客户端 MCP 日志看 initialize 是否成功工具列表为空Server 没有实现 tools/list或 listChanged 通知未刷新手动用 MCP Inspector 看工具列表调用工具返回权限错误环境变量缺失或过期检查 token、重新生成凭据Windows 下删除或覆盖文件提示需要管理员权限文件被进程占用或目录权限受限关闭占用进程或使用目录白名单避免操作系统保护目录Server 正常但模型不使用工具工具描述不清晰或参数 schema 不合理优化工具描述用更明确的触发场景表达本地 stdio 正常远端 HTTP 连不上端口、CORS、鉴权未配置先 curl 测接口再对照 MCP 传输要求7.2 我最常踩的三个坑第一个是 npx 缓存问题。配置里用npx -y xxx时首次下载可能耗时很久客户端容易误判为启动超时。解决方法是先手动在终端跑一次确认依赖已经缓存再配置到客户端里。第二个是路径里的大坑。配置文件里的路径如果是相对路径会以客户端当前工作目录为基准而不是以 Server 所在目录为基准。我建议一律写绝对路径省去不必要的排查时间。第三个是日志不输出的问题。很多 MCP Server 用 console.log 输出日志在 stdio 模式下这会把 stdout 污染导致协议消息解析失败。记住stdio 模式下 stdout 只能用于协议消息调试日志要写到 stderr 或者日志文件里。这是新手最容易忽略的细节。7.3 调试工具推荐除了前面提到的 MCP Inspector我自己还会用这几种方式配合调试。在 Server 代码里加 stderr 日志用process.stderr.write输出关键信息stdout 留给协议。对 HTTP 类型的 Server先手动发 JSON-RPC 请求确认接口本身没问题再接入客户端。最后是看 Host 的官方文档里关于 MCP 日志的位置很多问题在日志里已经写了具体错误码。7.4 协议版本和安全边界最后聊一下方向层面的东西。MCP 协议还在快速演进从最初只支持 stdio到后来加入 Streamable HTTP到能力协商机制的完善社区还在讨论如何统一认证、如何治理工具注册中心。如果你准备在生产环境深度使用 MCP建议固定协议版本和 SDK 版本同时把安全边界想清楚哪些工具允许模型直接调用哪些需要人工确认哪些不能让模型接触。这个边界比协议本身更值得提前设计。我在实际项目里的体会是MCP 的门槛不在设置而在把“能力如何描述、权限如何控制、边界如何划分”想清楚。协议简化了连接问题但真正的工程质量还是要靠人对场景的理解。先把一个小的本地 MCP Server 跑通再逐步扩展到设计稿、浏览器、数据库这些复杂场景这条路是踩过最多坑之后最值得推荐的一条。
