VoltAgent 与 MCP:用 Model Context Protocol 为 AI Agent 接入外部工具
VoltAgent 与 MCP:用 Model Context Protocol 为 AI 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 的实际价值体现在四个方面:
- 更轻松的工具集成:不必成为每个 API 或系统的专家。只要有人已经为某个能力(如读取文件、搜索网页)构建了 MCP 服务器,通常只需在 Agent 配置里"插上"即可,更少的自定义代码、更快的开发。
- 接入专业化工具:社区正在构建大量强大的 MCP 服务器(金融数据分析、智能家居控制、特定类型图片生成等),MCP 让你可以在自己的 Agent 中直接复用这些专业工作。
- 可复用性:为一个目的构建的 MCP 服务器(例如与 GitHub 交互)不绑定某个特定 Agent 或框架。只要另一个 Agent 或平台支持 MCP,同一台服务器就能被复用——"构建一次,多处使用"。
- 专注于 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 会自动完成以下工作:
- 启动服务器:运行你为 MCP 服务器指定的命令(如
npx @modelcontextprotocol/server-filesystem ...); - 连接:与运行中的服务器建立通信;
- 获取工具:询问服务器它提供哪些能力(工具);
- 暴露工具:将这些工具(如
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 目录。
- 创建
.env文件:在mcp-filesystem-agent项目根目录创建.env; - 添加 API Key:在
.env中写入 OpenAI Key:
(把OPENAI_API_KEY=your_openai_api_key_hereyour_openai_api_key_here替换为你的真实 Key); - 创建
data目录与测试文件:在项目根目录执行:mkdir data echo "Hello from the MCP agent's accessible file!" > data/test.txt - 安装依赖:
npm install # 或 yarn install / pnpm install - 启动 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 中测试
接下来就是见证时刻:
- 打开控制台:在浏览器中访问 VoltOps 平台;
- 找到 Agent:Agent 会以键名
fsAgent(名称为 "MCP Filesystem Agent")列出,点击进入; - 聊天:点击右下角的聊天图标打开聊天窗口;
- 让它读取文件:输入并发送:
Please read the file named test.txt in the data directory.
背后发生的事情(可以在控制台的 trace 中看到):
- Agent 收到消息;
- LLM 理解用户想读取文件,并且看到自己有一个
readFile工具可用(得益于 MCP 和 VoltAgent); - Agent 决定调用
readFile工具,传入参数test.txt; - VoltAgent 把这个工具调用路由到正在运行的文件系统 MCP 服务器进程;
- MCP 服务器(被安全限制在
./data目录内)读取test.txt并把内容返回; - VoltAgent 把内容回传给 Agent 的 LLM;
- 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。