企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆

导读

本文围绕 VoltAgent 项目中关于 Model Context Protocol（MCP）的官方博客内容展开，系统讲解 MCP 是什么、为什么它对构建 AI Agent 至关重要，以及如何通过 VoltAgent 的MCPConfiguration把第三方 MCP 服务器（如文件系统服务器）接入自己的 Agent。读完本文，你将掌握 MCP 的核心概念、四种服务器传输类型（stdio / http / sse / streamable-http）的配置方式，并能从零搭建一个可以读写本地文件系统的 VoltAgent 实战项目。

MCP 是什么

把 AI Agent 想象成一个"罐子里的聪明大脑"：它非常擅长理解和生成语言，但被封闭在数字容器里，没有"手"也没有"眼睛"去直接操作外部世界——文件、网站、数据库、API 都不在它的直接触达范围内。要让 Agent 真正完成有用的任务，它需要工具（tools）。

MCP（Model Context Protocol，模型上下文协议）解决的核心问题就是"连接方式"。可以把它类比成一个万能转换插头或标准电源插座：如果你有一堆电动工具（电钻、电锯、打磨机），每个工具都需要一种完全不同的电源线，那将是一场噩梦；而 MCP 为 Agent 与工具（即"MCP 服务器"）之间的通信提供了一种标准方式。

有了这个标准，一个用支持 MCP 的框架构建的 Agent，就可以连接任何同样"说 MCP 语言"的服务或工具，例如：

• 访问本地计算机的文件系统（读写文件）；
• 浏览网页；
• 与数据库交互；
• 连接特定API（如 GitHub、Slack、Google Maps 等）；
• 运行本地脚本或应用程序。

对开发者来说，最大的收益是标准化：开发者可以创建一次 MCP 服务器，任何兼容的 Agent 都能直接使用；Agent 构建者也能轻松接入多样化的能力，而无需为每个工具手写大量定制集成代码。

为什么你应该关心 MCP

MCP 的实际价值体现在四个方面：

1. 更轻松的工具集成：不必成为每个 API 或系统的专家。只要有人已经为某个能力（如读取文件、搜索网页）构建了 MCP 服务器，通常只需在 Agent 配置里"插上"即可，更少的自定义代码、更快的开发。
2. 接入专业化工具：社区正在构建大量强大的 MCP 服务器（金融数据分析、智能家居控制、特定类型图片生成等），MCP 让你可以在自己的 Agent 中直接复用这些专业工作。
3. 可复用性：为一个目的构建的 MCP 服务器（例如与 GitHub 交互）不绑定某个特定 Agent 或框架。只要另一个 Agent 或平台支持 MCP，同一台服务器就能被复用——"构建一次，多处使用"。
4. 专注于 Agent 逻辑：MCP 处理了通信的"怎么做"，你可以把更多精力花在设计 Agent 的"做什么"和"为什么"上——目标、性格、核心决策逻辑——而不是陷在工具连接的管道细节里。

去哪里寻找 MCP 服务器

MCP 生态正在快速成长，虽然目前还没有一个官方的、包罗万象的单一目录，但可以从几个渠道寻找：

• 官方示例：MCP 的创建方（Anthropic）和社区维护着参考实现与示例服务器列表，是很好的起点；
• 社区聚合站：已有多个网站专门收集和分类社区开发的 MCP 服务器，这些站点往往是"宝矿"；
• 工具/平台文档：某些服务或工具（数据库、Stripe 这类 API 平台、甚至 Blender 这类软件）的官方文档中，可能会提到官方或社区构建的 MCP 服务器；
• 包管理器：在 npm（Node.js/TypeScript 项目）中搜索@modelcontextprotocol/server-*之类命名的包。

VoltAgent 与 MCP

VoltAgent 是一个开源 TypeScript AI Agent 框架（详见 README.md），它简化了复杂 AI Agent 的构建，负责处理状态管理、工具使用等基础设施问题，而 MCP 服务器的集成正是它的核心能力之一。

VoltAgent 集成 MCP 的核心思路是：在MCPConfiguration对象中声明要使用的服务器，然后把该配置提供的工具（tools）传给Agent。VoltAgent 会自动完成以下工作：

1. 启动服务器：运行你为 MCP 服务器指定的命令（如npx @modelcontextprotocol/server-filesystem ...）；
2. 连接：与运行中的服务器建立通信；
3. 获取工具：询问服务器它提供哪些能力（工具）；
4. 暴露工具：将这些工具（如readFile、writeFile）暴露给 Agent 的 LLM，使其理解并能决定是否使用。

