构建你自己的 MCP Server

目前,你的 AI 听起来很聪明……但当你要求它实际去做某件事时,它就有点卡住了。

它可以写作、解释和规划,但实际上无法访问你的工具或数据。
这就是 MCP 试图解决的差距。一旦你理解了它,事情就开始变得更加合理了。那么…

MCP 到底是什么?

想象一下你雇了一个出色的新助手。他们可以写作、推理、总结和规划。但每次你要求他们”查看今天的日程”或”查找那个客户的订单”时,他们都耸耸肩,因为他们无法访问你的系统。

这就是 Model Context Protocol (MCP) 要解决的问题。

它是一个开放协议,为 AI models 提供了一种标准化的方式来与外部工具和数据源对话。把它想象成 AI 的 USB:你不需要每次买新设备时都重新发明插头。你只需插上就能用。

MCP 对于 AI 工具就像 HTTP 对于 web 一样。一个让一切可互操作的通用契约。

在 MCP 之前,每个 AI 集成都是定制的。调用天气 API 的工具与查询数据库的工具完全不同。开发者必须手工编写粘合代码,models 必须针对每个集成进行特别训练或提示。这是一片混乱。

MCP 标准化了这个握手过程。你只需编写一次 server。任何兼容 MCP 的 AI client,如 Claude、GPT、Gemini,或任何未来支持该规范的 model,都可以自动发现并使用你的工具。

你为什么应该关心?

你可能在想,”我们已经有了 function calling。为什么还需要 MCP?”

好问题。Function calling 让 model 在你的应用中调用函数,但你要定义这些函数,你要托管它们,而且每个应用都在重新发明轮子。MCP 在 4 个关键方面有所不同:

– 标准化:一个规范,任何 client。编写一次 MCP server;任何兼容的 AI 都可以使用它而无需更改。

• 可发现:Servers 在运行时广播其能力。AI 自动学习存在哪些工具。
• 沙箱化:Server 是一个独立进程。你的 AI host 永远不会直接访问文件或数据库,只能访问你暴露的内容。
• 可组合:同时附加多个 MCP servers。Claude 获得所有工具的统一视图。

简而言之,MCP 将一次性的 AI 集成转变为可重用、可互操作的组件。

那么,MCP 是如何工作的?

实际上 MCP 遵循经典的 client-server 架构。但让我们准确说明谁是谁,因为这会让人困惑。



MCP 世界中有三个角色:

– Host:用户运行的应用程序(Claude Desktop、你的 IDE、自定义聊天 UI)。它包含 AI model 和 MCP client。

• MCP Client:位于 host 内部。管理与一个或多个 MCP servers 的连接。它与 MCP Client 对话。Client 与你的 server 对话。你的 server 与数据库对话。每一跳都是干净且受控的。
• MCP Server:你编写和部署的轻量级进程。它通过标准的 JSON-RPC 接口暴露能力(tools、resources、prompts)。

这里有个关键的心智模型:AI model 永远不会直接与你的数据库对话。它与 MCP Client 对话。Client 与你的 server 对话。你的 server 与数据库对话。每一跳都是干净且受控的。

你必须知道的核心概念

MCP 有三个基本元素。充分理解它们会让其他一切都变得简单。

1. Tools

Tools 是 AI 可以调用的操作,会产生副作用或获取动态数据的事物。例如:发送邮件、运行查询、调用 API。

每个 tool 都有一个名称、一个描述(AI 读取以理解何时使用)以及定义其输入的 JSON schema。

2. Resources

