VoltAgent 与 MCP:用 Model Context Protocol 为 AI Agent 接入外部工具

原创2026-09-23 10:11:101,812 阅读
文章标签:人工智能AI AgentAgent 框架多智能体工具调用MCP 服务Agent 记忆RAGAgent 工作流Agent 编排可观测性AI 评测语音后端

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 的实际价值体现在四个方面:

  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。

登录后查看全文
voltagent