MCP协议入门：构建AI智能体标准化工具扩展的完整指南

1. 项目概述：为什么MCP值得你花时间学习？

如果你最近在AI应用开发或者智能体（Agent）领域有所涉猎，大概率已经不止一次听到过“MCP”这个词了。它就像一阵风，迅速席卷了技术社区，从Hacker News的热帖到GitHub的Trending，再到各种技术播客的讨论，似乎一夜之间，不会MCP就有点跟不上趟了。但别慌，这阵风不是虚火，它背后确实解决了一个非常实在的痛点：如何让AI智能体更安全、更标准、更强大地使用外部工具和数据。

MCP，全称是Model Context Protocol，你可以把它理解为一套“智能体与外界的标准接线手册”。在它出现之前，每个AI应用、每个框架想要连接数据库、调用API、读取文件，都得自己写一套“接线”逻辑。这就像每个家电厂商都用自己独特的插头和电压，你每买一个新电器，就得重新改造一遍家里的电路，麻烦不说，还容易出错、不安全。MCP做的就是统一这个“插座”和“电压”标准。它定义了一套清晰的协议，让任何工具（我们称之为“资源”）都能以一种标准化的方式，将自己“能做什么”、“需要什么参数”、“如何调用”告诉AI智能体。而智能体这边，只需要学会“阅读”MCP协议，就能即插即用地使用成千上万种工具，无需为每一个工具单独编写适配代码。

所以，学习MCP，对于开发者、AI应用架构师甚至是技术决策者来说，绝不仅仅是追逐一个热点。它意味着你将掌握构建下一代可扩展、安全且易于集成的AI应用的核心基础设施。无论是想让你现有的ChatGPT变得更“能干”，接入公司内部的CRM系统；还是想从头构建一个能自动处理工单、查询库存、生成报告的自动化智能体，MCP都提供了那条最优雅、最规范的“高速公路”。今天，我们就从零开始，拆解MCP的核心，并动手实现第一个简单的MCP服务器，让你真切感受到它的威力。

2. MCP核心概念深度解析：协议、服务器与客户端

在动手写代码之前，我们必须把MCP的几个核心角色和它们之间的关系彻底理清。很多初学者容易在这里混淆，导致后续学习步履维艰。MCP的架构非常清晰，主要包含三个部分：协议（Protocol）、服务器（Server）和客户端（Client）。

2.1 协议（Protocol）：不可撼动的“宪法”

协议是MCP的基石，是一系列预先定义好的规则和消息格式。它规定了通信双方（服务器和客户端）之间“如何说话”。这包括：

• 传输层（Transport）：双方通过什么方式连接？目前主流是stdio（标准输入输出）和SSE（Server-Sent Events）。Stdio简单直接，适合本地集成；SSE则适用于网络环境。
• 消息格式（Message Format）：所有往来信息都必须包装成特定的JSON结构。每个消息都有type字段（如tools/list，tools/call）和对应的params或result内容。
• 生命周期（Lifecycle）：规定了连接初始化（initialize）、工具列表交换、工具调用、错误处理等一系列交互的先后顺序。

你可以把协议看作编程中的接口（Interface）或合同（Contract）。作为服务器开发者，你不需要关心协议底层如何实现，只需要按照协议规定的格式“说话”；作为客户端（通常是AI框架），它也只需要按照协议“听话”和“回话”。这种解耦带来了巨大的灵活性。

2.2 服务器（Server）：工具的“供应商”与“执行者”

MCP服务器是实际“干活”的一方。它的核心职责是：

1. 宣告能力（Advertising）：在连接建立时，告诉客户端：“我这里有这些工具可用。” 例如，一个数据库服务器会宣告“query_database”工具，一个文件服务器会宣告“read_file”、“list_files”工具。
2. 执行调用（Execution）：当客户端发起一个工具调用请求时，服务器需要执行相应的代码逻辑。比如，客户端调用query_database并传入SQL语句，服务器就需要连接数据库，执行查询，并将结果格式化返回。
3. 管理资源（Resource Management）：除了工具，MCP还定义了“资源”（Resources），可以理解为无需动态参数、可直接读取的内容（如一个静态的配置文件内容、一个只读的API端点描述）。服务器也可以宣告这些资源供客户端读取。

一个关键认知：MCP服务器本身不包含AI模型。它就是一个标准的、无状态的后台服务，可以用任何语言编写（Python、TypeScript、Go等）。它的智能体现在它提供的工具能完成特定领域的任务。