Resources 是 AI 可以读取的数据——文件、文档和数据库行。与 tools 不同,它们是只读的,并通过 URI 标识(如 file:///path/to/doc.md 或 db://customers/42)。

Resources 可以是静态的(每次都相同)或动态的(从你的 server 实时获取)。

3. Prompts

Prompts 是你的 server 暴露的可重用 prompt 模板。它们可以包含动态参数,并像宏一样工作——对于标准化 AI 如何处理特定于你领域的常见任务很有用。

> Tools = 做某事。  

Resources = 读取某物。  

• Prompts = 以标准方式说某事。

理论够了。让我们构建点东西。

你的第一个 MCP server

我们将使用官方的 TypeScript SDK。它目前是最成熟的,拥有最好的工具。

前提条件

– 已安装 Node.js 18+

• 一个你熟悉的终端
• Claude Desktop(稍后用于测试)

1. 创建一个新项目

从一个新目录开始并初始化 Node 项目。

2. 更新 tsconfig.json

确保你的 TypeScript 配置为现代 Node。

3. 创建你的 server 文件

创建 src/index.ts——这是你 MCP server 的核心。

这里你的 server 运行时做两件事:首先,它通过 ListTools 告诉 client “这是我的工具”。然后当 AI 决定使用某个工具时,它触发 Call Tool,你来处理它。这就是整个契约。

添加 Tools、Resources 和 Prompts

让我们深入一点。以下是如何将所有三个基本元素添加到你的 server。

添加一个真实的 Tool(带外部调用)

这个 tool 获取某个城市的当前天气。与之前的模式相同,但现在内部有一个真实的 fetch 调用。

添加 Resources

Resources 通过两个处理程序暴露:一个列出所有可用资源,另一个通过 URI 读取特定资源。

添加 Prompts

Transport 层解释

MCP 将协议与 transport 分离。相同的 JSON-RPC 消息可以根据你的部署通过不同的通道流动。有两个主要选项:

– stdio:用于本地工具、CLI 应用和开发。它是如何工作的?Host 将你的 server 作为子进程启动。消息通过 stdin/stdout 传递。

• HTTP + SSE:用于远程 servers、web 部署和多用户。它是如何工作的?Server 监听 HTTP。Client 通过 POST 发送请求;server 通过 SSE 推送响应。

对于本地开发(与 Claude Desktop 对话),stdio 几乎总是正确的选择。它非常简单;没有端口、没有认证、没有 CORS。只是一个进程与另一个进程对话。

一旦你想将 server 暴露给远程用户或部署到云端,就切换到 HTTP + SSE。

让我们做一些真实世界的事情。

File Explorer MCP

让我们构建一些真正有用的东西。一个 MCP server,让 Claude 读取和列出你本地机器上的文件。这是有用 MCP servers 的”hello world”。

> 永远不要在生产环境中暴露不受限制的文件读取工具。始终验证请求的路径是否在允许的根目录内。使用 path.resolve() 并检查结果是否以你允许的前缀开头。

将你的 server 连接到 Claude

你的 server 已经准备好了。现在让我们将它连接到 Claude Desktop,这样你就可以实际与它对话了。

1. 构建你的 server

首先将 TypeScript 编译为 JavaScript。

2. 打开 Claude Desktop 配置

找到你操作系统的配置文件:

– macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows:%APPDATA%\Claude\claude_desktop_config.json

3. 将你的 server 添加到配置中

4. 重启 Claude Desktop

完全退出并重新打开 Claude。你的 server 将出现在工具面板中。尝试问,”列出我桌面文件夹中的文件。”

常见陷阱和调试技巧

你会遇到这些。这是简短列表:

❌ “Server not found” 或无法连接



最常见的问题。检查 claude_desktop_config.json 中的路径是绝对路径(在 Mac 上以 / 开头,在 Windows 上以 C:\ 开头)。相对路径不起作用,因为 Claude Desktop 不知道你的工作目录。

❌ “Tool returned an error” 没有详细信息

在整个 tool 处理程序周围添加 try/catch,并将错误作为文本响应返回而不是抛出。Claude 然后可以读取并向你解释它。

❌ stdout 污染导致连接崩溃



使用 stdio transport 时,永远不要使用 console.log。stdio 通道保留用于 MCP 消息;任何其他字节都会破坏流。改用 console.error(它进入 stderr,这是独立的)。

❌ Schema 不匹配:AI 使用错误的参数调用你的 tool

在输入 schema 中要具体。模糊的描述会导致 AI 猜测错误的参数类型。在描述字符串中添加示例;它们真的很有帮助。

🛠 使用 MCP Inspector

Anthropic 提供了一个调试工具:npx @modelcontextprotocol/inspector。运行它,指向你的 server,你可以手动触发 tool 调用来测试你的 server,完全不涉及 Claude。当某些东西不工作时首先使用它。

MCP 生态系统发展迅速。

查看 modelcontextprotocol.io 获取最新的规范更新。

以及 github.com/modelcontextprotocol 学习社区 servers。

现在去构建点东西吧。你的 AI 助手一直在等待你工具的钥匙。