Composio 自定义 MCP（Custom MCP）生命周期接入指南：注册、同步、鉴权与会话使用

Composio 自定义 MCPCustom 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/composio导读本文围绕 Composio 文档中针对 Custom MCP 的API-first 生命周期设计方案展开完整梳理从部署远端 MCP 服务器、注册CUSTOM_*工具包、按鉴权模式完成连接、同步/重同步工具到在会话中调用工具以及删除替换的完整链路。读完本文你将掌握upsert/sync/DELETE三个生命周期端点的精确用法与契约细节、三种鉴权模式的差异与连接要求、500 个工具上限与版本行为等平台限制并能结合仓库中的 SDK 示例与 OpenAPI 契约落地一套可运行的接入方案。背景为什么把 Custom MCP 文档重组为一条生命周期Composio 仓库的 设计规格文档 及其 实施计划 提出了一次明确的文档架构调整不再把「Dashboard 配置」「API 管理」「SDK 使用」当作三个互不相关的教程而是统一为一条开发者可以从注册一路走到删除的 API-first 生命周期同时保留既有的端点契约与 SDK 示例并把各种限制放在它们实际影响读者的步骤处就近说明。这一方案最终落地为 Custom MCP 指南 页面其目录顺序与设计稿中的结构一一对应Introduction Custom MCP lifecycle Register a Custom MCP Complete setup for your authentication mode Sync and resync tools Delete or replace a Custom MCP Authentication types Use Custom MCP in a session What you manage and what Composio handles Technical behavior Known gaps Related guides核心目标读者是已经运营着一个公网远端 MCP 服务器、希望把它注册进 Composio、同步其工具并在会话中使用生成的CUSTOM_*工具包的开发者。Custom MCP 与自定义工具的区别首先要区分两个容易混淆的概念见 Custom MCP 指南引言Custom MCP本文主题MCP 服务器运行在 Composio 之外通过一个公网 HTTPS 端点暴露工具。Composio 负责代理执行与凭据注入。Custom Tools and Toolkits自定义工具与工具包工具运行在你的应用进程内部属于进程内自定义工具相关文档见 custom-tools-and-toolkits.mdx。同时需要明确Custom MCP 目前仍是experimental实验性能力页面元数据中带有experimental: true标记其配置流程、鉴权选项与 API 契约可能在与早期客户协作期间发生变化。生命周期总览deploy → register → connect → sync → use → resync → delete一条 Custom MCP 会按以下阶段流转详见 指南生命周期小节Deploy部署将你的 MCP 服务器部署到一个公网 HTTPS URL。Register注册通过POST /api/v3/custom/toolkits/upsert提交服务器 URL 与鉴权方案Composio 为你的项目创建一个CUSTOM_*前缀的项目级工具包。Connect连接若服务器使用 API key 或 DCR OAuth需要创建一个已激活的连接账户无鉴权NO_AUTH服务器跳过此步。Sync同步同步其工具。首次同步自动开始此后工具变更需要手动触发重新同步。Use使用在会话中使用该工具包对需要鉴权的服务器必须显式选择连接账户或依赖 Tool Router 的自动账户匹配。Resync / Delete重同步 / 删除工具定义变更时手动重同步更换app_url或auth_schemes时需要先删除再重新注册。设计文档特别强调实验期间只能使用生命周期端点完成注册、同步与删除——SDK 尚未暴露这些方法且契约可能变化。Dashboard 端的管理功能面向偏好 UI 的用户「即将推出」。注册一个 Custom MCPPOST /custom/toolkits/upsert注册是生命周期的入口。调用POST /api/v3/custom/toolkits/upsert携带你的公网服务器 URL 与鉴权方案请求使用项目 API key 认证。仓库的 OpenAPI v3 契约postCustomToolkitsUpsert给出了完整字段定义slug工具包唯一标识130 字符匹配^[a-zA-Z0-9_\s]$空格会被转换为下划线。你的 slug 会被自动加上CUSTOM_前缀以避免与 Composio 托管工具包冲突。toolkit_config.name人类可读的应用名1200 字符。toolkit_config.app_url工具包应用 URL对 MCP 应用来说就是MCP URL。toolkit_config.auth_schemes鉴权方案数组至少一项支持NO_AUTH、API_KEY、DCR_OAUTH三种模式。toolkit_config.logo_file可选工具包 Logo。三种鉴权模式的注册请求体No auth无鉴权curl --request POST \ --url https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \ --header x-api-key: $COMPOSIO_API_KEY \ --header Content-Type: application/json \ --data { slug: ACME, toolkit_config: { name: Acme, app_url: https://mcp.example.com/mcp, auth_schemes: [ { mode: NO_AUTH } ] } }API key每个连接账户提供各自的 API keycurl --request POST \ --url https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \ --header x-api-key: $COMPOSIO_API_KEY \ --header Content-Type: application/json \ --data { slug: ACME, toolkit_config: { name: Acme, app_url: https://mcp.example.com/mcp, auth_schemes: [ { mode: API_KEY, headers: { Authorization: Bearer {{generic_api_key}} } } ] } }注意{{generic_api_key}}是占位符实际执行时会被替换为连接账户中存储的凭据。你可以换用不同的 header 名称或值格式但至少一个 header 值必须包含{{generic_api_key}}。契约中 API key 模式的headers为必填可选字段api_key_field用于设置连接页面上展示给最终用户的输入框文案display_name最长 100 字符description最长 500 字符。DCR OAuthOAuth Dynamic Client Registrationcurl --request POST \ --url https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \ --header x-api-key: $COMPOSIO_API_KEY \ --header Content-Type: application/json \ --data { slug: ACME, toolkit_config: { name: Acme, app_url: https://mcp.example.com/mcp, auth_schemes: [ { mode: DCR_OAUTH, discovery_url: https://mcp.example.com/.well-known/oauth-authorization-server } ] } }discovery_url通常是 MCP URL 的/.well-known/oauth-authorization-server路径Composio 会从该地址获取完整的鉴权方案。该模式要求服务器支持标准的 authorization-code 流程其他 OAuth grant 类型不受支持见 指南鉴权分支说明。响应与 insert-only 语义成功后Composio 添加CUSTOM_前缀并返回规范化后的工具包 slug{ slug: CUSTOM_ACME }设计规格与实现都反复强调一个关键语义——upsert实际是 insert-only对项目已经拥有的 slug 重新注册会就地更新可变字段如name、logo、API key 字段文案配置完全相同时是无害的 no-op。两个字段在注册后不可变更app_url和auth_schemes。试图修改二者任一均返回409 Conflict——OpenAPI 契约中对 409 的描述是「Conflict - app_url or auth_schemes differ from the registered toolkit; delete and re-register to change them」。正确的替换方式先删除现有工具包再重新注册删除会同时撤销其连接。此外注册请求同样受 OpenAPI 校验slug 缺失/非法400、凭据无效401、超时408都会以对应错误码返回。补充注册自定义 Logotoolkit_config.logo_file如果你不希望工具包在 Dashboard 与终端用户连接页上显示默认的 Composio Logo可以在注册时通过logo_file携带品牌图片base64 编码后放入content配合mime_typecurl --request POST \ --url https://backend.composio.dev/api/v3.1/custom/toolkits/upsert \ --header x-api-key: $COMPOSIO_API_KEY \ --header Content-Type: application/json \ --data { slug: ACME, toolkit_config: { name: Acme, app_url: https://mcp.example.com/mcp, logo_file: { content: iVBORw0KGgoAAAANSUhEUgAA..., mime_type: image/png }, auth_schemes: [ { mode: NO_AUTH } ] } }图片约束与 OpenAPI 契约中的logo_fileschema 一致仅支持PNG 或 JPEGmime_type为image/png或image/jpeg正方形边长 2561024 像素base64 编码前不超过 3MB契约中content字段最大长度 4,000,000模式为^[A-Za-z0-9/]{0,2}$content必须是单行base64不能包含换行或空白。Logo 会被上传到 Composio 托管的资源存储并在工具包出现的所有位置渲染因此即使你自己的站点下线也不影响展示。省略logo_file则使用 Composio 默认 Logo后续更换 Logo 只需用同一 slug 重新注册即可就地更新。完成所选鉴权模式的设置注册后的分支设计文档的「Content principles」要求在生命周期分支处解释鉴权差异。注册之后三条分支的行为如下指南鉴权表鉴权模式适用场景注册之后No auth服务器接受无凭据请求无需连接首次同步自动执行API key每个连接账户各自提供 API key创建并激活连接随后首次同步在后台开始DCR OAuth服务器支持 OAuth 动态客户端注册完成用户授权创建连接连接激活后开始首次同步创建用于自动账户匹配的 auth config一个容易被忽略的必做步骤注册工具包并不会自动创建 auth config。对 API key 与 DCR OAuth 服务器你必须额外创建一条 auth config——否则终端用户没有可连接的对象工具包的工具也无法完成鉴权。而且必须在创建时把is_enabled_for_tool_router设为true会话才能按user_id自动匹配连接账户curl --request POST \ --url https://backend.composio.dev/api/v3.1/auth_configs \ --header x-api-key: $COMPOSIO_API_KEY \ --header Content-Type: application/json \ --data { toolkit: { slug: CUSTOM_ACME }, auth_config: { type: use_custom_auth, authScheme: API_KEY, credentials: {}, is_enabled_for_tool_router: true } }该标志的作用让会话能够按user_id自动找到该工具包的连接账户。没有它即使存在已激活账户会话执行也会以NoActiveConnection失败此时你必须在每个会话中显式选择账户。如果配置已创建但漏掉了标志用 PATCH 补上curl --request PATCH \ --url https://backend.composio.dev/api/v3.1/auth_configs/ac_xxxxxxxx \ --header x-api-key: $COMPOSIO_API_KEY \ --header Content-Type: application/json \ --data { type: custom, is_enabled_for_tool_router: true }同步与重同步工具POST /custom/toolkits/sync注册完成、连接就绪后调用POST /api/v3/custom/toolkits/sync拉取服务器当前的工具定义OpenAPI 契约postCustomToolkitsSynccurl --request POST \ --url https://backend.composio.dev/api/v3.1/custom/toolkits/sync \ --header x-api-key: $COMPOSIO_API_KEY \ --header Content-Type: application/json \ --data { slug: CUSTOM_ACME, connected_account_id: ca_custom_acme }请求体字段slug必填137 字符匹配^[a-zA-Z0-9_]$与可选的connected_account_id。何时必须携带connected_account_idAPI key / DCR OAuth 服务器必须传入属于同一工具包、同一项目的已激活账户No auth 服务器省略该字段curl --request POST \ --url https://backend.composio.dev/api/v3.1/custom/toolkits/sync \ --header x-api-key: $COMPOSIO_API_KEY \ --header Content-Type: application/json \ --data { slug: CUSTOM_ACME }成功的同步返回工具包版本与发现的工具数量{ slug: CUSTOM_ACME, version: 20260728_00, synced_count: 12 }手动同步的触发时机与版本语义关于同步时机设计文档与指南明确了两点Composio 不会持续监听 MCP 服务器。自动同步只在两种情况下发生No auth 工具包在注册时API key / DCR OAuth 工具包在第一个连接账户变为激活状态时。之后连接的账户不会对已有工具的工具包触发重同步。每次成功的同步都会创建一个新的工具包版本如上例的version字段采用20260728_00这类带日期前缀的版本号。只有服务器工具定义变更或首次同步失败时才需要调用 sync 端点手动重同步。500 个工具上限一个 Custom MCP 工具包最多包含 500 个工具。若服务器返回超过 500 个工具同步会整体失败不会部分导入且最后一次成功的版本仍然可用。设计规格特意要求「Reject an oversized sync without partially importing it, and retain the last successful version」并建议把更大的服务器拆分成多个较小的 MCP 服务器。删除或替换一个 Custom MCPDELETE /custom/toolkits/{slug}替换语义与注册的 insert-only 语义直接相关可变字段name、logo 等可以就地更新但app_url与auth_schemes不可变更。要替换这两者必须先删除工具包再重新注册。调用DELETE /api/v3.1/custom/toolkits/{slug}curl --request DELETE \ --url https://backend.composio.dev/api/v3.1/custom/toolkits/CUSTOM_ACME \ --header x-api-key: $COMPOSIO_API_KEY{ slug: CUSTOM_ACME, deleted: true, revoke_job_ids: [job_123], auth_configs_soft_deleted: 1, connected_accounts_soft_deleted: 1 }删除的破坏性后果必须前置知晓设计文档要求「把破坏性或令人意外的行为紧跟在触发它的操作之后」删除会移除该自定义工具包及其全部工具撤销并移除其 auth config 与连接账户。任何替换操作都要从全新的连接开始。仓库中该端点的契约同样位于 OpenAPI v3 契约deleteCustomToolkitsBySlug中响应中的revoke_job_ids、auth_configs_soft_deleted、connected_accounts_soft_deleted即对应上述级联清理动作。在会话中使用 Custom MCP工具包同步完成后把它的CUSTOM_*slug 传入会话创建即可。设计规格强调需要鉴权的 Custom MCP 工具包必须显式选择连接账户。使用无鉴权服务器Pythonfrom composio import Composio composio Composio(api_keyyour_api_key) session composio.sessions.create( user_iduser_123, toolkits[CUSTOM_ACME], ) tools session.tools()TypeScriptimport { Composio } from composio/core; const composio new Composio({ apiKey: your_api_key }); const session await composio.sessions.create(user_123, { toolkits: [CUSTOM_ACME], }); const tools await session.tools();在默认的 search-first 会话模式下agent 可以通过COMPOSIO_SEARCH_TOOLS发现自定义工具并经 Tool Router 代理执行。使用需要鉴权的服务器当工具包的 auth config 是以is_enabled_for_tool_router: true创建时会话会自动按user_id匹配连接账户否则必须在会话配置中显式选择连接账户Pythonfrom composio import Composio composio Composio(api_keyyour_api_key) session composio.sessions.create( user_iduser_123, toolkits[CUSTOM_ACME], connected_accounts{ CUSTOM_ACME: [ca_custom_acme], }, )TypeScriptimport { Composio } from composio/core; const composio new Composio({ apiKey: your_api_key }); const session await composio.sessions.create(user_123, { toolkits: [CUSTOM_ACME], connectedAccounts: { CUSTOM_ACME: [ca_custom_acme], }, });被钉选的账户必须属于该自定义工具包且处于激活状态。显式选择能确保工具调用使用该账户的凭据。关于会话与工具过滤的更多配置方式可参考 Configuring Sessions关于多账户的显式选择可参考仓库中docs/content/docs/authentication/目录下的「Managing Multiple Connected Accounts」相关页面。职责边界你管理什么Composio 处理什么设计文档要求以运营职责边界而非合同语言来呈现这一对照表指南职责表领域你客户管理Composio 处理服务器部署并运营位于公网 HTTPS URL 的远端 MCP 服务器连接该 URL 进行工具发现与执行Composio 不托管你的服务器工具实现工具并决定工具定义变更何时可以同步启动首次同步、导入工具 schema、为其版本化并向会话暴露鉴权实现服务器侧的 API key / DCR OAuth 行为并完成每次必要的连接存储连接账户凭据并在发现或调用工具时发送它们生命周期决定何时重同步、删除或替换工具包提供项目级的注册、同步与删除操作技术行为slug、版本与 Tool Router从仓库实现与指南的「Technical behavior」小节可以看到以下平台行为每个注册的服务器都会变成一个**项目级project-scoped**的自定义工具包类型为type: custom归属CUSTOM类别slug 以CUSTOM_开头如CUSTOM_ACME。其工具可通过Tool Router 搜索与按工具包过滤的工具列表获取。工具执行被代理proxied到你的 MCP 服务器并携带所选连接账户的凭据。仓库中python/composio/core/models/tool_router.py、python/composio/core/models/tool_router_session.py与python/tests/test_tool_router.py等文件即对应 Tool Router 与代理执行的实现与测试。v3 与 v3.1 的版本选择差异自定义工具包使用带日期的注册表版本。v3.1 工具 API 默认解析最新版本而 v3 默认钉选一个不包含自定义工具的版本——这是「Technical behavior」部分最重要的坑在 v3 下GET /api/v3/tools?toolkit_slugCUSTOM_ACME即使在同步成功后也可能返回空列表。这不是同步失败而是版本选择行为v3 默认读取钉选版本而自定义工具只存在于最新版本。解决办法是显式加toolkit_versionslatestcurl --request GET \ --url https://backend.composio.dev/api/v3/tools?toolkit_slugCUSTOM_ACMEtoolkit_versionslatest \ --header x-api-key: $COMPOSIO_API_KEY各 v3 操作的版本选择对照详见 Toolkit Versioning 页面v3 操作选择最新版本的方式列出工具添加toolkit_versionslatest查询参数获取单个工具添加versionlatest查询参数执行单个工具在请求体中设置version: latest已知局限Known gaps汇总设计文档要求「重复重要的局限即使它们在生命周期部分已经出现过」。汇总如下对应 指南 Known gaps 部分设置与生命周期仅 API 方式SDK 尚未暴露注册、同步、更新或删除方法。请使用本页生命周期端点再通过 SDK 使用工具包 slug。Dashboard 即将推出Dashboard 尚无 Custom MCP 管理能力。仅支持远端服务器Composio 不托管你的服务器必须部署在公网 HTTPS 端点本地与仅 STDIO 的服务器不受支持。app_url与auth_schemes不可变修改返回409 Conflict需删除后重新注册删除同时会移除 auth config 与连接账户。500 个工具上限更大的服务器请拆分为多个 MCP 服务器若后续同步超限最后一次成功版本仍然可用。同步与鉴权无持续同步自动同步只会在注册或首次激活连接时填充空工具包失败时需用激活账户调用 sync 端点工具定义变更后需再次手动同步。API key 校验有限设置阶段只检查「提供了 key」并不验证远端服务器是否接受该 key。连接后请运行一个安全工具做端到端凭据验证。会话与工具 API自动账户匹配需要标志只有 auth config 的is_enabled_for_tool_router: true时会话才会自动匹配连接账户否则需通过 Python 的connected_accounts或 TypeScript 的connectedAccounts显式传账户 ID。优先使用 v3.1 工具 APIv3 钉选的默认版本不含自定义工具必须使用 v3 时按上文方式显式选择latest。结语按生命周期接入的落地建议把上述内容串联成一套可执行的接入清单在公网 HTTPS 端点部署 MCP 服务器app_url填 MCP URLdiscovery_url按需填 OAuth 元数据地址用POST /api/v3/custom/toolkits/upsert注册并记录返回的CUSTOM_*slug注意它insert-only、app_url/auth_schemes不可变按鉴权模式分支No auth 直接进入同步API key / DCR OAuth 需先创建is_enabled_for_tool_router: true的 auth config再建立并激活连接账户确认首次自动同步成功工具变更后手动调用POST /api/v3/custom/toolkits/sync超过 500 工具会整体失败在会话中按 slug 使用工具包鉴权工具包显式选择连接账户或依赖自动匹配v3 场景显式选择latest版本需要更换app_url/auth_schemes时DELETE /api/v3.1/custom/toolkits/{slug}后重新注册——注意删除会级联撤销连接。仓库中的 设计规格、实施计划、落地页面 以及 OpenAPI v3 契约 互为印证可作为继续深入研究的第一手资料。【免费下载链接】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），仅供参考