@voltagent/mcp-server 全解析：用 Model Context Protocol 暴露 VoltAgent 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/mcp-server是 VoltAgent 框架的 MCPModel Context Protocol服务端包负责把 VoltAgent 注册表中的 Agent、工作流Workflow与工具Tool统一暴露为 MCP 工具供 VoltOps Console、Claude Desktop、Cline 等任意 MCP 兼容客户端调用。本篇文章以该包的 CHANGELOG 为主线结合源码实现与官方示例系统讲解包的能力演进、三种传输协议stdio / SSE / Streamable HTTP的接入方式、无状态 serverless 部署模式、Prompts/Resources/Elicitation 扩展能力以及 1.x 到 2.x 的迁移路径。读完本文你将能够独立把一个 VoltAgent 应用通过 MCP 协议暴露给任意 IDE 或客户端。一、包定位与版本演进脉络voltagent/mcp-server的核心定位见包 README是Model Context Protocol server package for VoltAgent——提供一个传输无关transport-agnostic的 MCP 服务端核心通过适配器对接 stdio、SSE、HTTP 三种传输方式从而把 VoltAgent 的 Agent、工作流、工具、Prompts、Resources 等一等公民构件first-class components暴露给外部 MCP 客户端。从 CHANGELOG 可以看到它的完整演进历程版本类型核心变更1.0.1Patch首次发布完整的 MCP 集成栈voltagent/mcp-server提供传输无关的 MCP Providerserver-core/server-hono提供现成的路由处理core导出共享类型1.0.2Patch客户端侧工具调用client-side tool calls与 Vercel AI hooksuseChat/useAssistant集成1.0.3Patch支持 provider 定义的工具如openai.tools.webSearch()工具归一化时原样透传 provider 元数据升级ai→^5.0.762.0.0 / 2.0.1 / 2.0.2Major / PatchVoltAgent 2.x 对齐 AI SDK v6API 兼容但需按上游 v6 迁移指南升级2.1.0Minor升级官方 MCP SDK 至 1.30.0新增无状态 Streamable HTTP 处理startHTTP、serverless模式与请求级流式选项当前包版本为2.1.0依赖modelcontextprotocol/sdk^1.30.0与voltagent/internal^1.0.2见 package.json以voltagent/core^2.0.0与zod作为 peerDependencies。1.0.1MCP 集成栈首发1.0.1 是包的诞生版本带来了完整的 MCP 集成方案voltagent/mcp-server通过 stdio / HTTP / SSE 传输暴露 VoltAgent 注册表Agent、工作流、工具voltagent/server-core与voltagent/server-hono内置现成的路由处理器HTTP 服务器只需少量胶水代码即可代理 MCP 流量voltagent/core导出 MCP 层共享的类型定义自动过滤子 Agentchild sub-agents并把 Agent 的purpose缺省回退到instructions提升为 MCP 工具描述使 IDE 中的工具列表更清晰启用 MCP 后REST 端点会发布到 Swagger/OpenAPI 中并在启动横幅startup banner中回显/mcp/*路由方便发现。1.0.2客户端侧工具1.0.2 加入了对客户端侧工具调用与 Vercel AI hooks 的一等支持工具可以在浏览器端运行不提供execute函数模型仍在服务端工具调用通过useChat/useAssistant的onToolCall在客户端自动拦截执行后借助addToolResult(toolCallId, payload)把结果回传给模型保留对话状态。配套示例见 examples/with-client-side-tools。1.0.3Provider 定义的工具1.0.3 支持 provider 预定义的工具例如 OpenAI 的openai.tools.webSearch()既可作为独立工具、也可作为 toolkit 的一部分注册工具归一化逻辑改为原样透传 provider 工具元数据避免信息丢失。二、快速上手构造一个 MCP 服务器MCPServer是包的核心类server.ts。它的构造参数分为三组身份信息name/version/description、暴露内容agents/workflows/tools、行为配置protocols、capabilities、filter、adapters、httpTransportOptions。CHANGELOG 1.0.1 中给出的最小示例完整定义一个带status工具的 Support Agent并把它暴露为 MCP 服务器import { MCPServer } from voltagent/mcp-server; import { Agent, createTool } from voltagent/core; import { openai } from ai-sdk/openai; import { z } from zod; const status createTool({ name: status, description: Return the current time, parameters: z.object({}), async execute() { return { status: ok, time: new Date().toISOString() }; }, }); const assistant new Agent({ name: Support Agent, instructions: Route customer tickets to the correct queue., model: openai(gpt-4o-mini), tools: [status], }); export const mcpServer new MCPServer({ name: voltagent-example, version: 0.1.0, description: Expose VoltAgent over MCP, agents: { support: assistant }, tools: { status }, filterTools: ({ items }) items.filter((tool) tool.name ! debug), });filterTools是一个过滤器函数用于在工具暴露前按需裁剪例如屏蔽调试工具。包内置了passthroughFilter与composeFilters可串联多个过滤器过滤器会收到{ items, context }其中context携带transportstdio/sse/http、sessionId、userRole、metadata等运行时信息见 filters.ts。与 VoltAgent 实例集成MCP 服务器注册到 VoltAgent 实例上之后同一批 Agent、工作流与工具即可从 VoltOps Console 或任意 MCP 兼容 IDE 中发现。CHANGELOG 中给出了通过 Hono 服务器托管、默认只开 stdio 的完整接线方式import { Agent, VoltAgent } from voltagent/core; import { MCPServer } from voltagent/mcp-server; import { honoServer } from voltagent/server-hono; const assistant new Agent({ name: AssistantAgent, purpose: Respond to support questions and invoke helper tools when needed., model: myModel, }); const mcpServer new MCPServer({ name: support-mcp, version: 1.0.0, agents: { assistant }, protocols: { stdio: true, http: false, sse: false }, }); export const voltAgent new VoltAgent({ agents: { assistant }, mcpServers: { primary: mcpServer }, server: honoServer({ port: 3141 }), // flip http/sse to true when you need remote clients });注意两点protocols配置项用于声明需要启用的传输方式默认三者stdio、http、sse都为true见 server.ts需要远程客户端时把http/sse翻转为true即可honoServer({ port: 3141 })负责承载 HTTP 服务。三、核心机制VoltAgent 构件如何映射为 MCP 工具MCP 协议本身只暴露工具tools作为可调用能力。MCPServer的做法是把 VoltAgent 的三种构件统一归一化为 MCP 工具定义ListToolsRequestSchema/CallToolRequestSchema并全部注册进一个工具注册表buildToolRegistry名称冲突时通过createUniqueName自动追加序号去重server.ts。Agent → 工具AgentAdapter 把每个 Agent 映射为一个工具输入 Schema 固定为prompt必填发给 Agent 的主提示词context可选上下文 Map 或对象转发给 Agent 执行conversationId用于记忆线程memory threading的会话标识userId转发给 VoltAgent 遥测的用户标识maxSteps本次调用的最大工具步数覆盖。工具描述优先取 Agent 的purpose其次回退到instructions最后是VoltAgent agent {name}。这就是 README 强调的为 Agent 提供一个面向用户的purpose文案可以让 MCP 客户端展示更友好的工具描述。执行时最终调用agent.generateText(prompt, options)并把text、finishReason、usage序列化为CallToolResult。Tool → 工具ToolAdapter 负责把 VoltAgent 工具转换为 MCP 工具通过 json-schema 工具函数把 zodparameters编译为 MCPinputSchema把outputSchema编译为 MCPoutputSchema工具自身的mcp.annotations与mcp._meta会被透传并附加toolId、toolType元数据。执行时调用tool.execute(args, operationContext)若配置了 elicitation 则通过 stub OperationContext 注入requestElicitation。Workflow → 工具WorkflowAdapter 为每个工作流注册两个工具运行工具workflow_{id}入参为input符合工作流 inputSchema 的载荷若定义了 schema 则为必填与options支持conversationId、userId、executionId、active、context、elicitation等覆盖项执行后返回executionId、workflowId、status、startAt、endAt、result以及可选的suspension/error/usage恢复工具workflow_{id}_resume入参为executionId必填、resumeData按工作流resumeSchema校验与可选的stepId通过deps.workflowRegistry.resumeSuspendedWorkflow恢复被挂起的工作流执行。这意味着 MCP 客户端可以完整驱动 VoltAgent 的挂起—恢复工作流模式先调用运行工具拿到挂起状态人工决策后调用恢复工具续跑。四、传输层stdio / SSE / Streamable HTTPMCPServer把传输抽象为注册表transports/registry.tsstartConfiguredTransports会按protocols配置并行启动所有已注册的传输server.tsenableStdio()则是单独启用 stdio 的快捷方法。stdio基于官方 SDK 的StdioServerTransport适合本地 CLI 工具、IDE 插件等子进程标准输入输出场景startStdioTransport在启用前会校验hasProtocol(stdio)server.ts。SSESSEServer-Sent Events模式由handleSseRequest处理ssePath负责建立事件流会话messagePath接收客户端 POST 的 JSON 消息会话以sessionId为键保存在sseSessions中并支持通过createExternalSseSession/handleExternalSseMessage接入外部 SSE 桥server.ts。Streamable HTTPHTTP 模式使用官方 SDK 的StreamableHTTPServerTransport。入口handleStreamableHttpRequest的完整处理流程server.ts依次为校验url.pathname httpPath否则返回 404合并httpTransportOptions构造时默认值与请求级options若启用无状态模式serverless或sessionIdGenerator: undefined走handleStatelessStreamableHttpRequest分支否则从 URL 查询参数或mcp-session-id请求头提取sessionId命中已有会话则复用其 transport 处理请求未命中且带 sessionId 则返回 404新会话要求 POST 且 body 为合法的 initialize 请求随后创建 transport、连接服务端实例并注册会话。五、无状态 Streamable HTTP 与 serverless 部署2.1.0 重点2.1.0 引入了startHTTP方法server.ts与无状态处理选项核心目标是服务水平扩展horizontal scaling与 serverless 部署。三种开启无状态模式的方式1. 请求级开启README 推荐写法每个请求都使用全新的 MCP server 与 transport 实例不签发mcp-session-idawait server.startHTTP({ url: new URL(req.url ?? /, http://localhost:3141), httpPath: /mcp, req, res, options: { serverless: true }, });2. 通过sessionIdGenerator: undefined开启显式禁用会话 ID 生成同样进入无状态模式。3. 通过构造参数设置默认值让内置的 VoltAgent HTTP 路由默认无状态无需包装请求处理器const server new MCPServer({ name: my-server, version: 1.0.0, httpTransportOptions: { serverless: true }, });无状态模式的行为细节从源码看server.ts无状态分支会为每个请求新建StreamableHTTPServerTransportsessionIdGenerator: undefined、基于当前过滤上下文新建 Server 实例并立即连接处理处理完即销毁天然适合无状态容器。关于响应格式与流式无状态请求默认返回JSON响应enableJsonResponse默认取!serverlessStreaming需要请求级 SSE 进度通知时设置serverlessStreaming: true此时响应切换为请求作用域request-scoped的 SSE 流式输出。types.ts 中的类型注释明确说明MCPStreamableHTTPTransportOptions是对官方StreamableHTTPServerTransportOptions的 Partial 扩展新增serverless与serverlessStreaming两个控制项。状态模式的保留能力README 明确列出仍依赖状态会话stateful的能力在无状态模式下不可用会话绑定的 elicitationsession-bound elicitation订阅subscriptions可恢复性resumability请求外通知out-of-request notifications。因此在设计部署形态时需要权衡如果 Agent/工作流需要人工介入elicitation、资源订阅或长时间挂起恢复应保留默认的状态模式。六、扩展能力Prompts、Resources、Logging 与 ElicitationMCPServer通过capabilities配置与adapters动态适配器types.ts支持四种可选能力构造时会自动推导默认值prompts默认跟随adapters.prompts是否存在resources同理logging与elicitation默认关闭server.ts。PromptsPromptBridge 支持两类 Prompt静态 PromptMCPStaticPromptConfigname/description/messages与动态 Prompt通过MCPPromptsAdapter的listPrompts/getPrompt提供。动态解析失败时自动回退到静态 PromptnotifyPromptListChanged可广播列表变更通知。ResourcesResourceBridge 通过MCPResourcesAdapter暴露listResources/readResource/listResourceTemplates并可选支持subscribe/unsubscriberegisterCapabilities中的resources.subscribe与listChanged标志跟随supportsNotifications动态决定。Logging当配置了MCPLoggingAdapter且 capabilities.logging 未显式关闭时MCPServer自动开启 logging 能力注册SetLevelRequestSchema处理器将 MCP 客户端的日志级别设置转发给loggingAdapter.setLevel。Elicitation人类介入Elicitation 能力允许 MCP 客户端作为人类审批通道工具或工作流执行过程中需要确认时通过ElicitRequestSchema请求客户端输入buildElicitationHandler优先调用elicitationAdapter.sendRequest否则回退到serverInstance.elicitInput。完整示例中展示了这一模式的实战形态confirm_action工具通过operationContext?.elicitation请求人工审批示例的elicitation适配器以自动批准作为演示回退。七、过滤、元数据与可观测性三类过滤器filterTools、filterAgents、filterWorkflows分别作用于工具、Agent 与工作流摘要返回过滤后的条目集合。Agent 过滤前会先移除子 AgentgetParentAgentIds判定顶层 Agent工作流则以WorkflowSummary含 id/name/purpose/step 数形态参与过滤server.ts。元数据与发现getMetadata()返回完整的服务器元数据id/name/version/protocols/capabilities/agents/workflows/tools/releaseDate/packages/remotes可供 VoltOps Console 或运维面板展示listTools(contextOverrides)与executeTool(name, args)则允许在服务端侧直接枚举与调用 MCP 工具不经过网络传输便于测试与编排。启用 MCP 后/mcp/*REST 路由会同步发布到 Swagger/OpenAPI 并在启动横幅中回显CHANGELOG 1.0.1无需翻代码即可发现端点。八、1.x → 2.x 迁移AI SDK v62.0.0Major标志着 VoltAgent 2.x 对齐 AI SDK v6。CHANGELOG 明确说明VoltAgent 自身的 API 保持兼容但如果你直接调用 AI SDK需要跟随上游 v6 迁移指南。迁移摘要如下1. 更新 VoltAgent 包npm run volt update如果 CLI 缺失先初始化npx voltagent/cli init npm run volt update2. 对齐 AI SDK 相关包pnpm add ai^6 ai-sdk/provider^3 ai-sdk/provider-utils^4 ai-sdk/openai^3如果使用 UI hooks还需升级ai-sdk/react到^3。3. 结构化输出 API 变更generateObject与streamObject在 VoltAgent 2.x 中已废弃请改用generateText/streamText配合Output.object(...)// 之前已废弃 // const result await generateObject({ ... }); // 之后 import { Output } from ai; const result await generateText({ model, prompt, output: Output.object({ schema }), });2.0.2 与 2.0.1 两个 Patch 版本进一步巩固了上述迁移同步更新了voltagent/internal1.0.1 / 1.0.2确保整个 monorepo 的依赖版本一致。九、综合示例with-mcp-server仓库中的 examples/with-mcp-server 是上述所有能力的集大成示例包含两个普通工具current_time当前时间、confirm_action通过 elicitation 请求人工审批三个 AgentStoryWriterAgent、TranslatorAgent、SupervisorAgent含 subAgents 委托以及带工具绑定的AssistantAgent一个可挂起/恢复的expense-approval工作流金额超过 $500 时suspend等待经理审批否则自动批准完整注册了 promptsexpense-triage静态提示、resourcesvolt://docs/expense-policy报销政策、elicitation演示自动批准适配器通过new VoltAgent({ mcpServers: { mcpServer }, server: honoServer({ port: 3141 }) })一体化启动。这个示例直接对应 CHANGELOG 1.0.1 中stdio-only 与 HTTP/SSE 两种配置的定位修改protocols字段即可在本地 stdio 调试与远程 HTTP/SSE 暴露之间切换。十、总结voltagent/mcp-server的定位非常清晰它是 VoltAgent 生态通往 MCP 世界的桥梁把框架内置的 Agent、工作流、工具、Prompt、Resource 与人工介入elicitation机制统一封装为 MCP 协议能力。从 1.0.1 的 MCP 集成栈首发到 2.1.0 的无状态 Streamable HTTP 与 serverless 支持包的演进始终围绕两个目标协议完整stdio/SSE/HTTP 全支持与部署灵活状态模式保证 elicitation、订阅、恢复等高级能力无状态模式适配水平扩展与 serverless。如果下一步想深入了解路由代理层可以继续阅读 server-hono 与 server-core 两个包的源码——它们正是 CHANGELOG 中提到的 MCP 流量代理搭档。赞分享人工智能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 接入外部工具导读本文围绕 VoltAgent 项目中人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音使用 VoltAgent MCP Server 将 Agents、工作流与工具暴露给任意 MCP 客户端使用 VoltAgent MCP Server 将 Agents、工作流与工具暴露给任意 MCP 客户端本文围绕仓库中的 with mcp server 示例人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音VoltAgent A2A Server 实战指南用 JSON-RPC 把 VoltAgent Agent 暴露给外部 AgentVoltAgent A2A Server 实战指南用 JSON RPC 把 VoltAgent Agent 暴露给外部 Agent 本篇技术指南围绕 vol人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

@voltagent/mcp-server 全解析：用 Model Context Protocol 暴露 VoltAgent Agent、工作流与工具

相关推荐

养殖龙虾（OpenClaw）必配的虾粮与工具：TaoToken 统一 Key 接入 Gateway 配置清单

Tekton Pipeline Cluster Resolver 实战指南：解析集群内 Task、Pipeline 与 StepAction 并理解其缓存与安全边界

2026年AI搜索优化价格行情与避坑指南：杭州国技互联参数详解

更多资讯

Server 2019 安装 Intel 无线网卡驱动失败？WLAN 服务与 INF 修改排障全攻略

C# API限流计数一次扣2？从请求重复与中间件顺序定位修复

C++模板编译期计算：从递归实例化到constexpr的现代实践

Python小屋编程题91-100复盘：语法进阶与高频陷阱解析

2026腾讯云服务器一年多少钱？30台CVM配置价格与选型指南

使用 Nacos + Higress 连接 Agent 和 MCP 服务进行使用：TaoToken 统一 Key 接入配置骨架

今日更新

AI元人文：从工具使用到思维重构的深度探索

Python+CNN车牌识别实战：从数据预处理到模型训练与部署

Vim基础操作全攻略：保存退出、模式切换与高频命令实战

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？