2.3 客户端（Client）：智能的“调度员”与“使用者”

客户端是使用MCP工具的一方。在绝大多数场景下，客户端就是一个AI应用框架或运行时环境，例如：

• Claude Desktop：Anthropic官方的桌面应用，可以通过配置直接连接本地或远程的MCP服务器，让Claude模型获得使用工具的能力。
• 自定义AI应用：你使用LangChain、LlamaIndex或直接调用OpenAI/Anthropic API构建的应用，可以集成MCP客户端库，从而动态加载和使用MCP服务器提供的工具。

客户端的职责是：

1. 发现工具：连接服务器，获取可用的工具列表及其模式（Schema）。
2. 决策与调用：基于AI模型的决策（或预设规则），选择合适的工具，并按照模式构造参数，发起调用请求。
3. 处理结果：接收服务器返回的结果，并将其整合到上下文中，供AI模型生成最终的回复给用户。

三者关系比喻：如果把AI智能体比作一个维修工程师，那么MCP协议就是他使用的标准维修手册语言。MCP服务器是各个专业的工具库（电工库、水管工库），每个库都按照手册语言登记了自己所有的工具（扳手型号、电表量程）。客户端则是工程师的大脑和手，他查阅手册，根据问题决定去哪个工具库借什么工具，然后按照标准流程使用工具解决问题。

注意：初学者常犯的一个错误是试图在MCP服务器里写AI逻辑。请牢记，服务器的职责是提供并执行工具，至于“何时用”、“为什么用”这个工具，是客户端和其背后的AI模型需要思考的。

3. 手把手构建你的第一个MCP服务器：一个天气查询工具

理论讲得再多，不如动手一试。我们将使用MCP生态中最流行的TypeScript SDK来构建一个最简单的MCP服务器。这个服务器提供一个工具：get_weather，根据城市名称返回模拟的天气信息。

3.1 环境准备与项目初始化

首先，确保你的开发环境已安装Node.js（版本18或以上）和npm。然后，我们创建一个新的项目目录并初始化。

mkdir my-first-mcp-server cd my-first-mcp-server npm init -y

接下来，安装MCP的核心依赖库@modelcontextprotocol/sdk。这个SDK提供了构建服务器和客户端所需的所有类型定义和工具函数。

npm install @modelcontextprotocol/sdk

同时，由于我们使用TypeScript，需要安装TypeScript及其类型定义。

npm install --save-dev typescript @types/node npx tsc --init

编辑生成的tsconfig.json，确保包含必要的配置，例如设置target为ES2022，module为NodeNext，以及outDir等。

3.2 核心代码实现：定义与响应工具

现在，创建我们的服务器主文件src/server.ts。

import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js'; // 1. 创建Server实例 const server = new Server( { name: 'weather-mcp-server', version: '0.1.0', }, { capabilities: { tools: {}, // 声明本服务器支持提供工具 }, } ); // 2. 定义工具列表 const tools = [ { name: 'get_weather', description: '获取指定城市的当前天气信息。', inputSchema: { type: 'object', properties: { city: { type: 'string', description: '城市名称，例如：Beijing, Shanghai, New York', }, }, required: ['city'], }, }, ]; // 3. 处理`tools/list`请求：当客户端询问有什么工具时，返回这个列表。 server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools, }; }); // 4. 处理`tools/call`请求：当客户端调用某个工具时，执行具体逻辑。 server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; if (name === 'get_weather') { const city = (args as { city: string }).city; // 模拟天气数据生成逻辑 const weatherConditions = ['晴', '多云', '阴', '小雨', '中雨', '大雪']; const randomCondition = weatherConditions[Math.floor(Math.random() * weatherConditions.length)]; const randomTemp = Math.floor(Math.random() * 30) + 10; // 10-39°C const result = { city, condition: randomCondition, temperature: `${randomTemp}°C`, humidity: `${Math.floor(Math.random() * 40) + 40}%`, // 40-79% wind: `${(Math.random() * 10).toFixed(1)} m/s`, reportTime: new Date().toLocaleTimeString(), }; // 返回格式化的结果。content可以是文本，也可以是更结构化的数据。 return { content: [ { type: 'text', text: `城市：${result.city}\n天气：${result.condition}\n温度：${result.temperature}\n湿度：${result.humidity}\n风速：${result.wind}\n报告时间：${result.reportTime}`, }, ], }; } // 如果收到未知的工具调用请求，抛出错误 throw new Error(`未知的工具：${name}`); }); // 5. 启动服务器，使用Stdio传输方式 async function main() { const transport = new StdioServerTransport(); await server.connect(transport); console.error('MCP天气服务器已启动，正在通过stdio等待连接...'); } main().catch((error) => { console.error('服务器启动失败:', error); process.exit(1); });

