Composio Tool Router 快速指南为每个用户搭建隔离的 MCP 会话并精细管理工具与账户【免费下载链接】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/composioComposio 是一个 AI Agent 工具编排平台其 Tool Router 允许你为每个用户开设一个隔离的会话Session在会话内配置可用的工具箱Toolkit与工具Tool并暴露统一的 MCP 端点。本文走一遍从安装 SDK 到接入框架的完整流程示例场景是电商订单流用 Stripe 收款、把订单记录写入 Notion。01 Tool Router 解决什么问题为什么需要按用户隔离一个应用服务多个用户时“谁能用什么工具、用哪个账户”必须隔离开会话Session一个用户一个连接、配置、工具集互相独立工具箱Toolkit单个应用的一组工具如stripe、notion已连接账户Connected Account用户授权的真实账号只在自己的会话里生效会话自带一个 MCPModel Context Protocol地址任意 MCP 客户端可直接接入。能力落在哪里SDK 用两个类承载这些能力ToolRouter负责会话的创建、复用与删除ToolRouterSession是会话对象本身封装了 tools、execute、search、authorize 等方法。实现可看 会话创建 与 会话对象。02 跑通第一次从安装到可用会话安装 SDK 并初始化npm install composio/core初始化时 API Key 默认从COMPOSIO_API_KEY环境变量读取代码里可以不传import { Composio } from composio/core; const composio new Composio(); 用最小代码创建第一个会话const session await composio.create(buyer_8821, { toolkits: [stripe, notion], });create(userId, config)先校验配置再请求后端并返回会话对象。记下session.sessionId之后可用composio.use(sessionId)取回同一个会话session.delete()删除后会话立即不可再取。MCP 端点需要显式开启只有传{ mcp: true }时类型上才会暴露session.mcpconst { mcp } await composio.create(buyer_8821, { toolkits: [stripe, notion], mcp: true, });mcp.url就是交给 MCP 客户端的地址mcp.headers是认证头——构造时传了 apiKey 会自动带上x-api-key。协议类型只有http与sse两种。忘了mcp: true时端点在运行时依然存在只是类型降级、IDE 补不出来。重载写法见 会话创建源码。03 给用户配一份他能看到的工具集会话配置总览配置项形态作用toolkitsslug 数组或enable/disable整组开关工具箱tools{ 工具箱: string[] \| { enable } \| { disable } \| { tags } }工具箱内的工具级裁剪tags行为标签数组按行为过滤如只留只读工具authConfigs{ 工具箱: 认证配置ID }绑定认证配置Auth ConfigconnectedAccounts{ 工具箱: 账户ID }直接复用已有的已连接账户manageConnections布尔或对象会话是否自动引导用户连接sandbox{ enable, autoOffloadThreshold, sandboxSize }代码执行沙箱旧名 workbenchexperimentalcustomTools / customToolkits / assistivePrompt进程内本地工具、时区感知提示词sessionPresetdirect_tools直接暴露全部命中工具默认关掉 meta toolspreload{ tools: string[] \| all }预加载工具省去搜索步骤multiAccount{ enable, maxAccountsPerToolkit }允许同一工具箱连多个账户行为标签四个readOnlyHint只读、destructiveHint会改/删数据、idempotentHint可安全重试、openWorldHint开放世界上下文运行。示例一个订单流会话const session await composio.create(buyer_8821, { toolkits: [stripe, notion], tools: { notion: [NOTION_APPEND_TEXT_BLOCKS, NOTION_CREATE_COMMENT], // 只留这两个 }, tags: [readOnlyHint], authConfigs: { stripe: ac_stripe_prod }, manageConnections: { enable: true, callbackUrl: https://shop.example.com/auth/callback, waitForConnections: true, // 等用户完成授权再放行 }, });三个注意点tools与tags中enable、disable、tags是互斥形态同一个工具箱一次只能出现一个多传会校验失败waitForConnections为 true 时会话会阻塞到所有必需连接完成适合“注册完马上开工”的场景sandbox与workbench是同一份配置的新旧名同时传会直接抛错。04 让用户把 Stripe 账户连进来 发起 OAuth 流程const request await session.authorize(stripe, { callbackUrl: https://shop.example.com/auth/callback, }); console.log(request.redirectUrl); // 展示给用户 const account await request.waitForConnection();用户打开redirectUrl完成授权后waitForConnection()才拿到已连接账户并解锁。默认创建 PRIVATE 连接仅该用户可用实验性选项{ accountType: SHARED, aclConfigForShared }可以建带按用户 ACL 的共享连接。交互式应用保留manageConnections默认开启即可会话内置的 meta tools 会自己引导连接无界面场景关掉它用authorize()自己串流程。查连接是否已生效const { items } await session.toolkits({ toolkits: [stripe, notion] }); for (const t of items) console.log(t.slug, t.connection?.isActive);isActive由后端账户状态是否为 ACTIVE 推导还可以用isConnected、search过滤用cursor/limit翻页。05 接入主流 AI 框架两条接入路线先分清MCP 路线是客户端直连session.mcp.url加mcp.headers不需要 providerprovider 路线是session.tools()返回框架格式化工具对象需要在构造函数里传对应 provider。下面四个框架都走 MCP 路线。Vercel AI SDKimport { openai } from ai-sdk/openai; import { createMCPClient } from ai-sdk/mcp; import { stepCountIs, streamText } from ai; const client await createMCPClient({ transport: { type: http, url: mcp.url, headers: mcp.headers }, }); const stream await streamText({ model: openai(gpt-4o-mini), prompt: 对订单 #8821 收款并把结果记到 Notion, stopWhen: stepCountIs(10), tools: await client.tools(), });这里的mcp来自上文带{ mcp: true }的create结果。想走 provider 路线则在构造函数加provider: new VercelProvider()改用await session.tools()拿工具tools()还能接收 modifiers在 schema、入参、出参三个位置做拦截。LangChain、OpenAI Agents、Claude Agent SDK// LangChain多服务器 MCP 适配器 const client new MultiServerMCPClient({ composio: { transport: http, url: session.mcp.url, headers: session.mcp.headers }, }); // OpenAI Agents托管 MCP 工具 const mcpTool hostedMcpTool({ serverLabel: composio, serverUrl: mcp.url, headers: mcp.headers, }); // Claude Agent SDK在 query 选项里声明 mcp 服务器 const mcpServers { composio: { type: http, url: session.mcp.url, headers: session.mcp.headers }, };三个框架只是把同一份 url headers 接到不同位置跑通的完整版本在 Tool Router 示例工程四个框架各有一个入口文件src/mcp.ts、src/langchain.ts、src/openai-agents.ts、src/claude-agent-sdk.ts。06 常见坑与核心对象速查六个坑MCP 类型是显式开关不传mcp: trueTypeScript 不认session.mcp类型定义见 toolRouter.types.ts配置互斥单个工具箱下enable/disable/tags只能留一个校验逻辑在 参数转换账户数量非多账户模式下每个工具箱只允许一个已连接账户字符串 ID 会被 SDK 自动包成单元素数组自定义工具绑定了 customTools 的会话必须给 userId否则构造时直接抛错删除会 404删除不存在的会话得到后端 404别把它吞掉当成功沙箱规格修改sandboxSize会重建沙箱内存文件系统丢失/mnt/files/持久化目录保留。核心对象速查成员说明sessionId会话标识存下来后用use()复用mcp{ url, type, headers }连接三元组tools(modifiers?)拿框架格式的工具对象execute(slug, args)会话内执行工具返回{ data, error, logId }search({ query })按语义查工具附带使用引导authorize(toolkit, opts?)发起授权拿到重定向地址与等待句柄toolkits(opts?)查询各工具箱连接状态update(partial)部分更新会话配置未传字段不动delete()删除会话experimental.files会话挂载的文件系统上传、列表、下载、删除更多类型细节看 类型定义 与 官方 API 文档。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考