人工智能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 官方提供的 Model Context ProtocolMCP服务端实现包负责把 VoltAgent 的 Agent、Workflow 和 Tool 以统一的方式暴露给任意 MCP 客户端如 Claude、Cursor 等支持 MCP 的宿主应用。它以传输无关transport-agnostic的核心为底座内置 stdio、SSE 和 Streamable HTTP 三种传输适配并针对云原生场景提供了serverless无状态模式。读完本文你将掌握如何构建并启动一个 MCP 服务、purpose元数据如何影响客户端展示、Streamable HTTP 有状态会话与无状态部署的取舍以及各适配器在源码层面的映射机制。包定位一个传输无关的 MCP 服务端核心从 packages/mcp-server/README.md 的定义看该包提供的是shared utilities for exposing VoltAgent agents, workflows, and tools through the Model Context Protocol即核心是共享工具集而不是绑定某个框架的胶水代码传输无关transport-agnostic同一个MCPServer实例可以同时对接 stdio、SSE、HTTP 三类传输每个被暴露的 VoltAgent 实体Agent / Workflow / Tool都会在 MCP 侧被描述为一个个tool工具客户端通过tools/list与tools/call完成发现与调用。包的版本、依赖与构建信息可以从 packages/mcp-server/package.json 确认当前版本为2.1.0直接依赖官方modelcontextprotocol/sdk^1.30.0与voltagent/internal以voltagent/core和zod作为 peerDependencies构建产物为 ESMdist/index.mjs与 CJSdist/index.js双格式。注意README 中明确标注该包目前处于活跃开发期API 在首个公开版本发布前视为不稳定unstable。在生产依赖之前请锁定具体版本并跟踪 CHANGELOG见 packages/mcp-server/CHANGELOG.md。开发与构建在仓库根目录使用 pnpm 工作区命令即可完成依赖安装与定向构建pnpm install pnpm build --filter voltagent/mcp-server如果需要持续开发模式包内也提供了devtsup --watch、testvitest与typechecktsc --noEmit脚本见 packages/mcp-server/package.json。Agent 元数据purpose如何变成 MCP Tool 描述这是 README 中最重要的使用提示当一个 Agent 通过 MCP 暴露时它的purpose字段会被用作 MCP tool 的 description。客户端例如聊天 IDE 的工具面板、Agent 调度器会把这个描述展示给用户或上层模型因此应当填写一句面向用户、简洁明了的解释性文案。如果purpose为空适配器会回退到 Agent 的 instructions指令。源码层面的实现位于 packages/mcp-server/src/adapters/agent.ts 的toMcpToolconst purpose typeof agent.purpose string ? agent.purpose.trim() : undefined; const instructions typeof agent.instructions string ? agent.instructions.trim() : undefined; const description purpose purpose.length 0 ? purpose : instructions instructions.length 0 ? instructions : VoltAgent agent ${agent.name};可见回退链条是purpose→instructions→ 兜底文案VoltAgent agent name。与此同时Agent 的id会被写入 MCP tool 的_meta.agentIdname会同时出现在title与annotations.title中方便客户端识别实体来源。与 Agent 相似Workflow 的描述取自workflow.purpose ?? VoltAgent workflow name见 packages/mcp-server/src/adapters/workflow.ts而普通 Tool 则直接使用tool.description作为 MCP description见 packages/mcp-server/src/adapters/tool.ts。因此在定义 VoltAgent 实体时就写好purpose/description是让 MCP 侧展示体验可读的关键习惯。核心类 MCPServer 与配置项所有能力都收敛在MCPServer类上packages/mcp-server/src/server.ts。构造时传入MCPServerConfig完整类型定义见 packages/mcp-server/src/types.ts配置项类型说明id/name/versionstring服务标识与版本id缺省时由name规范化生成小写、-连接、去除首尾符号descriptionstring服务描述同步给 MCP SDK 的Server实例protocols{ stdio?, sse?, http? }各传输开关均默认为true由hasProtocol()与startConfiguredTransports()统一消费httpTransportOptionsMCPStreamableHTTPTransportOptionsStreamable HTTP 的默认传输选项如serverless请求级选项优先filterTools/filterAgents/filterWorkflowsFilterFunction过滤函数缺省为passthroughFilter()原样返回capabilities{ logging?, prompts?, resources?, elicitation? }MCP 能力开关详见下文agents/workflows/toolsRecord以配置方式补充的实体与依赖注入的注册表合并去重后取顶层实体releaseDate/packages/remotes元数据服务发布信息、包信息与远端环境信息写入getMetadata()结果adapters动态适配器logging/prompts/resources/elicitation四类适配器覆盖依赖注入的同名接口MCPServer.initialize(deps)负责注入运行时依赖agentRegistry、workflowRegistry 以及各类适配器并据此自动翻转能力开关例如提供了loggingAdapter.setLevel才启用 logging 能力提供 prompts 适配器才启用 prompts 能力见initialize()与registerCapabilityHandlers()位于 packages/mcp-server/src/server.ts 的 L206-L257 与 L1041-L1121。因此典型启动流程是const server new MCPServer({ name: my-server, version: 1.0.0, protocols: { stdio: true, http: true, sse: true }, tools: { /* 可选额外配置的工具 */ }, }); server.initialize({ agentRegistry: { getAllAgents: () [...], getAgent: (id) ... }, workflowRegistry: { getAllWorkflows: () [...], resumeSuspendedWorkflow: async (...) ... }, }); await server.startConfiguredTransports(); // 按 protocols 开关批量启动三大传输的启动方式stdiostartStdioTransport()创建StdioServerTransport并挂载到共享的 MCPServer上通过传输注册表packages/mcp-server/src/transports/registry.ts中的StdioTransport控制器封装packages/mcp-server/src/transports/stdio.ts。适合本地子进程如 Claude Desktop 的本地 MCP 配置。SSEhandleSseRequest()处理ssePathSSE 事件流与messagePathPOST 消息两条路由基于 SDK 的SSEServerTransport每条 SSE 连接都会在sseSessions中登记并支持createExternalSseSession()创建外部桥接会话packages/mcp-server/src/transports/external-sse.ts。Streamable HTTPhandleStreamableHttpRequest()/startHTTP()MCP 官方推荐的新一代 HTTP 传输默认有状态会话可切换无状态是本文档讲解的核心详见下一节。能力Capabilities一览MCPServer在初始化时向 SDK 注册能力声明packages/mcp-server/src/server.ts 的registerCapabilityHandlerstools始终注册{ tools: {} }并挂载tools/list与tools/call处理器prompts注册prompts/list与prompts/get通过PromptBridge代理到 prompts 适配器packages/mcp-server/src/capabilities/prompts.tsresources注册resources/list、resources/read、resources/templates/list以及可选的subscribe/unsubscribepackages/mcp-server/src/capabilities/resources.tslogging注册logging/setLevel代理到 logging 适配器elicitation注册ElicitRequestSchema处理器优先使用elicitationAdapter.sendRequest否则回退到 SDK 内置的elicitInputpackages/mcp-server/src/server.ts 的 L1170-L1178。Streamable HTTP有状态会话与 serverless 无状态模式默认行为有状态会话在默认配置下startHTTP遵循 Streamable HTTP 规范的有状态流程见handleStreamableHttpRequest的实现packages/mcp-server/src/server.ts 的 L414-L519仅接受POST作为初始化请求GET/DELETE用于会话管理非 POST 的初始化请求返回 400校验 body 必须是合法的initialize载荷否则返回 400用sessionIdGenerator: () randomUUID()生成会话 ID并通过StreamableHTTPServerTransport的onsessioninitialized/onsessionclosed回调把会话登记进httpTransports/httpServerInstances两张 Map后续带mcp-session-id头或?sessionId查询参数的请求会被路由到对应会话的 transportextractSessionId同时支持两种传递方式。会话生命周期由服务端管理close()会关闭全部传输与会话L300-L318。serverless每次请求一个全新实例对于水平扩展或 serverless无服务器部署有状态会话往往不可行——多实例之间没有共享的会话表。此时在请求级选项里开启serverless: trueawait server.startHTTP({ url: new URL(req.url ?? /, http://localhost:3141), httpPath: /mcp, req, res, options: { serverless: true }, });这就是 README 给出的推荐写法。其效果是每个 HTTP 请求都会使用一个全新的 MCP server 实例与全新的 transport 实例且不会签发mcp-session-id。源码中对应handleStatelessStreamableHttpRequestpackages/mcp-server/src/server.ts 的 L521-L540它创建sessionIdGenerator: undefined的 transport、为当前上下文新建 server 实例、连接后立即处理请求。另一种无状态开关sessionIdGenerator: undefined除了serverless: true显式把sessionIdGenerator设置为undefined同样会进入无状态模式。handleStreamableHttpRequest中专门用hasOwnProperty检查该字段是否存在且为undefinedL430-L445只要二者满足其一即走无状态分支。这在不想包一层请求处理函数的场景下非常有用——例如 examples/with-cerbos/src/mcp-server.ts 里直接创建new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })并每请求新建 server 的做法本质就是这一思路。serverlessStreaming请求级 SSE 进度通知无状态请求默认返回 JSONenableJsonResponse默认为!serverlessStreaming即未开启 streaming 时返回 JSON。当需要把 LLM 生成或 Workflow 执行的中间进度实时推给客户端时可以设置options: { serverless: true, serverlessStreaming: true }此时每个请求使用请求级request-scoped的 SSE输出流式通知而不是有状态的长连接。serverlessStreaming是 VoltAgent 在 SDK 选项之上扩展的字段类型定义在 packages/mcp-server/src/types.ts 的MCPStreamableHTTPTransportOptions中{ serverless?: boolean; serverlessStreaming?: boolean }。有状态功能在无状态模式下的限制README 特别提醒无状态模式无法支持会话绑定的能力。以下功能仍然要求有状态stateful模式会话内 elicitation请求式输入收集Agent/Workflow 在执行中需要向客户端提问并等待回答依赖会话内往返订阅subscriptionsresources 的subscribe/ 变更通知可恢复性resumabilityWorkflow 挂起后的resume流程依赖已登记的会话与注册表状态请求外通知out-of-request notifications服务端主动推送的事件无状态请求结束后没有承载通道。因此在选用 serverless 之前应先确认业务是否依赖上述能力若是应保留有状态会话或在架构上引入共享会话存储。服务端默认配置无状态httpTransportOptions如果不想在每次请求都传入serverless: true可以在构造MCPServer时把默认值写进配置使内置的 VoltAgent HTTP 路由整体变为无状态const server new MCPServer({ name: my-server, version: 1.0.0, httpTransportOptions: { serverless: true }, });请求级options会覆盖构造时的httpTransportOptions两者再与已废弃的transportOptions合并见 packages/mcp-server/src/server.ts 的 L425-L429。这也是 README 提供的第三种无状态配置方式适合把 MCP 路由内嵌进现有 VoltAgent HTTP 服务的场景。工具名映射Tool / Agent / Workflow 如何变成 MCP toolsbuildToolRegistry()把三类实体统一编译成一张name - RegisteredToolEntry的工具表packages/mcp-server/src/server.ts 的 L1006-L1016Tool以tool.name || tool.id为基名sanitize 后_meta.toolType toolAgent以agent_id无 id 则用 name为基名_meta.toolType agent其输入 schema 固定为{ prompt(必填), context?, conversationId?, userId?, maxSteps? }执行时调用agent.generateText(prompt, options)并把text、finishReason、usage序列化为 JSON 文本返回packages/mcp-server/src/adapters/agent.tsWorkflow每个 Workflow 会生成两个工具——workflow_id执行与workflow_id_resume恢复挂起执行。执行工具要求input当 Workflow 声明了inputSchema时必填返回执行快照{ executionId, workflowId, status, startAt, endAt, result, ... }resume 工具要求executionId调用workflowRegistry.resumeSuspendedWorkflow()恢复packages/mcp-server/src/adapters/workflow.ts 的 L236-L305。命名冲突时通过createUniqueName追加_1、_2等后缀消解名称统一经过sanitizeName仅保留[a-zA-Z0-9_-]。此外filters.tspackages/mcp-server/src/filters.ts提供了FilterContext含transport: stdio | sse | http、sessionId、userRole、metadata与composeFilters可在不同传输、不同角色下对暴露的 Agent/Workflow/Tool 做细粒度裁剪例如按userRole隐藏管理类工具——这正是 examples/with-cerbos 示例中权限由 VoltAgent 的 MCP 配置层处理的设计基础。测试验证与部署佐证仓库内为上述无状态行为提供了完整的端到端测试packages/mcp-server/src/server.spec.ts使用真实的node:http服务器 MCP SDK 客户端验证了serverless 模式下initialize、initialized、tools/list、tools/call全流程不产生会话多个MCPServer实例轮流处理请求均无mcp-session-id头往返有状态模式下会话 ID 的正确登记、复用与清理。在部署侧examples/with-cloudflare-workers/src/index.ts展示了把 VoltAgent 以serverlessHono()toCloudflareWorker()发布为无服务器 Worker 的完整形态examples/with-netlify-functions/netlify/functions/voltagent.ts则是 Netlify Functions 上的对应做法。结合本文档的serverless: true即可把 MCP 端点发布到任意支持无状态 HTTP 的边缘平台。总结voltagent/mcp-server的价值在于用一套 transport-agnostic 的核心把 VoltAgent 的 Agent / Workflow / Tool 统一映射为 MCP tools并针对现代部署形态提供了完备的无状态 HTTP 方案。落地时的关键决策点可归纳为写好实体的purpose/description让 MCP 客户端展示可读本地进程用 stdio长连接场景用 SSE标准 HTTP 场景用 Streamable HTTP水平扩展 / serverless 部署时用serverless: true或sessionIdGenerator: undefined切无状态需要流式进度时再加serverlessStreaming: true依赖 elicitation、订阅、Workflow 可恢复性、请求外通知等会话级能力时必须保留有状态模式通过httpTransportOptions在服务端整体默认无状态通过filter*与FilterContext按传输、角色裁剪暴露面。该包基于 MIT 协议开源见 packages/mcp-server/README.md 与 packages/mcp-server/package.json当前处于活跃开发期接入时请以仓库实际版本与 CHANGELOG 为准。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Agent OS MCP 工具参考通过 Model Context Protocol 暴露的 8 个内核治理原语Agent OS MCP 工具参考通过 Model Context Protocol 暴露的 8 个内核治理原语 Agent OS 将内核级治理能力代码安全人工智能AI AgentAI 安全治理策略引擎Agent 沙箱认证鉴权Genkit MCP Server 实战指南通过 Model Context Protocol 打通 LLM Agent、IDE 与 Genkit FlowGenkit MCP Server 实战指南通过 Model Context Protocol 打通 LLM Agent、IDE 与 Genkit Flow人工智能大模型后端AI AgentRAG工具调用CAMEL Agent MCP Server 实战指南将 CAMEL 多智能体以 Model Context Protocol 标准对外暴露CAMEL Agent MCP Server 实战指南将 CAMEL 多智能体以 Model Context Protocol 标准对外暴露 导读 本文围绕人工智能大模型AI AgentAgent 框架多智能体工具调用MCP ClientsRAG模型评测数据生成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 VoltAgent MCP Server 使用指南：通过 Model Context Protocol 暴露 Agent、Workflow 与 Tool
人工智能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 官方提供的 Model Context ProtocolMCP服务端实现包负责把 VoltAgent 的 Agent、Workflow 和 Tool 以统一的方式暴露给任意 MCP 客户端如 Claude、Cursor 等支持 MCP 的宿主应用。它以传输无关transport-agnostic的核心为底座内置 stdio、SSE 和 Streamable HTTP 三种传输适配并针对云原生场景提供了serverless无状态模式。读完本文你将掌握如何构建并启动一个 MCP 服务、purpose元数据如何影响客户端展示、Streamable HTTP 有状态会话与无状态部署的取舍以及各适配器在源码层面的映射机制。包定位一个传输无关的 MCP 服务端核心从 packages/mcp-server/README.md 的定义看该包提供的是shared utilities for exposing VoltAgent agents, workflows, and tools through the Model Context Protocol即核心是共享工具集而不是绑定某个框架的胶水代码传输无关transport-agnostic同一个MCPServer实例可以同时对接 stdio、SSE、HTTP 三类传输每个被暴露的 VoltAgent 实体Agent / Workflow / Tool都会在 MCP 侧被描述为一个个tool工具客户端通过tools/list与tools/call完成发现与调用。包的版本、依赖与构建信息可以从 packages/mcp-server/package.json 确认当前版本为2.1.0直接依赖官方modelcontextprotocol/sdk^1.30.0与voltagent/internal以voltagent/core和zod作为 peerDependencies构建产物为 ESMdist/index.mjs与 CJSdist/index.js双格式。注意README 中明确标注该包目前处于活跃开发期API 在首个公开版本发布前视为不稳定unstable。在生产依赖之前请锁定具体版本并跟踪 CHANGELOG见 packages/mcp-server/CHANGELOG.md。开发与构建在仓库根目录使用 pnpm 工作区命令即可完成依赖安装与定向构建pnpm install pnpm build --filter voltagent/mcp-server如果需要持续开发模式包内也提供了devtsup --watch、testvitest与typechecktsc --noEmit脚本见 packages/mcp-server/package.json。Agent 元数据purpose如何变成 MCP Tool 描述这是 README 中最重要的使用提示当一个 Agent 通过 MCP 暴露时它的purpose字段会被用作 MCP tool 的 description。客户端例如聊天 IDE 的工具面板、Agent 调度器会把这个描述展示给用户或上层模型因此应当填写一句面向用户、简洁明了的解释性文案。如果purpose为空适配器会回退到 Agent 的 instructions指令。源码层面的实现位于 packages/mcp-server/src/adapters/agent.ts 的toMcpToolconst purpose typeof agent.purpose string ? agent.purpose.trim() : undefined; const instructions typeof agent.instructions string ? agent.instructions.trim() : undefined; const description purpose purpose.length 0 ? purpose : instructions instructions.length 0 ? instructions : VoltAgent agent ${agent.name};可见回退链条是purpose→instructions→ 兜底文案VoltAgent agent name。与此同时Agent 的id会被写入 MCP tool 的_meta.agentIdname会同时出现在title与annotations.title中方便客户端识别实体来源。与 Agent 相似Workflow 的描述取自workflow.purpose ?? VoltAgent workflow name见 packages/mcp-server/src/adapters/workflow.ts而普通 Tool 则直接使用tool.description作为 MCP description见 packages/mcp-server/src/adapters/tool.ts。因此在定义 VoltAgent 实体时就写好purpose/description是让 MCP 侧展示体验可读的关键习惯。核心类 MCPServer 与配置项所有能力都收敛在MCPServer类上packages/mcp-server/src/server.ts。构造时传入MCPServerConfig完整类型定义见 packages/mcp-server/src/types.ts配置项类型说明id/name/versionstring服务标识与版本id缺省时由name规范化生成小写、-连接、去除首尾符号descriptionstring服务描述同步给 MCP SDK 的Server实例protocols{ stdio?, sse?, http? }各传输开关均默认为true由hasProtocol()与startConfiguredTransports()统一消费httpTransportOptionsMCPStreamableHTTPTransportOptionsStreamable HTTP 的默认传输选项如serverless请求级选项优先filterTools/filterAgents/filterWorkflowsFilterFunction过滤函数缺省为passthroughFilter()原样返回capabilities{ logging?, prompts?, resources?, elicitation? }MCP 能力开关详见下文agents/workflows/toolsRecord以配置方式补充的实体与依赖注入的注册表合并去重后取顶层实体releaseDate/packages/remotes元数据服务发布信息、包信息与远端环境信息写入getMetadata()结果adapters动态适配器logging/prompts/resources/elicitation四类适配器覆盖依赖注入的同名接口MCPServer.initialize(deps)负责注入运行时依赖agentRegistry、workflowRegistry 以及各类适配器并据此自动翻转能力开关例如提供了loggingAdapter.setLevel才启用 logging 能力提供 prompts 适配器才启用 prompts 能力见initialize()与registerCapabilityHandlers()位于 packages/mcp-server/src/server.ts 的 L206-L257 与 L1041-L1121。因此典型启动流程是const server new MCPServer({ name: my-server, version: 1.0.0, protocols: { stdio: true, http: true, sse: true }, tools: { /* 可选额外配置的工具 */ }, }); server.initialize({ agentRegistry: { getAllAgents: () [...], getAgent: (id) ... }, workflowRegistry: { getAllWorkflows: () [...], resumeSuspendedWorkflow: async (...) ... }, }); await server.startConfiguredTransports(); // 按 protocols 开关批量启动三大传输的启动方式stdiostartStdioTransport()创建StdioServerTransport并挂载到共享的 MCPServer上通过传输注册表packages/mcp-server/src/transports/registry.ts中的StdioTransport控制器封装packages/mcp-server/src/transports/stdio.ts。适合本地子进程如 Claude Desktop 的本地 MCP 配置。SSEhandleSseRequest()处理ssePathSSE 事件流与messagePathPOST 消息两条路由基于 SDK 的SSEServerTransport每条 SSE 连接都会在sseSessions中登记并支持createExternalSseSession()创建外部桥接会话packages/mcp-server/src/transports/external-sse.ts。Streamable HTTPhandleStreamableHttpRequest()/startHTTP()MCP 官方推荐的新一代 HTTP 传输默认有状态会话可切换无状态是本文档讲解的核心详见下一节。能力Capabilities一览MCPServer在初始化时向 SDK 注册能力声明packages/mcp-server/src/server.ts 的registerCapabilityHandlerstools始终注册{ tools: {} }并挂载tools/list与tools/call处理器prompts注册prompts/list与prompts/get通过PromptBridge代理到 prompts 适配器packages/mcp-server/src/capabilities/prompts.tsresources注册resources/list、resources/read、resources/templates/list以及可选的subscribe/unsubscribepackages/mcp-server/src/capabilities/resources.tslogging注册logging/setLevel代理到 logging 适配器elicitation注册ElicitRequestSchema处理器优先使用elicitationAdapter.sendRequest否则回退到 SDK 内置的elicitInputpackages/mcp-server/src/server.ts 的 L1170-L1178。Streamable HTTP有状态会话与 serverless 无状态模式默认行为有状态会话在默认配置下startHTTP遵循 Streamable HTTP 规范的有状态流程见handleStreamableHttpRequest的实现packages/mcp-server/src/server.ts 的 L414-L519仅接受POST作为初始化请求GET/DELETE用于会话管理非 POST 的初始化请求返回 400校验 body 必须是合法的initialize载荷否则返回 400用sessionIdGenerator: () randomUUID()生成会话 ID并通过StreamableHTTPServerTransport的onsessioninitialized/onsessionclosed回调把会话登记进httpTransports/httpServerInstances两张 Map后续带mcp-session-id头或?sessionId查询参数的请求会被路由到对应会话的 transportextractSessionId同时支持两种传递方式。会话生命周期由服务端管理close()会关闭全部传输与会话L300-L318。serverless每次请求一个全新实例对于水平扩展或 serverless无服务器部署有状态会话往往不可行——多实例之间没有共享的会话表。此时在请求级选项里开启serverless: trueawait server.startHTTP({ url: new URL(req.url ?? /, http://localhost:3141), httpPath: /mcp, req, res, options: { serverless: true }, });这就是 README 给出的推荐写法。其效果是每个 HTTP 请求都会使用一个全新的 MCP server 实例与全新的 transport 实例且不会签发mcp-session-id。源码中对应handleStatelessStreamableHttpRequestpackages/mcp-server/src/server.ts 的 L521-L540它创建sessionIdGenerator: undefined的 transport、为当前上下文新建 server 实例、连接后立即处理请求。另一种无状态开关sessionIdGenerator: undefined除了serverless: true显式把sessionIdGenerator设置为undefined同样会进入无状态模式。handleStreamableHttpRequest中专门用hasOwnProperty检查该字段是否存在且为undefinedL430-L445只要二者满足其一即走无状态分支。这在不想包一层请求处理函数的场景下非常有用——例如 examples/with-cerbos/src/mcp-server.ts 里直接创建new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })并每请求新建 server 的做法本质就是这一思路。serverlessStreaming请求级 SSE 进度通知无状态请求默认返回 JSONenableJsonResponse默认为!serverlessStreaming即未开启 streaming 时返回 JSON。当需要把 LLM 生成或 Workflow 执行的中间进度实时推给客户端时可以设置options: { serverless: true, serverlessStreaming: true }此时每个请求使用请求级request-scoped的 SSE输出流式通知而不是有状态的长连接。serverlessStreaming是 VoltAgent 在 SDK 选项之上扩展的字段类型定义在 packages/mcp-server/src/types.ts 的MCPStreamableHTTPTransportOptions中{ serverless?: boolean; serverlessStreaming?: boolean }。有状态功能在无状态模式下的限制README 特别提醒无状态模式无法支持会话绑定的能力。以下功能仍然要求有状态stateful模式会话内 elicitation请求式输入收集Agent/Workflow 在执行中需要向客户端提问并等待回答依赖会话内往返订阅subscriptionsresources 的subscribe/ 变更通知可恢复性resumabilityWorkflow 挂起后的resume流程依赖已登记的会话与注册表状态请求外通知out-of-request notifications服务端主动推送的事件无状态请求结束后没有承载通道。因此在选用 serverless 之前应先确认业务是否依赖上述能力若是应保留有状态会话或在架构上引入共享会话存储。服务端默认配置无状态httpTransportOptions如果不想在每次请求都传入serverless: true可以在构造MCPServer时把默认值写进配置使内置的 VoltAgent HTTP 路由整体变为无状态const server new MCPServer({ name: my-server, version: 1.0.0, httpTransportOptions: { serverless: true }, });请求级options会覆盖构造时的httpTransportOptions两者再与已废弃的transportOptions合并见 packages/mcp-server/src/server.ts 的 L425-L429。这也是 README 提供的第三种无状态配置方式适合把 MCP 路由内嵌进现有 VoltAgent HTTP 服务的场景。工具名映射Tool / Agent / Workflow 如何变成 MCP toolsbuildToolRegistry()把三类实体统一编译成一张name - RegisteredToolEntry的工具表packages/mcp-server/src/server.ts 的 L1006-L1016Tool以tool.name || tool.id为基名sanitize 后_meta.toolType toolAgent以agent_id无 id 则用 name为基名_meta.toolType agent其输入 schema 固定为{ prompt(必填), context?, conversationId?, userId?, maxSteps? }执行时调用agent.generateText(prompt, options)并把text、finishReason、usage序列化为 JSON 文本返回packages/mcp-server/src/adapters/agent.tsWorkflow每个 Workflow 会生成两个工具——workflow_id执行与workflow_id_resume恢复挂起执行。执行工具要求input当 Workflow 声明了inputSchema时必填返回执行快照{ executionId, workflowId, status, startAt, endAt, result, ... }resume 工具要求executionId调用workflowRegistry.resumeSuspendedWorkflow()恢复packages/mcp-server/src/adapters/workflow.ts 的 L236-L305。命名冲突时通过createUniqueName追加_1、_2等后缀消解名称统一经过sanitizeName仅保留[a-zA-Z0-9_-]。此外filters.tspackages/mcp-server/src/filters.ts提供了FilterContext含transport: stdio | sse | http、sessionId、userRole、metadata与composeFilters可在不同传输、不同角色下对暴露的 Agent/Workflow/Tool 做细粒度裁剪例如按userRole隐藏管理类工具——这正是 examples/with-cerbos 示例中权限由 VoltAgent 的 MCP 配置层处理的设计基础。测试验证与部署佐证仓库内为上述无状态行为提供了完整的端到端测试packages/mcp-server/src/server.spec.ts使用真实的node:http服务器 MCP SDK 客户端验证了serverless 模式下initialize、initialized、tools/list、tools/call全流程不产生会话多个MCPServer实例轮流处理请求均无mcp-session-id头往返有状态模式下会话 ID 的正确登记、复用与清理。在部署侧examples/with-cloudflare-workers/src/index.ts展示了把 VoltAgent 以serverlessHono()toCloudflareWorker()发布为无服务器 Worker 的完整形态examples/with-netlify-functions/netlify/functions/voltagent.ts则是 Netlify Functions 上的对应做法。结合本文档的serverless: true即可把 MCP 端点发布到任意支持无状态 HTTP 的边缘平台。总结voltagent/mcp-server的价值在于用一套 transport-agnostic 的核心把 VoltAgent 的 Agent / Workflow / Tool 统一映射为 MCP tools并针对现代部署形态提供了完备的无状态 HTTP 方案。落地时的关键决策点可归纳为写好实体的purpose/description让 MCP 客户端展示可读本地进程用 stdio长连接场景用 SSE标准 HTTP 场景用 Streamable HTTP水平扩展 / serverless 部署时用serverless: true或sessionIdGenerator: undefined切无状态需要流式进度时再加serverlessStreaming: true依赖 elicitation、订阅、Workflow 可恢复性、请求外通知等会话级能力时必须保留有状态模式通过httpTransportOptions在服务端整体默认无状态通过filter*与FilterContext按传输、角色裁剪暴露面。该包基于 MIT 协议开源见 packages/mcp-server/README.md 与 packages/mcp-server/package.json当前处于活跃开发期接入时请以仓库实际版本与 CHANGELOG 为准。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Agent OS MCP 工具参考通过 Model Context Protocol 暴露的 8 个内核治理原语Agent OS MCP 工具参考通过 Model Context Protocol 暴露的 8 个内核治理原语 Agent OS 将内核级治理能力代码安全人工智能AI AgentAI 安全治理策略引擎Agent 沙箱认证鉴权Genkit MCP Server 实战指南通过 Model Context Protocol 打通 LLM Agent、IDE 与 Genkit FlowGenkit MCP Server 实战指南通过 Model Context Protocol 打通 LLM Agent、IDE 与 Genkit Flow人工智能大模型后端AI AgentRAG工具调用CAMEL Agent MCP Server 实战指南将 CAMEL 多智能体以 Model Context Protocol 标准对外暴露CAMEL Agent MCP Server 实战指南将 CAMEL 多智能体以 Model Context Protocol 标准对外暴露 导读 本文围绕人工智能大模型AI AgentAgent 框架多智能体工具调用MCP ClientsRAG模型评测数据生成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考