Composio MCP 示例实战：基于 Streamable HTTP 与 Vercel AI SDK 构建可调用工具的 Agent-平芜编程栈

Composio MCP 示例实战：基于 Streamable HTTP 与 Vercel AI SDK 构建可调用工具的 Agent

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio

本篇技术指南以 ts/examples/mcp 中的 MCP 示例为骨架，完整演示如何用 Composio TypeScript SDK 创建 MCP 配置、为指定用户生成 MCP Server 实例，并通过@ai-sdk/mcp的 Streamable HTTP 传输把工具接入 Vercel AI SDK 的streamText流程。读完本文，你将掌握composio.mcp.create/composio.mcp.generate的完整调用链、环境变量的正确配置方式，以及如何把 Composio 托管的 Gmail 等工具无缝注入任意 AI SDK Agent。

示例概览：一次完整的 MCP 接入闭环

该示例的核心价值在于展示了「创建 MCP 配置 → 生成用户级 Server → 通过 HTTP 传输拉起工具 → 交给 Agent 执行」的全链路：

初始化 Composio SDK，并绑定VercelProvider（位于 ts/packages/providers/vercel/src/index.ts，用于将 Composio 工具包装为 Vercel AI SDK 的ToolSet）；
调用composio.mcp.create创建一个仅包含 Gmail 工具包的 MCP 配置；
调用composio.mcp.generate为指定用户生成带用户上下文的 MCP Server 实例；
用@modelcontextprotocol/sdk的StreamableHTTPClientTransport建立连接，并用@ai-sdk/mcp的createMCPClient拉取工具；
最终把这些工具直接传给streamText，让gpt-4o-mini自主调用「获取最新 2 封邮件并总结」的任务。

完整可运行代码见 ts/examples/mcp/src/index.ts，依赖与脚本声明见 ts/examples/mcp/package.json。

环境准备与运行

1. 安装依赖

示例目录是一个独立的私有 workspace 包（包名为mcp-example），在ts/examples/mcp目录下执行：

pnpm install

若从仓库根目录 ts 出发，也可以一次性安装所有示例的依赖：

cd ts pnpm install

2. 配置环境变量

README 建议复制环境变量模板并编辑：

cp .env.example .env

从示例源码可以确认，实际读取的环境变量有以下三个（缺失时会直接throw并提示）：

环境变量	作用	是否必填
`COMPOSIO_API_KEY`	Composio API 密钥，从 Composio Dashboard 获取	是
`COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID`	已创建的 Gmail Auth Config ID，用于声明工具包使用的认证配置	是（本示例）
`COMPOSIO_EXAMPLES_USER_ID`	你数据库中的外部用户 ID，用于生成该用户的 MCP Server 实例	是（本示例）

说明：COMPOSIO_EXAMPLES_*系列变量是整个示例体系的统一约定（详见 ts/examples/README.md），示例会「大声失败」——缺失变量时直接报错并点名缺失项。若你的环境中没有.env.example模板文件，直接手动 export 上述变量即可。

3. 运行示例

# 运行示例 pnpm start # 开发模式（带文件监听自动重启） pnpm dev

从 package.json 的 scripts 可以看到，start实际执行的是bun src/index.ts，dev执行的是bun --watch src/index.ts，即运行环境是 Bun。若从仓库根目录运行，可改用：

pnpm --filter mcp-example start

逐步拆解核心代码

第一步：初始化 Composio 与 Provider

import { Composio } from '@composio/core'; import { VercelProvider } from '@composio/vercel'; const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY, provider: new VercelProvider(), });

VercelProvider继承自BaseAgenticProvider（见 ts/packages/providers/vercel/src/index.ts），负责把 Composio 的工具包装成 Vercel AI SDK 可识别的ToolSet，并统一处理 JSON Schema 规范化（如toStrictJsonSchema、dereferenceJsonSchema、normalizeToolArguments等）。

第二步：声明认证配置与允许的工具

const authConfigId = process.env.COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID; const externalUserId = process.env.COMPOSIO_EXAMPLES_USER_ID; if (!authConfigId || !externalUserId) { throw new Error('Set COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID and COMPOSIO_EXAMPLES_USER_ID'); } const allowedTools = ['GMAIL_FETCH_EMAILS'];

