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

Composio 自定义 MCP（Custom 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 MCP（POST /custom/toolkits/upsert）

注册是生命周期的入口。调用POST /api/v3/custom/toolkits/upsert，携带你的公网服务器 URL 与鉴权方案，请求使用项目 API key 认证。仓库的 OpenAPI v3 契约（postCustomToolkitsUpsert）给出了完整字段定义：

slug：工具包唯一标识，1～30 字符，匹配^[a-zA-Z0-9_\s]+$，空格会被转换为下划线。你的 slug 会被自动加上CUSTOM_前缀，以避免与 Composio 托管工具包冲突。
toolkit_config.name：人类可读的应用名（1～200 字符）。
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 key）：

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": "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 OAuth（OAuth Dynamic Client Registration）：

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": "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）都会以对应错误码返回。

补充：注册自定义 Logo（toolkit_config.logo_file）

如果你不希望工具包在 Dashboard 与终端用户连接页上显示默认的 Composio Logo，可以在注册时通过logo_file携带品牌图片（base64 编码后放入content，配合mime_type）：

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", "logo_file": { "content": "iVBORw0KGgoAAAANSUhEUgAA...", "mime_type": "image/png" }, "auth_schemes": [ { "mode": "NO_AUTH" } ] } }'

图片约束（与 OpenAPI 契约中的logo_fileschema 一致）：

仅支持PNG 或 JPEG（mime_type为image/png或image/jpeg）；
正方形，边长 256～1024 像素；
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 契约postCustomToolkitsSync）：

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", "connected_account_id": "ca_custom_acme" }'

请求体字段：slug（必填，1～37 字符，匹配^[a-zA-Z0-9_]+$）与可选的connected_account_id。何时必须携带connected_account_id：

API 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 MCP（DELETE /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 工具包必须显式选择连接账户。

使用无鉴权服务器

Python：

from composio import Composio composio = Composio(api_key="your_api_key") session = composio.sessions.create( user_id="user_123", toolkits=["CUSTOM_ACME"], ) tools = session.tools()

TypeScript：

import { 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匹配连接账户；否则必须在会话配置中显式选择连接账户：

Python：

from composio import Composio composio = Composio(api_key="your_api_key") session = composio.sessions.create( user_id="user_123", toolkits=["CUSTOM_ACME"], connected_accounts={ "CUSTOM_ACME": ["ca_custom_acme"], }, )

TypeScript：

import { 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_slug=CUSTOM_ACME即使在同步成功后也可能返回空列表。这不是同步失败，而是版本选择行为：v3 默认读取钉选版本，而自定义工具只存在于最新版本。解决办法是显式加toolkit_versions=latest：

curl --request GET \ --url "https://backend.composio.dev/api/v3/tools?toolkit_slug=CUSTOM_ACME&toolkit_versions=latest" \ --header "x-api-key: $COMPOSIO_API_KEY"

各 v3 操作的版本选择对照（详见 Toolkit Versioning 页面）：

v3 操作	选择最新版本的方式
列出工具	添加`toolkit_versions=latest`查询参数
获取单个工具	添加`version=latest`查询参数
执行单个工具	在请求体中设置`"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 工具 API：v3 钉选的默认版本不含自定义工具；必须使用 v3 时，按上文方式显式选择latest。

结语：按生命周期接入的落地建议

把上述内容串联成一套可执行的接入清单：

在公网 HTTPS 端点部署 MCP 服务器（app_url填 MCP URL，discovery_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}后重新注册——注意删除会级联撤销连接。