你只需要声明"要哪个服务器、它在哪"，剩下的事情由 VoltAgent 负责接线。

从源码看 MCP 的传输层实现

从源码结构看，MCPConfiguration的底层客户端能力由MCPClient提供（packages/core/src/mcp/client/index.ts），它封装了官方 MCP SDK，并根据配置的type选择不同的传输实现：

• type: "stdio"：使用StdioClientTransport，以本地命令行子进程方式运行，通过标准输入/输出通信；构造函数中通过getDefaultEnvironment()继承默认环境变量，并可合并env与cwd配置（见 packages/core/src/mcp/types.ts 中的StdioServerConfig）；
• type: "http"：先尝试 Streamable HTTP，失败后自动回退到 SSE（对应HTTPServerConfig的"自动回退"设计，packages/core/src/mcp/types.ts）；
• type: "sse"：显式使用 SSE 传输（SSEServerConfig）；
• type: "streamable-http"：显式使用 Streamable HTTP，不做回退（StreamableHTTPServerConfig，可携带sessionId）。

同时，MCPClient.getAgentTools 会把 MCP 服务器返回的 JSON Schema 工具定义通过zod-from-json-schema转换成 zod schema，并以${serverName}_${toolName}的命名空间形式包装成 Agent 可执行的createTool工具——这就是readFile、writeFile等远程工具能被 Agent LLM 理解并调用的底层机制。MCPConfiguration（packages/core/src/mcp/registry/index.ts）则负责按服务器名管理客户端连接缓存，并提供getTools()、getToolsets()、getRawTools()等不同粒度的工具获取方式，还支持通过authorization配置在发现（discovery）和执行（execution）阶段对工具调用进行权限控制（filterOnDiscovery、checkOnExecution）。