代码关键点解析：

1. Server初始化：我们创建了一个Server实例，并声明了它的名称、版本以及支持的能力（这里是tools）。
2. 工具模式（Schema）定义：get_weather工具的inputSchema非常重要。它用JSON Schema精确描述了客户端调用时必须传入的参数（city，字符串类型，必需）。AI客户端（如Claude）会读取这个模式，从而知道如何构造提问来获取必要参数。
3. 请求处理器（Request Handler）：这是服务器的核心。我们为两种类型的请求设置了处理器：ListToolsRequestSchema和CallToolRequestSchema。MCP SDK帮我们处理了底层的协议解析，我们只需关注业务逻辑。
4. 结果返回：工具调用的结果需要包装在content数组中。这里我们返回了type: 'text'的纯文本结果，便于AI直接阅读。你也可以返回type: 'image'或更复杂的数据结构。
5. Stdio传输：StdioServerTransport()意味着服务器通过标准输入（stdin）和标准输出（stdout）与客户端通信。这是与Claude Desktop等本地应用集成的最简单方式。

3.3 编译、运行与基础测试

首先，编译TypeScript代码。

npx tsc

这会在dist目录（取决于你的tsconfig.json配置）生成编译后的JavaScript文件。然后，我们可以直接运行它来测试服务器是否能正常启动。

node dist/server.js

如果看到“MCP天气服务器已启动，正在通过stdio等待连接...”的输出，并且进程没有退出，说明服务器正在正常运行，等待客户端连接。

如何进行快速测试？我们可以写一个极简的测试客户端，或者使用MCP SDK自带的测试工具。这里介绍一个更直观的方法：因为MCP协议本质是JSON消息交换，我们可以手动模拟一个客户端请求。但这比较繁琐。对于初学者，我强烈推荐使用mcp-test工具（需要额外安装）或直接配置到Claude Desktop中进行真实体验。

4. 在Claude Desktop中集成与调试你的MCP服务器

构建MCP服务器的终极目标是被AI应用使用。Anthropic的Claude Desktop应用是目前体验MCP最便捷的客户端。下面教你如何将我们刚写好的天气服务器配置进去。

4.1 配置Claude Desktop

Claude Desktop的配置通常位于以下目录：

• macOS:~/Library/Application Support/Claude/claude_desktop_config.json
• Windows:%APPDATA%\Claude\claude_desktop_config.json
• Linux:~/.config/Claude/claude_desktop_config.json

如果文件不存在，就创建它。编辑这个JSON文件，添加mcpServers配置项：

