拓冰网站定制 
1. MCP重新定义AI与工具的对话方式最近在AI开发圈里MCP这个词的热度是越来越高。无论是讨论Claude Code、Cursor这类AI编程助手还是看到飞书、Figma、Obsidian这些日常工具开始支持它你都能感受到一股新的技术浪潮正在涌动。简单来说MCP全称Model Context Protocol它要解决的是一个非常核心的问题如何让大语言模型LLM安全、高效、标准化地使用外部工具和数据。在过去如果你想给ChatGPT或者Claude加个“外挂”让它能读取你的数据库、操作你的设计稿或者控制你的智能家居往往需要开发者针对每个模型、每个场景去写一套复杂的对接代码过程繁琐且难以复用。MCP的出现就像是为AI世界制定了一套通用的“USB接口”标准。它定义了一套清晰的协议让任何工具我们称之为MCP Server都能以统一的方式将自己的能力“暴露”给任何支持MCP的AI应用MCP Client。这意味着开发者只需为工具编写一次MCP服务端它就能被所有遵循该协议的AI助手调用。对于我们这些一线开发者而言这不仅仅是技术上的简化更是一种思维范式的转变——AI正从一个封闭的聊天机器人演变成一个能真正融入我们工作流、调用我们熟悉工具的智能体。2. MCP核心架构与工作原理拆解要理解MCP为什么能成为热点我们必须深入到它的架构层面去看。它的设计非常精巧核心思想是解耦与标准化。2.1 协议栈Client-Server-Transport三层模型MCP的架构清晰地分为三层这保证了它的灵活性和普适性。第一层是MCP Client客户端。这就是我们直接交互的AI应用比如Claude Desktop、Cursor、或是任何集成了MCP SDK的应用。Client的核心职责是发起请求。当用户向AI提出一个需求例如“帮我总结一下Notion里上周的会议纪要”Client中的大模型会分析这个意图判断需要调用哪个工具资源读取或操作执行然后按照MCP协议格式生成一个标准的请求发送出去。Client不关心工具具体在哪、如何实现它只认协议。第二层是MCP Server服务端。这是能力的提供者。一个MCP Server可以对应一个工具如Figma设计文件操作、一个数据源如公司数据库或一组相关功能。Server在启动时会向Client“广告”自己具备哪些能力。这些能力在MCP中被抽象为两种基本类型Resources资源和Tools工具。Resources代表可读取的静态或动态数据比如一个文件、一张数据库表、当前的天气信息Tools代表可执行的操作比如执行一个搜索、创建一个日历事件、运行一段代码。Server等待Client的请求并返回结构化的结果。第三层是Transport传输层。这是连接Client和Server的桥梁。MCP协议本身是传输无关的它可以通过标准输入输出stdio、HTTP或SSH等多种方式传输JSON-RPC消息。这使得部署极其灵活Server可以是一个本地进程也可以是一个远程服务。最常见的开发模式就是通过stdio让Client和Server像两个本地命令行程序一样通过管道通信。2.2 核心概念Resources与Tools的精准定义理解Resources和Tools的区别是掌握MCP开发的关键。Resources资源的核心是“读”。它有一个唯一的URI统一资源标识符来定位例如file:///home/user/doc.md或figma://file/{file_id}/nodes。Client可以通过read_resource请求来获取资源的内容。资源内容通常以文本形式返回并且可以关联一个MIME类型帮助Client更好地渲染比如标记为text/markdown的文本可以被更好地格式化显示。资源可以是静态的如一个本地文件也可以是动态的比如一个返回实时股价的端点。Server通过list_resources来告知Client自己有哪些资源可用。Tools工具的核心是“写”或“执行”。它代表一个可调用的函数。每个Tool都有明确的输入参数定义一个JSON Schema。当Client需要执行某个操作时它使用call_tool请求并传入参数。Server执行相应的逻辑比如调用第三方API、执行系统命令、操作软件然后将结果以结构化数据文本、图片、列表等返回。例如一个“发送邮件”的Tool其输入参数可能包括收件人、主题、正文。Server通过list_tools来公布自己的工具列表。这种设计让AI的能力边界得到了极大的、标准化的扩展。AI不再仅仅是一个文本生成器而是成为了一个能够协调多种资源和工具的“大脑”。2.3 通信流程一次完整的交互是如何发生的让我们通过一个具体场景看看数据是如何流动的。假设我们在Claude Desktop中安装了Figma MCP Server并想询问“我最新设计稿的标题是什么”。初始化与能力发现Claude DesktopClient启动时会加载配置好的MCP Server比如figma-mcp。通过stdioClient向Server发送初始化请求。Server回复通过list_resources告知“我可以提供figma://file/{file_id}/document这个资源它代表Figma文件的文档结构”同时通过list_tools告知“我还有一个update_figma_comment工具可以用于批注”。意图解析与请求生成用户在Claude界面输入问题。Claude内部的模型理解到要回答这个问题需要先获取设计稿的文档信息。模型决定调用read_resource方法并拼装出目标资源的URI如果配置中已指定了默认文件ID则会自动填入。协议请求与执行Client按照MCP的JSON-RPC格式构造一个read_resource请求通过传输层发送给Server。请求体中包含了资源的URI。服务端处理与响应Figma MCP Server收到请求解析出文件ID然后调用Figma的官方API获取该文件的文档树结构。Server将获取到的JSON数据其中包含页面、画板、节点的名称和属性作为文本内容封装进MCP协议的响应中返回给Client。结果呈现与回答生成Claude Desktop收到响应将结构化的文档数据作为上下文提供给大模型。大模型分析这些数据从中提取出根画板或文件的名称最终生成自然语言回答“您最新设计稿的标题是‘用户仪表盘V2.1’。”整个过程对用户是透明的感觉就像是在和Claude自然对话但它背后已经完成了一次对复杂外部工具的安全调用。3. 主流MCP Server解析与实战配置MCP生态的繁荣体现在层出不穷的Server实现上。从热门工具集成到实用工具链我们可以将它们分为几大类。3.1 设计与协作工具类Figma、Brave Search、Tavily这类Server旨在将AI融入创意和搜索工作流。Figma MCP Server这是目前讨论度最高的之一。它允许AI读取Figma文件的结构、图层名称、注释甚至通过Tools创建新的注释或修改图层名称。这对于设计评审、生成设计规范文档、自动化标注等工作流有巨大价值。配置核心你需要一个Figma的个人访问令牌Personal Access Token和文件ID。令牌在Figma账户设置中生成文件ID从文件浏览器地址栏获取。配置通常写入Claude Desktop的claude_desktop_config.json。一个典型的配置片段如下{ mcpServers: { figma: { command: npx, args: [ -y, modelcontextprotocol/server-figma, --token, YOUR_FIGMA_TOKEN, --file-id, YOUR_FILE_ID ] } } }实操心得很多人反映“Figma MCP还原度很低”这通常不是协议问题而是Server实现和模型上下文限制导致的。Figma文件结构可能非常复杂生成的文档树JSON体积庞大很容易超出AI模型的上下文窗口。因此选择关键页面或使用Server的筛选参数如果提供来限制返回的数据范围至关重要。好的使用方式是让AI进行摘要查询如“列出首页的所有主要画板名称”而不是“把我整个文件的所有细节都读出来”。搜索类MCP ServerBrave Search, Tavily这类Server为AI提供了联网搜索能力。Tavily MCP 和 Brave Search MCP 是典型代表。功能差异Tavily 是针对AI优化过的搜索API它会自动过滤、总结信息返回更简洁、相关性更高的结果摘要适合快速获取答案。Brave Search 则更接近传统搜索引擎提供丰富的原始搜索结果链接和摘要信息量更大。添加步骤以Tavily为例首先去其官网注册获取API Key。然后在MCP Client配置中添加Server。对于Claude Desktop配置方式与Figma类似指定命令和传入API Key参数。对于Cursor或Code需要在它们的特定设置面板如Cursor的Settings - MCP Servers中进行图形化或JSON配置。注意事项搜索类Tool通常有调用频率和额度限制在开发测试时需留意。另外明确搜索意图的提示词能获得更好结果比如“使用Tavily搜索2024年最新的React状态管理库趋势并总结三点”比单纯“搜索React状态管理”更有效。3.2 开发与效率工具类Filesystem、Git、Playwright这类Server是程序员提升效率的利器。Filesystem Server内置或社区版这是最基础也最强大的Server之一。它让AI可以直接读取、写入、列出你指定目录下的文件。重要警告这涉及极高的安全风险。必须将其严格限制在必要的、非敏感的工作目录内绝对不要指向根目录或包含密钥、配置文件的目录。安全配置示例在配置中只允许访问你的项目文件夹。{ mcpServers: { project_files: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /path/to/your/safe/project ] } } }Git Server允许AI执行git status,git log,git diff等命令并读取结果。这可以用来生成提交信息、分析代码变更、回顾项目历史。它本质上是安全地封装了git命令行工具。避坑技巧确保Server运行环境已安装git并且具有执行权限。复杂的git操作如交互式变基可能因输出格式复杂而导致AI理解困难最好让AI执行简单、标准的命令。Playwright MCP Server这是一个非常有趣的Server它允许AI控制浏览器进行自动化操作。想象一下你可以对AI说“帮我看看某电商网站上iPhone 15的价格并截图保存。” AI可以通过这个Server编写Playwright脚本并执行。潜在风险与限制这赋予了AI强大的自动化能力但也可能被用于不当操作。务必在可控环境下使用。此外复杂的网页交互如处理验证码、非标准UI组件对AI的提示工程要求很高可能需要多轮调试。3.3 如何将MCP Server添加进Claude Code、Cursor等客户端这是实操中最关键的一步。不同客户端的配置方式大同小异核心都是编辑一个配置文件来声明需要启动的MCP Server。通用步骤找到配置文件Claude Desktop配置文件通常位于~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 或%APPDATA%\Claude\claude_desktop_config.json(Windows)。Cursor在Settings界面中有专门的“MCP Servers”设置项支持图形化添加其背后也是修改一个配置文件。其他客户端参考其官方文档寻找MCP或插件配置部分。编写Server配置在配置文件的mcpServers对象下为你想要添加的Server创建一个新的键值对。Key是自定义名称如figmaValue是一个对象至少包含command和args字段用于指定如何启动这个Server进程。对于npm包通常使用npx命令。重启客户端保存配置文件后完全重启AI客户端使其加载新的MCP配置。验证重启后在对话中尝试使用新功能。例如添加Filesystem Server后可以问“请列出我项目src目录下的所有TypeScript文件。”一个综合配置示例 (claude_desktop_config.json){ mcpServers: { project_files: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/me/Development/my_project ] }, figma_design: { command: npx, args: [ -y, modelcontextprotocol/server-figma, --token, fig-xxx..., --file-id, abcDeFgHiJk ] }, web_search: { command: npx, args: [ -y, modelcontextprotocol/server-tavily, --api-key, tavily_xxx... ] } } }重要提示在配置API Key、访问令牌等敏感信息时永远不要将它们硬编码在配置文件中提交到版本控制系统如Git。应该使用环境变量。例如在配置中通过process.env.FIGMA_TOKEN引用并在启动客户端前设置好环境变量。4. MCP开发入门从零构建你的第一个Server理解了如何使用下一步就是创造。开发一个MCP Server并不复杂官方提供了Python、TypeScript/JavaScript等多种语言的SDK大大降低了门槛。4.1 环境搭建与项目初始化我们以最流行的 TypeScript 为例演示如何构建一个简单的“天气查询”MCP Server。创建项目mkdir mcp-weather-server cd mcp-weather-server npm init -y安装依赖安装官方的MCP TypeScript SDK。npm install modelcontextprotocol/sdk安装开发依赖我们需要TypeScript和相关的类型定义。npm install --save-dev typescript types/node tsx在package.json中添加启动脚本scripts: { start: tsx src/index.ts }4.2 核心代码实现定义资源与工具创建src/index.ts文件开始编写Server逻辑。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from modelcontextprotocol/sdk/types.js; // 1. 创建Server实例 const server new Server( { name: weather-mcp-server, version: 0.1.0, }, { capabilities: { resources: {}, // 声明我们支持资源 tools: {}, // 声明我们支持工具 }, } ); // 2. 定义一个“工具”查询城市天气 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ { name: get_weather, description: 获取指定城市的当前天气信息, inputSchema: { type: object, properties: { city: { type: string, description: 城市名称例如Beijing, Shanghai, }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位摄氏度或华氏度, default: celsius, }, }, required: [city], }, }, ], }; }); // 3. 处理工具调用请求 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name ! get_weather) { throw new Error(未知工具: ${request.params.name}); } const { city, unit celsius } request.params.arguments as { city: string; unit?: string; }; // 模拟调用天气API此处为示例实际需调用如OpenWeatherMap的API // 假设我们有一个虚拟的 fetchWeatherData 函数 const temperature 22; // 模拟数据 const condition 晴朗; const humidity 65; let displayTemp temperature; if (unit fahrenheit) { displayTemp (temperature * 9) / 5 32; } return { content: [ { type: text, text: 城市【${city}】的当前天气\n - 天气状况${condition}\n - 温度${displayTemp.toFixed(1)}°${unit celsius ? C : F}\n - 湿度${humidity}%, }, ], }; }); // 4. 定义一个“资源”静态的天气帮助文档 server.setRequestHandler(ListResourcesRequestSchema, async () { return { resources: [ { uri: weather://help, mimeType: text/markdown, name: 天气查询帮助文档, description: 关于如何使用本天气服务的信息, }, ], }; }); server.setRequestHandler(ReadResourceRequestSchema, async (request) { if (request.params.uri ! weather://help) { throw new Error(未知资源: ${request.params.uri}); } return { contents: [ { uri: request.params.uri, mimeType: text/markdown, text: # 天气查询MCP服务帮助\n\n 本服务提供了一个工具\n\n - **get_weather**: 查询城市天气。需要参数 \city\城市名可选参数 \unit\单位celsius 或 fahrenheit。\n\n 示例调用请求\{city: London, unit: celsius}\, }, ], }; }); // 5. 启动Server使用标准输入输出作为传输层 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Weather Server 已启动并运行在 stdio 上); } main().catch((error) { console.error(Server 启动失败:, error); process.exit(1); });4.3 本地测试与调试编译运行由于我们使用tsx可以直接运行。npm start此时Server会启动并等待来自stdio的输入。使用MCP Inspector进行测试手动构造JSON-RPC消息很麻烦。Anthropic官方提供了一个强大的图形化测试工具MCP Inspector。你可以通过它连接到你的本地Server直观地查看Server公告了哪些资源和工具并手动发起调用测试极大提升开发效率。集成到客户端测试无误后就可以像配置第三方Server一样将你的自定义Server添加到Claude Desktop或Cursor的配置中指定command为node或tsx并指向你的入口文件。开发心得输入验证至关重要在call_tool的处理函数中务必严格验证传入的参数防止无效或恶意输入导致Server崩溃。错误处理要友好抛出的错误信息应该清晰以便Client和背后的用户能理解问题所在。MCP协议支持返回结构化的错误信息。资源URI设计要有层次如果你的Server提供多种资源设计一个清晰的URI命名空间如weather://city/beijing/forecast、weather://city/shanghai/current这样更易于管理和使用。5. MCP与相关概念的深度辨析在讨论MCP时经常会遇到一些容易混淆的概念厘清它们有助于我们更准确地把握MCP的定位。5.1 MCP vs. Function Calling这是最常见的困惑点。两者目标相似都是让LLM调用外部功能但层级和范围不同。Function Calling函数调用是特定LLM提供商如OpenAI、Anthropic在其API中实现的一种功能。开发者定义一组函数的描述名称、参数、说明LLM在对话中判断是否需要调用某个函数并生成符合该函数参数格式的JSON。然后由开发者自己的后端代码来执行这个函数。它是厂商特定、耦合于其API的。MCP模型上下文协议是一个开放的、与模型无关的协议标准。它定义了一套通用的通信机制JSON-RPC和数据模型Resources, Tools不关心对面是Claude、GPT还是其他任何兼容的AI。Server和Client可以独立开发。MCP可以看作是Function Calling的“标准化、可移植、解耦”版本。简单类比Function Calling像是每家手机品牌都有自己的私有充电接口OpenAI口、Anthropic口。MCP则像是USB-C标准任何设备只要支持USB-C就能互相连接。用MCP构建的Tool可以同时给Claude Desktop和Cursor使用而无需为每个客户端重写适配逻辑。5.2 MCP vs. Skill (in Claude)在Anthropic的生态中特别是Claude.ai平台上还有一个概念叫“Skill”。Skill是专属于Claude.ai平台的一种功能扩展机制。用户可以通过自然语言描述让Claude学会调用一个特定的API或完成一个复杂任务。Skill的创建和运行完全在Claude.ai的云端环境中。区别平台绑定Skill是Claude.ai的特性。MCP是开放协议可用于Claude Desktop、Cursor、自建应用等。创建方式Skill通过自然语言“教授”创建门槛低但精度可能依赖提示词。MCP Server需要编程实现精度和可靠性更高。运行环境Skill在Anthropic云端运行。MCP Server可以在本地、私有服务器或任何地方运行对数据隐私和安全性控制更强。能力范围Skill更适合定义一次性的、基于API的复杂工作流。MCP更专注于标准化、可复用的工具和资源访问。对于开发者而言如果需要构建稳定、可复用、且需在多种AI客户端中使用的工具MCP是更专业的选择。对于快速原型或一次性任务Skill可能更便捷。5.3 MCP的适用边界与挑战MCP并非万能钥匙理解其边界能让我们更好地应用它。优势标准化与互操作性一次开发多处使用。安全性通过协议隔离ClientAI无法直接访问系统必须通过Server定义的安全接口。灵活性支持本地和远程部署传输方式多样。生态潜力正在形成丰富的Server市场工具集成会越来越容易。当前挑战与注意事项上下文限制这是最大的实践瓶颈。很多工具如Figma、文件系统返回的数据量巨大很容易占满模型的上下文窗口导致后续对话失忆或无法处理。Server开发者需要提供分页、过滤、摘要等功能使用者需要学会提出精准的查询。工具描述的精确性Tool的description和参数的description至关重要。大模型依赖这些文本来判断何时、如何调用工具。模糊的描述会导致错误的调用。错误处理与状态管理MCP本身是无状态的复杂的多步骤交互例如一个需要登录、多步操作的工具需要Server自身维护会话状态或由用户协调这对设计提出了更高要求。性能与延迟每次调用都涉及进程间通信IPC或网络请求可能会引入可感知的延迟。对于实时性要求高的场景需要优化。6. 故障排查与效能优化指南在实际使用和开发MCP时你会遇到各种问题。这里汇总了一些常见场景和解决思路。6.1 客户端连接与配置问题问题现象可能原因排查步骤与解决方案Claude Desktop/Cursor 启动后无MCP功能1. 配置文件路径错误。2. 配置文件格式错误JSON语法错误。3. Server启动命令错误或依赖未安装。1. 检查配置文件路径是否正确特别是跨平台时的路径分隔符。2. 使用JSON验证工具检查配置文件。3. 尝试在终端手动运行配置中的command和args看Server能否独立启动。查看客户端日志如Claude Desktop的帮助菜单中的“查看日志”。提示“无法连接到MCP Server”1. Server进程崩溃。2. 传输层不匹配如配置了HTTP但Server是stdio。3. 防火墙或权限问题。1. 检查Server代码是否有未捕获的异常查看Server的标准错误输出。2. 确认Client和Server约定的传输方式stdio/HTTP一致。3. 如果是HTTP Server检查端口是否被占用Client配置的URL是否正确。特定工具/资源不出现1. Server的list_tools/list_resources未正确实现或返回空。2. Client缓存了旧的Server信息。1. 使用MCP Inspector连接Server直接调用list_tools等方法验证返回数据。2. 重启Client有时需要完全退出再重新打开。6.2 Server开发与运行时问题问题现象可能原因排查步骤与解决方案Server启动后立即退出1. 依赖缺失。2. 代码中存在同步的顶级错误。3. 未正确等待异步连接。1. 确保package.json中的依赖已安装特别是modelcontextprotocol/sdk。2. 在代码开头添加try-catch或使用process.on(uncaughtException)捕获错误。3. 确保server.connect(transport)被await或在async函数中调用。Client调用工具无响应或超时1. Server的call_tool处理函数存在死循环或长时间阻塞。2. 未正确发送响应。1. 在Tool处理函数中添加超时逻辑对于耗时操作考虑异步处理并立即返回“处理中”状态如果协议支持。2. 确保处理函数最终会return一个符合协议格式的响应对象。返回内容被Client截断或格式错乱1. 返回的文本内容过长。2. MIME类型设置错误导致Client渲染异常。1. 对长文本进行分页或摘要。MCP协议支持分页机制可以分批返回资源内容。2. 对于非纯文本正确设置mimeType如图片用image/pngJSON数据用application/json。6.3 效能优化与最佳实践精简工具与资源描述Tool的name和description要简洁、准确避免冗长。清晰的描述能帮助AI更准确地选择工具。实现资源分页对于可能返回大量数据的资源如文件列表、数据库查询结果一定要实现分页。在list_resources的响应中提供nextCursor等分页令牌在read_resource时支持分页参数。这能有效避免一次性加载海量数据撑爆上下文。使用缓存对于变化不频繁的资源如静态文档、配置信息可以在Server端实现缓存机制减少对底层系统或API的重复调用提升响应速度。异步与流式响应未来方向关注MCP协议的更新。对于长时间运行的任务考虑支持异步操作或流式返回部分结果以提升用户体验。详细的错误信息在Tool调用失败时返回结构化的错误信息不仅包含错误代码更要有面向用户的、可读的解释帮助用户或AI理解下一步该怎么做。安全性是第一要务最小权限原则Filesystem Server只授予必要目录的访问权。输入净化对所有来自Client的输入如文件路径、API参数进行严格的验证和净化防止路径遍历、命令注入等攻击。密钥管理永远不要将API密钥、令牌等硬编码在代码或配置文件中。使用环境变量或安全的密钥管理服务。MCP协议正在快速发展社区每天都在涌现新的Server和创意。作为开发者拥抱这个协议意味着你正在为AI构建下一代的基础设施。从自动化繁琐任务到创造全新的人机交互体验可能性是无限的。我个人的体会是与其等待某个AI应用集成你需要的功能不如用MCP自己动手把它“连接”起来这种“即插即用”的能力整合才是AI时代真正的效率革命。开始动手从写一个简单的、解决你实际痛点的MCP Server开始吧。 MCP协议：AI工具化集成的标准化接口与实战开发指南
1. MCP重新定义AI与工具的对话方式最近在AI开发圈里MCP这个词的热度是越来越高。无论是讨论Claude Code、Cursor这类AI编程助手还是看到飞书、Figma、Obsidian这些日常工具开始支持它你都能感受到一股新的技术浪潮正在涌动。简单来说MCP全称Model Context Protocol它要解决的是一个非常核心的问题如何让大语言模型LLM安全、高效、标准化地使用外部工具和数据。在过去如果你想给ChatGPT或者Claude加个“外挂”让它能读取你的数据库、操作你的设计稿或者控制你的智能家居往往需要开发者针对每个模型、每个场景去写一套复杂的对接代码过程繁琐且难以复用。MCP的出现就像是为AI世界制定了一套通用的“USB接口”标准。它定义了一套清晰的协议让任何工具我们称之为MCP Server都能以统一的方式将自己的能力“暴露”给任何支持MCP的AI应用MCP Client。这意味着开发者只需为工具编写一次MCP服务端它就能被所有遵循该协议的AI助手调用。对于我们这些一线开发者而言这不仅仅是技术上的简化更是一种思维范式的转变——AI正从一个封闭的聊天机器人演变成一个能真正融入我们工作流、调用我们熟悉工具的智能体。2. MCP核心架构与工作原理拆解要理解MCP为什么能成为热点我们必须深入到它的架构层面去看。它的设计非常精巧核心思想是解耦与标准化。2.1 协议栈Client-Server-Transport三层模型MCP的架构清晰地分为三层这保证了它的灵活性和普适性。第一层是MCP Client客户端。这就是我们直接交互的AI应用比如Claude Desktop、Cursor、或是任何集成了MCP SDK的应用。Client的核心职责是发起请求。当用户向AI提出一个需求例如“帮我总结一下Notion里上周的会议纪要”Client中的大模型会分析这个意图判断需要调用哪个工具资源读取或操作执行然后按照MCP协议格式生成一个标准的请求发送出去。Client不关心工具具体在哪、如何实现它只认协议。第二层是MCP Server服务端。这是能力的提供者。一个MCP Server可以对应一个工具如Figma设计文件操作、一个数据源如公司数据库或一组相关功能。Server在启动时会向Client“广告”自己具备哪些能力。这些能力在MCP中被抽象为两种基本类型Resources资源和Tools工具。Resources代表可读取的静态或动态数据比如一个文件、一张数据库表、当前的天气信息Tools代表可执行的操作比如执行一个搜索、创建一个日历事件、运行一段代码。Server等待Client的请求并返回结构化的结果。第三层是Transport传输层。这是连接Client和Server的桥梁。MCP协议本身是传输无关的它可以通过标准输入输出stdio、HTTP或SSH等多种方式传输JSON-RPC消息。这使得部署极其灵活Server可以是一个本地进程也可以是一个远程服务。最常见的开发模式就是通过stdio让Client和Server像两个本地命令行程序一样通过管道通信。2.2 核心概念Resources与Tools的精准定义理解Resources和Tools的区别是掌握MCP开发的关键。Resources资源的核心是“读”。它有一个唯一的URI统一资源标识符来定位例如file:///home/user/doc.md或figma://file/{file_id}/nodes。Client可以通过read_resource请求来获取资源的内容。资源内容通常以文本形式返回并且可以关联一个MIME类型帮助Client更好地渲染比如标记为text/markdown的文本可以被更好地格式化显示。资源可以是静态的如一个本地文件也可以是动态的比如一个返回实时股价的端点。Server通过list_resources来告知Client自己有哪些资源可用。Tools工具的核心是“写”或“执行”。它代表一个可调用的函数。每个Tool都有明确的输入参数定义一个JSON Schema。当Client需要执行某个操作时它使用call_tool请求并传入参数。Server执行相应的逻辑比如调用第三方API、执行系统命令、操作软件然后将结果以结构化数据文本、图片、列表等返回。例如一个“发送邮件”的Tool其输入参数可能包括收件人、主题、正文。Server通过list_tools来公布自己的工具列表。这种设计让AI的能力边界得到了极大的、标准化的扩展。AI不再仅仅是一个文本生成器而是成为了一个能够协调多种资源和工具的“大脑”。2.3 通信流程一次完整的交互是如何发生的让我们通过一个具体场景看看数据是如何流动的。假设我们在Claude Desktop中安装了Figma MCP Server并想询问“我最新设计稿的标题是什么”。初始化与能力发现Claude DesktopClient启动时会加载配置好的MCP Server比如figma-mcp。通过stdioClient向Server发送初始化请求。Server回复通过list_resources告知“我可以提供figma://file/{file_id}/document这个资源它代表Figma文件的文档结构”同时通过list_tools告知“我还有一个update_figma_comment工具可以用于批注”。意图解析与请求生成用户在Claude界面输入问题。Claude内部的模型理解到要回答这个问题需要先获取设计稿的文档信息。模型决定调用read_resource方法并拼装出目标资源的URI如果配置中已指定了默认文件ID则会自动填入。协议请求与执行Client按照MCP的JSON-RPC格式构造一个read_resource请求通过传输层发送给Server。请求体中包含了资源的URI。服务端处理与响应Figma MCP Server收到请求解析出文件ID然后调用Figma的官方API获取该文件的文档树结构。Server将获取到的JSON数据其中包含页面、画板、节点的名称和属性作为文本内容封装进MCP协议的响应中返回给Client。结果呈现与回答生成Claude Desktop收到响应将结构化的文档数据作为上下文提供给大模型。大模型分析这些数据从中提取出根画板或文件的名称最终生成自然语言回答“您最新设计稿的标题是‘用户仪表盘V2.1’。”整个过程对用户是透明的感觉就像是在和Claude自然对话但它背后已经完成了一次对复杂外部工具的安全调用。3. 主流MCP Server解析与实战配置MCP生态的繁荣体现在层出不穷的Server实现上。从热门工具集成到实用工具链我们可以将它们分为几大类。3.1 设计与协作工具类Figma、Brave Search、Tavily这类Server旨在将AI融入创意和搜索工作流。Figma MCP Server这是目前讨论度最高的之一。它允许AI读取Figma文件的结构、图层名称、注释甚至通过Tools创建新的注释或修改图层名称。这对于设计评审、生成设计规范文档、自动化标注等工作流有巨大价值。配置核心你需要一个Figma的个人访问令牌Personal Access Token和文件ID。令牌在Figma账户设置中生成文件ID从文件浏览器地址栏获取。配置通常写入Claude Desktop的claude_desktop_config.json。一个典型的配置片段如下{ mcpServers: { figma: { command: npx, args: [ -y, modelcontextprotocol/server-figma, --token, YOUR_FIGMA_TOKEN, --file-id, YOUR_FILE_ID ] } } }实操心得很多人反映“Figma MCP还原度很低”这通常不是协议问题而是Server实现和模型上下文限制导致的。Figma文件结构可能非常复杂生成的文档树JSON体积庞大很容易超出AI模型的上下文窗口。因此选择关键页面或使用Server的筛选参数如果提供来限制返回的数据范围至关重要。好的使用方式是让AI进行摘要查询如“列出首页的所有主要画板名称”而不是“把我整个文件的所有细节都读出来”。搜索类MCP ServerBrave Search, Tavily这类Server为AI提供了联网搜索能力。Tavily MCP 和 Brave Search MCP 是典型代表。功能差异Tavily 是针对AI优化过的搜索API它会自动过滤、总结信息返回更简洁、相关性更高的结果摘要适合快速获取答案。Brave Search 则更接近传统搜索引擎提供丰富的原始搜索结果链接和摘要信息量更大。添加步骤以Tavily为例首先去其官网注册获取API Key。然后在MCP Client配置中添加Server。对于Claude Desktop配置方式与Figma类似指定命令和传入API Key参数。对于Cursor或Code需要在它们的特定设置面板如Cursor的Settings - MCP Servers中进行图形化或JSON配置。注意事项搜索类Tool通常有调用频率和额度限制在开发测试时需留意。另外明确搜索意图的提示词能获得更好结果比如“使用Tavily搜索2024年最新的React状态管理库趋势并总结三点”比单纯“搜索React状态管理”更有效。3.2 开发与效率工具类Filesystem、Git、Playwright这类Server是程序员提升效率的利器。Filesystem Server内置或社区版这是最基础也最强大的Server之一。它让AI可以直接读取、写入、列出你指定目录下的文件。重要警告这涉及极高的安全风险。必须将其严格限制在必要的、非敏感的工作目录内绝对不要指向根目录或包含密钥、配置文件的目录。安全配置示例在配置中只允许访问你的项目文件夹。{ mcpServers: { project_files: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /path/to/your/safe/project ] } } }Git Server允许AI执行git status,git log,git diff等命令并读取结果。这可以用来生成提交信息、分析代码变更、回顾项目历史。它本质上是安全地封装了git命令行工具。避坑技巧确保Server运行环境已安装git并且具有执行权限。复杂的git操作如交互式变基可能因输出格式复杂而导致AI理解困难最好让AI执行简单、标准的命令。Playwright MCP Server这是一个非常有趣的Server它允许AI控制浏览器进行自动化操作。想象一下你可以对AI说“帮我看看某电商网站上iPhone 15的价格并截图保存。” AI可以通过这个Server编写Playwright脚本并执行。潜在风险与限制这赋予了AI强大的自动化能力但也可能被用于不当操作。务必在可控环境下使用。此外复杂的网页交互如处理验证码、非标准UI组件对AI的提示工程要求很高可能需要多轮调试。3.3 如何将MCP Server添加进Claude Code、Cursor等客户端这是实操中最关键的一步。不同客户端的配置方式大同小异核心都是编辑一个配置文件来声明需要启动的MCP Server。通用步骤找到配置文件Claude Desktop配置文件通常位于~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 或%APPDATA%\Claude\claude_desktop_config.json(Windows)。Cursor在Settings界面中有专门的“MCP Servers”设置项支持图形化添加其背后也是修改一个配置文件。其他客户端参考其官方文档寻找MCP或插件配置部分。编写Server配置在配置文件的mcpServers对象下为你想要添加的Server创建一个新的键值对。Key是自定义名称如figmaValue是一个对象至少包含command和args字段用于指定如何启动这个Server进程。对于npm包通常使用npx命令。重启客户端保存配置文件后完全重启AI客户端使其加载新的MCP配置。验证重启后在对话中尝试使用新功能。例如添加Filesystem Server后可以问“请列出我项目src目录下的所有TypeScript文件。”一个综合配置示例 (claude_desktop_config.json){ mcpServers: { project_files: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/me/Development/my_project ] }, figma_design: { command: npx, args: [ -y, modelcontextprotocol/server-figma, --token, fig-xxx..., --file-id, abcDeFgHiJk ] }, web_search: { command: npx, args: [ -y, modelcontextprotocol/server-tavily, --api-key, tavily_xxx... ] } } }重要提示在配置API Key、访问令牌等敏感信息时永远不要将它们硬编码在配置文件中提交到版本控制系统如Git。应该使用环境变量。例如在配置中通过process.env.FIGMA_TOKEN引用并在启动客户端前设置好环境变量。4. MCP开发入门从零构建你的第一个Server理解了如何使用下一步就是创造。开发一个MCP Server并不复杂官方提供了Python、TypeScript/JavaScript等多种语言的SDK大大降低了门槛。4.1 环境搭建与项目初始化我们以最流行的 TypeScript 为例演示如何构建一个简单的“天气查询”MCP Server。创建项目mkdir mcp-weather-server cd mcp-weather-server npm init -y安装依赖安装官方的MCP TypeScript SDK。npm install modelcontextprotocol/sdk安装开发依赖我们需要TypeScript和相关的类型定义。npm install --save-dev typescript types/node tsx在package.json中添加启动脚本scripts: { start: tsx src/index.ts }4.2 核心代码实现定义资源与工具创建src/index.ts文件开始编写Server逻辑。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from modelcontextprotocol/sdk/types.js; // 1. 创建Server实例 const server new Server( { name: weather-mcp-server, version: 0.1.0, }, { capabilities: { resources: {}, // 声明我们支持资源 tools: {}, // 声明我们支持工具 }, } ); // 2. 定义一个“工具”查询城市天气 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ { name: get_weather, description: 获取指定城市的当前天气信息, inputSchema: { type: object, properties: { city: { type: string, description: 城市名称例如Beijing, Shanghai, }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位摄氏度或华氏度, default: celsius, }, }, required: [city], }, }, ], }; }); // 3. 处理工具调用请求 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name ! get_weather) { throw new Error(未知工具: ${request.params.name}); } const { city, unit celsius } request.params.arguments as { city: string; unit?: string; }; // 模拟调用天气API此处为示例实际需调用如OpenWeatherMap的API // 假设我们有一个虚拟的 fetchWeatherData 函数 const temperature 22; // 模拟数据 const condition 晴朗; const humidity 65; let displayTemp temperature; if (unit fahrenheit) { displayTemp (temperature * 9) / 5 32; } return { content: [ { type: text, text: 城市【${city}】的当前天气\n - 天气状况${condition}\n - 温度${displayTemp.toFixed(1)}°${unit celsius ? C : F}\n - 湿度${humidity}%, }, ], }; }); // 4. 定义一个“资源”静态的天气帮助文档 server.setRequestHandler(ListResourcesRequestSchema, async () { return { resources: [ { uri: weather://help, mimeType: text/markdown, name: 天气查询帮助文档, description: 关于如何使用本天气服务的信息, }, ], }; }); server.setRequestHandler(ReadResourceRequestSchema, async (request) { if (request.params.uri ! weather://help) { throw new Error(未知资源: ${request.params.uri}); } return { contents: [ { uri: request.params.uri, mimeType: text/markdown, text: # 天气查询MCP服务帮助\n\n 本服务提供了一个工具\n\n - **get_weather**: 查询城市天气。需要参数 \city\城市名可选参数 \unit\单位celsius 或 fahrenheit。\n\n 示例调用请求\{city: London, unit: celsius}\, }, ], }; }); // 5. 启动Server使用标准输入输出作为传输层 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Weather Server 已启动并运行在 stdio 上); } main().catch((error) { console.error(Server 启动失败:, error); process.exit(1); });4.3 本地测试与调试编译运行由于我们使用tsx可以直接运行。npm start此时Server会启动并等待来自stdio的输入。使用MCP Inspector进行测试手动构造JSON-RPC消息很麻烦。Anthropic官方提供了一个强大的图形化测试工具MCP Inspector。你可以通过它连接到你的本地Server直观地查看Server公告了哪些资源和工具并手动发起调用测试极大提升开发效率。集成到客户端测试无误后就可以像配置第三方Server一样将你的自定义Server添加到Claude Desktop或Cursor的配置中指定command为node或tsx并指向你的入口文件。开发心得输入验证至关重要在call_tool的处理函数中务必严格验证传入的参数防止无效或恶意输入导致Server崩溃。错误处理要友好抛出的错误信息应该清晰以便Client和背后的用户能理解问题所在。MCP协议支持返回结构化的错误信息。资源URI设计要有层次如果你的Server提供多种资源设计一个清晰的URI命名空间如weather://city/beijing/forecast、weather://city/shanghai/current这样更易于管理和使用。5. MCP与相关概念的深度辨析在讨论MCP时经常会遇到一些容易混淆的概念厘清它们有助于我们更准确地把握MCP的定位。5.1 MCP vs. Function Calling这是最常见的困惑点。两者目标相似都是让LLM调用外部功能但层级和范围不同。Function Calling函数调用是特定LLM提供商如OpenAI、Anthropic在其API中实现的一种功能。开发者定义一组函数的描述名称、参数、说明LLM在对话中判断是否需要调用某个函数并生成符合该函数参数格式的JSON。然后由开发者自己的后端代码来执行这个函数。它是厂商特定、耦合于其API的。MCP模型上下文协议是一个开放的、与模型无关的协议标准。它定义了一套通用的通信机制JSON-RPC和数据模型Resources, Tools不关心对面是Claude、GPT还是其他任何兼容的AI。Server和Client可以独立开发。MCP可以看作是Function Calling的“标准化、可移植、解耦”版本。简单类比Function Calling像是每家手机品牌都有自己的私有充电接口OpenAI口、Anthropic口。MCP则像是USB-C标准任何设备只要支持USB-C就能互相连接。用MCP构建的Tool可以同时给Claude Desktop和Cursor使用而无需为每个客户端重写适配逻辑。5.2 MCP vs. Skill (in Claude)在Anthropic的生态中特别是Claude.ai平台上还有一个概念叫“Skill”。Skill是专属于Claude.ai平台的一种功能扩展机制。用户可以通过自然语言描述让Claude学会调用一个特定的API或完成一个复杂任务。Skill的创建和运行完全在Claude.ai的云端环境中。区别平台绑定Skill是Claude.ai的特性。MCP是开放协议可用于Claude Desktop、Cursor、自建应用等。创建方式Skill通过自然语言“教授”创建门槛低但精度可能依赖提示词。MCP Server需要编程实现精度和可靠性更高。运行环境Skill在Anthropic云端运行。MCP Server可以在本地、私有服务器或任何地方运行对数据隐私和安全性控制更强。能力范围Skill更适合定义一次性的、基于API的复杂工作流。MCP更专注于标准化、可复用的工具和资源访问。对于开发者而言如果需要构建稳定、可复用、且需在多种AI客户端中使用的工具MCP是更专业的选择。对于快速原型或一次性任务Skill可能更便捷。5.3 MCP的适用边界与挑战MCP并非万能钥匙理解其边界能让我们更好地应用它。优势标准化与互操作性一次开发多处使用。安全性通过协议隔离ClientAI无法直接访问系统必须通过Server定义的安全接口。灵活性支持本地和远程部署传输方式多样。生态潜力正在形成丰富的Server市场工具集成会越来越容易。当前挑战与注意事项上下文限制这是最大的实践瓶颈。很多工具如Figma、文件系统返回的数据量巨大很容易占满模型的上下文窗口导致后续对话失忆或无法处理。Server开发者需要提供分页、过滤、摘要等功能使用者需要学会提出精准的查询。工具描述的精确性Tool的description和参数的description至关重要。大模型依赖这些文本来判断何时、如何调用工具。模糊的描述会导致错误的调用。错误处理与状态管理MCP本身是无状态的复杂的多步骤交互例如一个需要登录、多步操作的工具需要Server自身维护会话状态或由用户协调这对设计提出了更高要求。性能与延迟每次调用都涉及进程间通信IPC或网络请求可能会引入可感知的延迟。对于实时性要求高的场景需要优化。6. 故障排查与效能优化指南在实际使用和开发MCP时你会遇到各种问题。这里汇总了一些常见场景和解决思路。6.1 客户端连接与配置问题问题现象可能原因排查步骤与解决方案Claude Desktop/Cursor 启动后无MCP功能1. 配置文件路径错误。2. 配置文件格式错误JSON语法错误。3. Server启动命令错误或依赖未安装。1. 检查配置文件路径是否正确特别是跨平台时的路径分隔符。2. 使用JSON验证工具检查配置文件。3. 尝试在终端手动运行配置中的command和args看Server能否独立启动。查看客户端日志如Claude Desktop的帮助菜单中的“查看日志”。提示“无法连接到MCP Server”1. Server进程崩溃。2. 传输层不匹配如配置了HTTP但Server是stdio。3. 防火墙或权限问题。1. 检查Server代码是否有未捕获的异常查看Server的标准错误输出。2. 确认Client和Server约定的传输方式stdio/HTTP一致。3. 如果是HTTP Server检查端口是否被占用Client配置的URL是否正确。特定工具/资源不出现1. Server的list_tools/list_resources未正确实现或返回空。2. Client缓存了旧的Server信息。1. 使用MCP Inspector连接Server直接调用list_tools等方法验证返回数据。2. 重启Client有时需要完全退出再重新打开。6.2 Server开发与运行时问题问题现象可能原因排查步骤与解决方案Server启动后立即退出1. 依赖缺失。2. 代码中存在同步的顶级错误。3. 未正确等待异步连接。1. 确保package.json中的依赖已安装特别是modelcontextprotocol/sdk。2. 在代码开头添加try-catch或使用process.on(uncaughtException)捕获错误。3. 确保server.connect(transport)被await或在async函数中调用。Client调用工具无响应或超时1. Server的call_tool处理函数存在死循环或长时间阻塞。2. 未正确发送响应。1. 在Tool处理函数中添加超时逻辑对于耗时操作考虑异步处理并立即返回“处理中”状态如果协议支持。2. 确保处理函数最终会return一个符合协议格式的响应对象。返回内容被Client截断或格式错乱1. 返回的文本内容过长。2. MIME类型设置错误导致Client渲染异常。1. 对长文本进行分页或摘要。MCP协议支持分页机制可以分批返回资源内容。2. 对于非纯文本正确设置mimeType如图片用image/pngJSON数据用application/json。6.3 效能优化与最佳实践精简工具与资源描述Tool的name和description要简洁、准确避免冗长。清晰的描述能帮助AI更准确地选择工具。实现资源分页对于可能返回大量数据的资源如文件列表、数据库查询结果一定要实现分页。在list_resources的响应中提供nextCursor等分页令牌在read_resource时支持分页参数。这能有效避免一次性加载海量数据撑爆上下文。使用缓存对于变化不频繁的资源如静态文档、配置信息可以在Server端实现缓存机制减少对底层系统或API的重复调用提升响应速度。异步与流式响应未来方向关注MCP协议的更新。对于长时间运行的任务考虑支持异步操作或流式返回部分结果以提升用户体验。详细的错误信息在Tool调用失败时返回结构化的错误信息不仅包含错误代码更要有面向用户的、可读的解释帮助用户或AI理解下一步该怎么做。安全性是第一要务最小权限原则Filesystem Server只授予必要目录的访问权。输入净化对所有来自Client的输入如文件路径、API参数进行严格的验证和净化防止路径遍历、命令注入等攻击。密钥管理永远不要将API密钥、令牌等硬编码在代码或配置文件中。使用环境变量或安全的密钥管理服务。MCP协议正在快速发展社区每天都在涌现新的Server和创意。作为开发者拥抱这个协议意味着你正在为AI构建下一代的基础设施。从自动化繁琐任务到创造全新的人机交互体验可能性是无限的。我个人的体会是与其等待某个AI应用集成你需要的功能不如用MCP自己动手把它“连接”起来这种“即插即用”的能力整合才是AI时代真正的效率革命。开始动手从写一个简单的、解决你实际痛点的MCP Server开始吧。