这里先做环境变量守卫，再通过allowedTools白名单把 Agent 的能力收敛到单个工具，最小化权限暴露。

第三步：创建 MCP 配置

const mcpConfig = await composio.mcp.create(`examples-gmail-${Math.floor(Date.now() / 1000)}`, { toolkits: [ { toolkit: 'gmail', authConfigId, }, ], allowedTools, manuallyManageConnections: false, });

create的入参在 ts/packages/core/src/types/mcp.experimental.types.ts 中由MCPConfigCreationParamsSchema校验，各字段含义如下：

参数	类型	默认值	说明
`name`	string	必填	MCP 配置唯一名称，API 将名称上限限制为 30 个字符，因此示例使用`examples-gmail-<unix秒时间戳>`的短标签命名法
`toolkits`	`Array<string \\| { toolkit?: string; authConfigId?: string }>`	必填	可传 toolkit slug 字符串（如`"gmail"`），或带`authConfigId`的对象，以便绑定指定的认证配置
`allowedTools`	`string[]`	可选	允许暴露给 Agent 的工具白名单
`manuallyManageConnections`	boolean	`false`	`false`时 Composio 会向 MCP Server 注入账号管理工具，由 Agent 在对话中请求并完成账号认证；`true`则由你自行管理连接

从源码看，create内部（见 ts/packages/core/src/models/MCP.ts）会把toolkits拆分为toolkits（slug 列表）、auth_config_ids、custom_tools三组，并依据manuallyManageConnections设置managed_auth_via_composio布尔值后调用client.mcp.custom.create。返回的对象上还挂载了一个闭包generate(userId)，可以直接基于该配置生成 Server 实例。

关于命名约定：注释与 scripts/examples-provision.mjs 中的清理逻辑都依赖examples-<label>-<unix秒>这一形态——examples-前缀用于标识「示例创建的资源」，时间戳用于区分手工创建的同名前缀配置，垃圾回收（--gc）只会按正则^examples-[a-z0-9-]+-\d{10}$匹配并清理超过 24 小时的残留配置。

第四步：为用户生成 MCP Server 实例

const server = await composio.mcp.generate(externalUserId, mcpConfig.id);

generate（MCP.ts）会先retrieve配置详情，再调用client.mcp.generate.url携带{ mcp_server_id, user_ids: [userId], managed_auth_by_composio }换取用户专属的 Streamable HTTP URL。返回的MCPServerInstance结构（见 mcp.experimental.types.ts）为：