{ "mcpServers": { "weather": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/dist/server.js"], "env": {} } } }

关键参数说明：

• "weather"：这是你给这个服务器起的名字，会在Claude的界面中显示。
• command：启动服务器的命令，这里是node。
• args：命令的参数，第一个必须是你编译后的server.js文件的绝对路径。请务必替换成你的实际路径。
• env：可以设置环境变量，这里留空。

重要提示：修改配置后，必须完全重启Claude Desktop应用（不是关闭窗口，而是从任务栏/程序坞彻底退出再重新打开），配置才会生效。

4.2 在Claude中验证与使用

重启Claude Desktop后，新建一个对话。如果你看到输入框上方或侧边栏出现了新的工具图标（可能是一个螺丝刀或魔杖图标），或者名字叫“weather”，就说明配置成功了。

你可以尝试直接对Claude说：“使用天气工具查一下北京的天气。” 或者 “What‘s the weather like in Shanghai?”

Claude会识别到可用的get_weather工具，并自动向你追问所需的参数：“我需要使用天气工具。请问你想查询哪个城市？” 在你回复“北京”后，Claude会调用工具，并将服务器返回的模拟天气结果整合到它的回复中呈现给你。

这个过程的意义：你刚刚完成了一个完整的“AI智能体使用自定义工具”的闭环。你编写的服务器（工具提供方）和Claude（AI智能体）通过MCP协议进行了无缝的、类型安全的协作。Claude完全不需要事先知道你的服务器内部如何实现，它只依赖你提供的工具模式（Schema）。

4.3 调试技巧与日志查看

开发过程中，服务器难免出错。如何调试？

1. 服务器端日志：我们在代码中使用了console.error来输出日志。这些日志会输出到Claude Desktop启动服务器时创建的子进程的标准错误流中。在macOS上，你可以通过Console.app查看系统日志，筛选你的服务器进程名。更简单的方法是，在开发时，可以先在终端直接运行node dist/server.js，观察其输出，确保逻辑正确。
2. 客户端连接问题：如果Claude Desktop启动后没有显示你的工具，首先检查配置JSON的语法是否正确，路径是否绝对且有效。然后查看Claude Desktop自身的日志文件（位置因系统而异，通常在上述配置文件的同级或父级目录的Logs文件夹内）。
3. 协议级调试：对于复杂问题，你可能需要查看原始的MCP协议消息。可以在服务器初始化时增加调试选项，或者使用MCP_DEBUG=1环境变量（如果SDK支持）。更专业的做法是使用一个中间代理来截获并打印所有stdio流量。

5. 从示例到实践：扩展思路与进阶挑战

第一个“Hello World”级别的服务器跑通了，但这只是开始。MCP的真正力量在于连接真实世界的系统和数据。下面提供几个扩展方向，你可以选择其中一个作为接下来的学习目标。

5.1 扩展一：连接真实数据源

将我们的模拟天气服务器，改造成调用真实天气API（如和风天气、OpenWeatherMap）的服务器。

• 要点：在工具调用处理器中，使用fetch或axios发起网络请求。
• 挑战：如何处理API密钥等敏感信息？绝对不要硬编码在代码中。应该通过服务器的env配置传入，或在Claude Desktop配置的env字段中设置。
• 进阶：为工具增加更多参数，如units（温度单位）、forecast_days（预报天数），让工具更强大。

5.2 扩展二：实现更多工具类型

一个服务器可以提供多个工具。尝试添加以下工具：

• get_time：返回指定时区的当前时间。
• calculate：一个简单的计算器，处理数学表达式。
• search_files：在某个指定目录下搜索包含特定关键词的文件（注意：这涉及文件系统访问，权限和安全需谨慎考虑）。
• 资源（Resources）：尝试实现一个提供静态资源的服务器。例如，宣告一个company_handbook资源，当客户端读取它时，返回一段固定的公司手册文本。这用于提供无需参数的、只读的上下文信息。

5.3 扩展三：构建生产级服务器

让我们的服务器更健壮、更专业。

• 错误处理：在工具调用中增加更细致的错误处理。比如，城市不存在、网络超时、API限额用完等，都应该返回结构化的错误信息给客户端，而不是让进程崩溃。
• 输入验证：虽然JSON Schema定义了类型，但在服务器逻辑内部，仍应对输入进行业务逻辑验证。
• 日志与监控：集成像Winston、Pino这样的日志库，结构化地记录请求、响应和错误，便于后期排查。
• 配置管理：使用dotenv或config库来管理不同环境（开发、测试、生产）的配置。

5.4 理解SSE传输模式

我们目前使用的是Stdio传输，适合与本地应用程序集成。但如果你的服务器需要作为一个独立的网络服务，被远程的AI应用调用，就需要使用SSE（Server-Sent Events）传输。

• 区别：Stdio是同步的、一对一的。SSE是基于HTTP的，服务器启动一个HTTP服务，客户端通过HTTP连接并监听事件流。
• 应用场景：当你开发一个中央工具服务器，希望供多个AI助手或团队使用时，SSE是更合适的选择。MCP官方TypeScript SDK也提供了HTTPServerTransport来简化创建。

学习MCP的第一天，就像拿到了一把万能钥匙的毛坯。你了解了它的形状（协议）、学会了最基本的打磨方法（构建简单服务器）、并试了试它能打开的第一扇门（Claude Desktop）。这把钥匙的潜力远不止于此。接下来，你可以用它去打开数据库的大门、操作云资源的大门、连接企业内部所有系统的大门。关键在于，无论门后的世界多么复杂，你与AI智能体之间的交互语言，都已被MCP这把标准钥匙统一和简化。这，就是标准化协议带来的力量。