自定义连接器允许组织管理员注册未在内置目录中的 HTTPS API，或在支持的情况下注册 Streamable HTTP MCP 服务器。它定义了网络边界和认证方式，但不会为智能体自动生成完整的 API 参考。
谁负责配置
- 组织管理员 创建、编辑和删除连接器定义。
- 成员 连接自己的密钥或完成连接器的 OAuth 流程。
- 智能体授权 控制哪些智能体可以使用已连接的凭证，以及它们获得哪些命名权限。
定义在组织内共享。成员凭证仅限于该成员和组织范围内。
HTTP API 连接器
- 打开 连接器 → 自定义，选择 新建连接器。
- 选择 HTTP API 并输入显示名称。
- 添加一个或多个 HTTPS 前缀，每行一个。请求必须匹配已配置的前缀，连接器才能授权。
- 如果 API 需要认证，请添加认证方式：
- API 认证：输入请求头名称和包含
{{secret}}的请求头模板，例如Authorization和Bearer {{secret}}。 - OAuth 2.0：输入授权 URL、令牌 URL、客户端 ID、客户端密钥、作用域和令牌端点认证方式。将表单中显示的精确重定向 URL 注册到服务提供方。
- API 认证：输入请求头名称和包含
- 创建连接器。需要使用的成员随后选择 连接，并提供自己的密钥或完成 OAuth。
- 授权所需的智能体和权限。
更改现有 OAuth 定义或其客户端凭证会断开当前的 OAuth 连接。更改后，成员需重新连接。
MCP 连接器
如果你的工作区中出现 MCP 作为连接器类型，请输入 HTTPS Streamable HTTP MCP 端点，并在同一表单中配置 API 或 OAuth 认证。如果选择器中未提供 MCP，则该工作区未启用 MCP。
教智能体 API 步骤
自定义连接器提供安全的网络访问和凭证注入。创建表单不会上传或自动发现 OpenAPI 文档。请在请求中向智能体提供端点、方法、参数和预期响应，或将该过程记录在带有 API 参考文件的工作流中。
请使用已知端点的只读请求验证新连接器。没有通用的 测试连接 请求，因为许多 API 不提供有意义的根端点。
安全边界
- 仅接受 HTTPS 前缀和 MCP 端点。
- 防火墙仅将已保存的凭证注入到匹配的请求中。
- 已保存的密钥静态加密存储，不会以环境变量形式暴露给智能体。
- 不要在聊天消息、工作流说明或附件中放置密钥、令牌或客户端密钥。
- 使用仅包含工作流所需最小上游权限的服务凭证。
故障排查
| 问题 | 检查 |
|---|---|
| 新建连接器 不可用 | 只有组织管理员可以创建或编辑连接器定义。 |
| 智能体无法看到连接器 | 为当前成员连接，然后授权该智能体。 |
| 请求在到达 API 前被阻止 | 确认请求 URL 以已配置的 HTTPS 前缀开头。 |
| API 返回 401 或 403 | 重新连接成员凭证，并核查上游密钥或 OAuth 作用域。 |
| OAuth 返回重定向错误 | 注册连接器表单中显示的精确重定向 URL，并核查授权和令牌 URL。 |
| 智能体猜错端点或请求体 | 将 API 步骤写入工作流并附上相关参考，而不是仅依赖连接器名称。 |