此外，如果你希望反过来把 VoltAgent 的 Agent、工作流和工具暴露为 MCP 服务器（例如让 Cursor、Windsurf、VS Code 扩展等 MCP 客户端发现并调用），可以查看 examples/with-mcp-server/README.md：它演示了用@voltagent/mcp-server的MCPServer将注册表镜像到 MCP 客户端，并通过@voltagent/server-hono挂载 HTTP/SSE 路由（/mcp/*），也支持--stdio模式直接供 IDE 以子进程方式连接。示例完整代码见 examples/with-mcp-server/src/index.ts。

实战：用 VoltAgent 连接文件系统 MCP 服务器

下面我们来构建一个基础项目：连接标准的文件系统 MCP 服务器，让 Agent 能读取本地特定目录中的文件。完整的示例参考仓库中的 examples/with-mcp-server。

创建项目

最快的起步方式是使用create-voltagent-app命令行工具。我们把项目命名为mcp-filesystem-agent：

npm create voltagent-app@latest mcp-filesystem-agent

命令会引导你完成配置，多数选项使用默认值即可，但要记得选择TypeScript。（更多细节可参考 快速开始指南。）

完成后进入项目目录：

cd mcp-filesystem-agent

此时项目结构如下：

mcp-filesystem-agent/ ├── src/ │ └── index.ts # 主 Agent 逻辑写在这里！ ├── package.json # 项目依赖 ├── tsconfig.json # TypeScript 配置 ├── .gitignore # Git 忽略文件 └── .env # 存放 API Key（需要手动添加）

编写 Agent 与 MCP 配置

打开src/index.ts，设置 MCP 配置和 Agent 定义：

import { openai } from "@ai-sdk/openai"; import { VoltAgent, Agent, MCPConfiguration } from "@voltagent/core"; import { VercelAIProvider } from "@voltagent/vercel-ai"; // Node.js 'path' 模块用于生成安全、跨平台的文件路径 import path from "node:path"; const mcpConfig = new MCPConfiguration({ servers: { filesystem: { // 'stdio' 表示 VoltAgent 会把它作为本地命令行进程运行， // 并通过标准输入/输出与其通信。 type: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", path.resolve("./data")], }, }, }); const mcpAgent = new Agent({ name: "MCP Filesystem Agent", instructions: "You can interact with the local filesystem. List files, read files, write files.", llm: new VercelAIProvider(), model: openai("gpt-4o-mini"), tools: await mcpConfig.getTools(), }); new VoltAgent({ agents: { fsAgent: mcpAgent, }, });

代码逐段解析：

• MCPConfiguration：在这里定义filesystem服务器连接。
  • type: "stdio"告诉 VoltAgent 这是一个本地命令；
  • command: "npx"指定如何运行它；
  • args: [...]提供细节：MCP 服务器包（@modelcontextprotocol/server-filesystem），以及关键的path.resolve("./data")——这会把服务器"锁"在项目内的./data目录中，让它只能看到这个目录。之后必须实际创建data目录（mkdir data）！这对安全至关重要：MCP 服务器被限制在最小可见范围内，Agent 无法越界访问其他文件。
• Agent定义：创建Agent实例，核心是tools: await mcpConfig.getTools()。这一行告诉 VoltAgent："去连接我在mcpConfig里定义的所有服务器，找出它们提供的工具（比如文件系统服务器的readFile、writeFile），并把它们提供给这个 Agent 的 LLM 使用。"
• VoltAgent初始化：启动 VoltAgent 主服务器，并把mcpAgent注册到fsAgent这个键名下。这个键名就是之后在 VoltOps LLM 可观测性平台中选中该 Agent 的方式。

运行前的准备

运行前需要两样东西：LLM 的 API Key，以及我们限制 MCP 服务器访问的data目录。

1. 创建.env文件：在mcp-filesystem-agent项目根目录创建.env；
2. 添加 API Key：在.env中写入 OpenAI Key：

   OPENAI_API_KEY=your_openai_api_key_here

   （把your_openai_api_key_here替换为你的真实 Key）；

3. 创建data目录与测试文件：在项目根目录执行：

   mkdir data echo "Hello from the MCP agent's accessible file!" > data/test.txt

4. 安装依赖：

   npm install # 或 yarn install / pnpm install

5. 启动 Agent：

   npm run dev # 或 yarn dev / pnpm dev

启动后会看到 VoltAgent 服务器的启动信息，包括 VoltOps 平台的链接：

══════════════════════════════════════════════════ VOLTAGENT SERVER STARTED SUCCESSFULLY ══════════════════════════════════════════════════ ✓ HTTP Server: http://localhost:3141 VoltOps Platform: https://console.voltagent.dev ══════════════════════════════════════════════════

此时文件系统 MCP 服务器进程也会在后台自动启动。

在 Console 中测试

接下来就是见证时刻：

1. 打开控制台：在浏览器中访问 VoltOps 平台；
2. 找到 Agent：Agent 会以键名fsAgent（名称为 "MCP Filesystem Agent"）列出，点击进入；
3. 聊天：点击右下角的聊天图标打开聊天窗口；
4. 让它读取文件：输入并发送：Please read the file named test.txt in the data directory.

背后发生的事情（可以在控制台的 trace 中看到）：

1. Agent 收到消息；
2. LLM 理解用户想读取文件，并且看到自己有一个readFile工具可用（得益于 MCP 和 VoltAgent）；
3. Agent 决定调用readFile工具，传入参数test.txt；
4. VoltAgent 把这个工具调用路由到正在运行的文件系统 MCP 服务器进程；
5. MCP 服务器（被安全限制在./data目录内）读取test.txt并把内容返回；
6. VoltAgent 把内容回传给 Agent 的 LLM；
7. LLM 组织出类似"好的，我读了 test.txt 文件。内容是：Hello from the MCP agent's accessible file!"的回复，并在聊天中发给你。

就这样，Agent 通过 MCP 使用外部工具与本地文件系统完成了交互——完全符合预期。

总结

MCP 起初可能显得有些抽象，但真正跑通之后它的价值就清晰了：它确实像一个"万能转换插头"，让 AI Agent 只需配置正确的 MCP 服务器就能获得新能力（比如访问文件）。VoltAgent 让连接服务器到 Agent 的过程变得相当轻松——你声明服务器，框架负责启动、连接、拉取工具并暴露给 LLM。通过提供这层标准通信协议，MCP 为 Agent 安全、可靠地与海量外部系统交互打开了大门。

如果你想进一步探索，可以从仓库中的 examples/with-mcp-server 入手，查看完整的服务器端示例（MCPServer配置、stdio/HTTP/SSE 三种协议同时启用、工作流与 elicitation 适配器）；要深入理解客户端底层实现，可以阅读 packages/core/src/mcp/registry/index.ts 与 packages/core/src/mcp/client/index.ts。

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