MCP 连接器管理
MCP（Model Context Protocol，模型上下文协议）连接器允许代理调用外部 API——数据库、SaaS 产品、内部服务等。作为组织管理员，你可以管理连接器目录：哪些模板对工作区可见、哪些模板具有组织级凭据，以及连接器需要暂停或清理时如何处理。
连接器管理位于 Admin > MCP Connectors（/admin/mcp）。
核心概念
| 概念 | 说明 |
|---|---|
| 模板 | 描述服务的连接器定义——包括名称、服务器 URL、传输方式及其支持的认证方法。模板存在于三个作用域：全局（内置目录）、组织（由你创建）和工作区（由工作区管理员创建；为便于治理，你可以查看并禁用它们）。 |
| 连接器记录 | 工作区首次启用模板时自动（按需）创建的底层基础设施。它保存工具缓存、OAuth 客户端身份和共享配置。你无法直接创建或删除这些记录。 |
| 凭据 | API token、bearer token 或 OAuth 授权——以加密形式存储。凭据可限定在组织、特定工作区或单个用户的作用域内。 |
| 启用 / 禁用 | 一种可逆的组织级暂停操作。禁用的模板会从工作区目录中隐藏，并从代理运行时中排除。现有状态记录和凭据会被保留；重新启用后会恢复全部内容。 |
| 清除 | 一种彻底清理操作：删除连接器记录、其在所有工作区中的全部状态记录以及所有凭据。模板仍保留在目录中，之后可从零开始再次启用。这是唯一具有破坏性的生命周期操作。 |
| 分发 | 用于将模板推送到工作区的对话框：包含两个复选框，且默认均已勾选。绝不会覆盖现有的每工作区选择。 |
管理员目录
Admin > MCP Connectors 中的目录会显示组织可见的所有模板——全局（内置）模板、你创建的组织作用域自定义模板，以及工作区管理员注册的工作区作用域模板（以供治理查看）。
筛选标签
使用目录顶部的筛选标签回答特定问题：
| 筛选项 | 显示内容 | 所回答的问题 |
|---|---|---|
| In use (默认) | 具有连接器记录的模板（至少一个工作区已使用该模板） | “我正在主动管理什么？” |
| Needs attention | 存在问题的模板：组织凭据已过期、OAuth 待处理或发现失败 | “哪里出问题了——我的待办队列” |
| Org credential | 存在组织级凭据的模板 | “哪些凭据生命周期由我负责？” |
| All | 组织可见的所有模板 | 浏览完整目录 |
通过 source 下拉菜单还可进一步缩小范围：全局目录、组织创建的自定义模板或工作区创建的模板。
将模板分发给工作区
分发会将模板推送到尚未对其作出选择的工作区。
- 在目录中，点击模板行。
- 点击 Distribute。
- 对话框显示两个复选框（默认均已勾选）：
- Enable for existing workspaces that have not yet decided——在尚未拥有该模板状态记录的工作区中插入启用状态。已明确启用或禁用该模板的工作区不会受到影响。
- Auto-enable for future workspaces——之后加入组织的新工作区会自动启用该模板。
- 确认。CubePlex 会立即执行扇出操作。
禁用模板
禁用是一种可逆暂停操作。它会从所有工作区目录中隐藏模板，并在代理运行时阻止其工具。现有工作区状态记录和凭据会被保留——重新启用将按原样恢复全部内容。
- 在目录中，点击模板行。
- 点击 Disable，然后确认对话框。
- 该模板会在目录中显示 Disabled 徽标。工作区无法再启用它，代理也无法再调用其工具。
如需重新启用：点击模板行，再点击 Re-enable。徽标会被移除，之前的状态记录和凭据会立即恢复为活动状态。
清除连接器（危险区域）
清除是一种彻底清理操作，且无法撤销。当你想从组织中移除连接器使用痕迹的全部内容——而不只是暂停它时——请使用此操作。
清除会删除：
- 连接器记录（共享基础设施对象）
- 每个工作区中的所有状态记录
- 所有作用域（组织、工作区和用户）的全部凭据
清除会保留：
- 模板本身——它仍在目录中，之后可以从零开始再次启用。
执行清除：
- 在目录中，点击模板行。
- 滚动到 Danger zone 部分。
- 点击 Purge connector。确认对话框会精确列出要删除的内容（连接器记录、N 个状态记录、M 个凭据）。
- 确认。删除将立即发生且不可逆。
当你要永久弃用连接器时，清除是正确的操作。如果只是想暂时阻止工作区使用它，请改用 Disable。
创建组织作用域的自定义模板
对于不在内置目录中的服务（例如内部工具），请将其注册为组织作用域模板。创建后，模板会出现在目录中，组织内的任意工作区均可启用它。
- 前往 Admin > MCP Connectors，点击 + Add custom template。
- 填写表单：
- Name 和 Server URL。
- Transport（
streamable_http或sse）。 - Supported auth methods——以下一种或多种：OAuth、API token / bearer token、No auth。
- 点击 Create template。
该模板现在会在目录中显示，来源为 Org。工作区可立即启用它；无需先进行分发，但你仍可选择分发。
CubePlex 会在工作区首次启用模板时自动发现模板工具——无需手动列出工具。
认证
OAuth 连接器
多数 OAuth 连接器支持动态客户端注册（Dynamic Client Registration，DCR）——包括 Notion、Linear、Atlassian、Asana、Sentry、Intercom 和 Cloudflare。对于这些连接器，无需额外设置：首次创建凭据时，CubePlex 会自动向服务注册自己的 OAuth 客户端。
少数 OAuth 连接器不支持 DCR——GitHub、Slack 和 Google Workspace。它们需要预先注册 OAuth 应用：
- 运维人员在供应商的开发者控制台中注册 OAuth 应用，并使用重定向 URI
${CUBEPLEX_PUBLIC_BASE_URL}/api/v1/oauth/mcp/callback。 - 将应用的客户端 ID 和密钥放入环境变量（
CUBEPLEX_MCP_OAUTH__<SLUG>__CLIENT_ID/…__CLIENT_SECRET），再由目录填充程序加载。
这是部署时的步骤，并非在管理 UI 中输入的内容。在这些凭据加载前，连接器的 OAuth 流程无法完成。详情请参阅 backend/docs/mcp_catalog_oauth.md 中的运维手册。
API key / bearer token 连接器
对于使用静态 API token 或 bearer token 认证的连接器（例如搜索连接器 Tavily、Exa 和 Jina AI），会在为模板创建组织级凭据时配置凭据。CubePlex 会将其加密存入凭据保险库。
单个模板的混合认证
一个模板可以同时具有 OAuth 和静态凭据——例如，工作区 A 的用户各自完成 OAuth 流程，而工作区 B 使用共享服务账户 token。认证方法在配置每个凭据时选择，而不是固定在模板级别。
工具发现与缓存
工作区首次启用模板时（即创建连接器记录），CubePlex 会连接 MCP 服务器、列出其工具，并将工具列表存储在连接器记录中。代理运行会使用这个缓存列表——不会在每条消息时都重新连接服务器，因此即使有许多活跃连接器，聊天启动也能保持快速。实际调用工具时始终会访问在线服务器。
缓存会在超过 24 小时时自动于后台刷新（配置键为 mcp.tools_cache_ttl_hours；设为 0 可禁用后台刷新）。如果服务器的工具已变更且你不想等待，请在模板详情页中使用 Retry discovery 立即刷新。
工作区状态可见性
每个模板的详情面板都显示 Workspaces 标签：按工作区列出模板是否启用，以及正在使用的凭据来源。你可以对任何具有连接器记录的模板查看这些信息（即至少有一个工作区已使用该模板）。
各个工作区的启用/禁用开关由工作区管理员在工作区的 MCP 页面中管理。组织管理员可以查看状态，但只能通过 Distribute 对话框进行管理，或使用 Disable 在组织范围内暂停模板。