{ id: string; // MCP 配置 ID name: string; // 配置名称 type: 'streamable_http', url: string; // 该用户专属的 MCP 端点 URL userId: string; // 外部用户 ID allowedTools: string[]; authConfigs: string[]; }

第五步：建立 Streamable HTTP 传输并创建 MCP Client

const serverParams = new StreamableHTTPClientTransport(new URL(server.url), { requestInit: { headers: { 'x-api-key': process.env.COMPOSIO_API_KEY! } }, }); const mcpClient = await createMCPClient({ name: 'composio-mcp-client', transport: serverParams, });

这里有两个关键点：

使用@modelcontextprotocol/sdk提供的StreamableHTTPClientTransport（客户端流式 HTTP 传输），而非旧的 SSE 传输；
MCP 端点通过x-api-key请求头携带 Composio API Key 完成认证（x-api-key正是 Composio 平台统一使用的 API 认证头），这是该托管 MCP Server 与本地 stdio MCP 的最大差异。

第六至八步：拉取工具、交给 Agent、关闭连接

const tools = await mcpClient.tools(); const stream = streamText({ model: openai('gpt-4o-mini'), messages: [ { role: 'user', content: `Fetch the latest 2 emails and provide a detailed summary with sender, subject, date, and brief content overview for each email.`, }, ], stopWhen: stepCountIs(5), tools, }); for await (const textPart of stream.textStream) { process.stdout.write(textPart); } await mcpClient.close();

streamText来自 Vercel AI SDK（ai包），stopWhen: stepCountIs(5)限制 Agent 最多执行 5 步工具调用以避免失控；tools直接传入从 MCP Client 拉取的工具集，模型即可自主决定何时调用GMAIL_FETCH_EMAILS。示例最后显式close()释放连接资源。

源码级原理：MCP 模型层的完整能力

示例只用到了create与generate，但 ts/packages/core/src/models/MCP.ts 中的MCP类还封装了完整的服务端管理 API，可在你的业务中按需选用：

list(options)：分页（page/limit，默认 1/10）、按toolkits、authConfigs、name过滤查询 MCP Server 列表；
get(serverId)：获取单个配置详情，包含commands（Claude / Cursor / Windsurf 各客户端的接入命令）、MCPUrl、toolkitIcons、serverInstanceCount等；
update(serverId, config)：增量更新名称、工具包、allowedTools与manuallyManageConnections，注意工具包列表是整体替换而非合并；
delete(serverId)：永久删除配置（不可恢复，删除前请确认无活跃连接）。

值得留意的是源码中标注的演进方向：MCP类被标记为@deprecated，官方建议改用会话级 MCP 端点——即composio.create(userId, { mcp: true })返回的 session 会直接暴露session.mcp.url/session.mcp.headers，MCP 按会话按需开启，独立的composio.mcp服务端管理 API 仅为向后兼容保留。新项目建议优先走 session MCP 端点，示例代码则用于演示兼容路径的完整接法。

环境变量自动供给：examples-provision 脚本

COMPOSIO_EXAMPLES_GMAIL_AUTH_CONFIG_ID等变量不必手工去 Dashboard 逐个创建，仓库提供了幂等的供给脚本 scripts/examples-provision.mjs，在ts/目录下执行：

out=$(node ../scripts/examples-provision.mjs) && eval "$out"

该脚本会检查一个专用的（可丢弃的）Composio 项目：

自动创建缺失的examples-<slug>命名 Auth Config（Gmail/GitHub/Slack 走use_composio_managed_auth，serpapi 走use_custom_auth+ API_KEY）；
对尚无活跃连接的 OAuth 工具包，加上--initiate-missing可发起连接并打印浏览器授权 URL；
用--gc [--dry-run]可清理示例运行残留（未达 ACTIVE 的账号、多余的 serpapi 演示账号、examples-前缀的 MCP 配置），且只清理 24 小时前创建、确属示例创建的资源。

脚本只向 stdout 输出可被eval的export语句，报告走 stderr；注意「先捕获再 eval」，不要写成eval "$(...)"，否则会掩盖脚本失败的退出状态。

自定义与扩展建议

README 明确指出示例的扩展方向（见 ts/examples/mcp/README.md），结合源码可进一步落地：

替换/增加应用：修改toolkits数组，例如换成github、slack，或传入{ toolkit: 'github', authConfigId: '你的配置ID' }；同时把allowedTools换成对应工具包的工具名（如GITHUB_CREATE_ISSUE），并补充对应的COMPOSIO_EXAMPLES_GITHUB_AUTH_CONFIG_ID等环境变量。
实现业务逻辑：把messages内容替换为真实任务，或将tools接入你自己的 Agent 循环（支持 Anthropic、LangChain 等框架，参见下方相关示例）。
错误处理与日志：为stream.textStream迭代加入 try/catch，打印模型调用失败或工具执行异常；可用stopWhen: stepCountIs(N)控制步数上限，避免长任务失控。
认证模式切换：将manuallyManageConnections设为true时，Composio 不再注入账号管理工具，需要自行确保用户已建立连接（可参考 connected-accounts 示例的建连流程）。

小结

本示例用不到 70 行代码打通了「Composio 托管 MCP Server + Streamable HTTP 传输 + Vercel AI SDK Agent」整条链路。核心要点可归纳为：通过composio.mcp.create声明工具包与认证配置、通过composio.mcp.generate换取用户级端点、以x-api-key完成 HTTP 认证、再用createMCPClient把远端工具直接注入streamText。理解这条链路后，你可以把任意 Composio 支持的 1000+ 工具包快速接入现有 AI 应用，而无需自行实现工具服务器与认证逻辑。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考