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

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载导读本文围绕 VoltAgent 项目中关于 Model Context ProtocolMCP的官方博客内容展开系统讲解 MCP 是什么、为什么它对构建 AI Agent 至关重要以及如何通过 VoltAgent 的MCPConfiguration把第三方 MCP 服务器如文件系统服务器接入自己的 Agent。读完本文你将掌握 MCP 的核心概念、四种服务器传输类型stdio / http / sse / streamable-http的配置方式并能从零搭建一个可以读写本地文件系统的 VoltAgent 实战项目。MCP 是什么把 AI Agent 想象成一个罐子里的聪明大脑它非常擅长理解和生成语言但被封闭在数字容器里没有手也没有眼睛去直接操作外部世界——文件、网站、数据库、API 都不在它的直接触达范围内。要让 Agent 真正完成有用的任务它需要工具tools。MCPModel Context Protocol模型上下文协议解决的核心问题就是连接方式。可以把它类比成一个万能转换插头或标准电源插座如果你有一堆电动工具电钻、电锯、打磨机每个工具都需要一种完全不同的电源线那将是一场噩梦而 MCP 为 Agent 与工具即MCP 服务器之间的通信提供了一种标准方式。有了这个标准一个用支持 MCP 的框架构建的 Agent就可以连接任何同样说 MCP 语言的服务或工具例如访问本地计算机的文件系统读写文件浏览网页与数据库交互连接特定API如 GitHub、Slack、Google Maps 等运行本地脚本或应用程序。对开发者来说最大的收益是标准化开发者可以创建一次 MCP 服务器任何兼容的 Agent 都能直接使用Agent 构建者也能轻松接入多样化的能力而无需为每个工具手写大量定制集成代码。为什么你应该关心 MCPMCP 的实际价值体现在四个方面更轻松的工具集成不必成为每个 API 或系统的专家。只要有人已经为某个能力如读取文件、搜索网页构建了 MCP 服务器通常只需在 Agent 配置里插上即可更少的自定义代码、更快的开发。接入专业化工具社区正在构建大量强大的 MCP 服务器金融数据分析、智能家居控制、特定类型图片生成等MCP 让你可以在自己的 Agent 中直接复用这些专业工作。可复用性为一个目的构建的 MCP 服务器例如与 GitHub 交互不绑定某个特定 Agent 或框架。只要另一个 Agent 或平台支持 MCP同一台服务器就能被复用——构建一次多处使用。专注于 Agent 逻辑MCP 处理了通信的怎么做你可以把更多精力花在设计 Agent 的做什么和为什么上——目标、性格、核心决策逻辑——而不是陷在工具连接的管道细节里。去哪里寻找 MCP 服务器MCP 生态正在快速成长虽然目前还没有一个官方的、包罗万象的单一目录但可以从几个渠道寻找官方示例MCP 的创建方Anthropic和社区维护着参考实现与示例服务器列表是很好的起点社区聚合站已有多个网站专门收集和分类社区开发的 MCP 服务器这些站点往往是宝矿工具/平台文档某些服务或工具数据库、Stripe 这类 API 平台、甚至 Blender 这类软件的官方文档中可能会提到官方或社区构建的 MCP 服务器包管理器在 npmNode.js/TypeScript 项目中搜索modelcontextprotocol/server-*之类命名的包。VoltAgent 与 MCPVoltAgent 是一个开源 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 中的StdioServerConfigtype: http先尝试 Streamable HTTP失败后自动回退到 SSE对应HTTPServerConfig的自动回退设计packages/core/src/mcp/types.tstype: sse显式使用 SSE 传输SSEServerConfigtype: 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 理解并调用的底层机制。MCPConfigurationpackages/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-agentnpm create voltagent-applatest 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 KeyOPENAI_API_KEYyour_openai_api_key_here把your_openai_api_key_here替换为你的真实 Key创建data目录与测试文件在项目根目录执行mkdir data echo Hello from the MCP agents accessible file! data/test.txt安装依赖npm install # 或 yarn install / pnpm install启动 Agentnpm 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 平台找到 AgentAgent 会以键名fsAgent名称为 MCP Filesystem Agent列出点击进入聊天点击右下角的聊天图标打开聊天窗口让它读取文件输入并发送Please read the file named test.txt in the data directory.背后发生的事情可以在控制台的 trace 中看到Agent 收到消息LLM 理解用户想读取文件并且看到自己有一个readFile工具可用得益于 MCP 和 VoltAgentAgent 决定调用readFile工具传入参数test.txtVoltAgent 把这个工具调用路由到正在运行的文件系统 MCP 服务器进程MCP 服务器被安全限制在./data目录内读取test.txt并把内容返回VoltAgent 把内容回传给 Agent 的 LLMLLM 组织出类似好的我读了 test.txt 文件。内容是Hello from the MCP agents 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 AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐VoltAgent MCP 接入指南用 Model Context Protocol 为 AI Agent 连接任意外部系统VoltAgent MCP 接入指南用 Model Context Protocol 为 AI Agent 连接任意外部系统 导读 本教程面向希望在 Volt人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Pydantic AI MCP Agent 实战基于 Model Context Protocol 无缝接入外部工具Pydantic AI MCP Agent 实战基于 Model Context Protocol 无缝接入外部工具 导读 本文将围绕 pydantic ai示例工程OpenManus 中的 MCPModel Context Protocol为 Agent 动态接入外部工具的即插即用协议OpenManus 中的 MCPModel Context Protocol为 Agent 动态接入外部工具的即插即用协议 本篇技术指南聚焦 OpenMa人工智能AI 应用AI Agent上一篇HeidiSQL完全攻略数据库管理零基础到精通下一篇5个关键场景深度解析go2rtc流媒体服务器的实战部署指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考