> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 连接器 API

使用连接器 API 为专家接入外部服务和 MCP 工具。内置连接器会保存为连接器实例。自定义 MCP 服务器会保存到你账号级的自定义 MCP 配置中。

大多数端点要求当前用户拥有**连接器**权限。OAuth 回调端点是公开的，因为身份提供商会跳回这些地址。

## 目录与实例

| 方法       | 路径                                           | 权限  | 作用                 |
| -------- | -------------------------------------------- | --- | ------------------ |
| `GET`    | `/connectors/catalog`                        | 用户  | 列出内置连接器预设          |
| `GET`    | `/connector-instances`                       | 用户  | 列出你的连接器实例          |
| `POST`   | `/connector-instances`                       | 用户  | 创建连接器实例            |
| `GET`    | `/connector-instances/{instance_id}`         | 用户  | 获取单个连接器实例          |
| `PATCH`  | `/connector-instances/{instance_id}`         | 所有者 | 重命名、启用或修改默认打开设置    |
| `DELETE` | `/connector-instances/{instance_id}`         | 所有者 | 删除连接器实例            |
| `POST`   | `/connector-instances/{instance_id}/test`    | 所有者 | 测试已保存的连接器          |
| `POST`   | `/connector-instances/{instance_id}/refresh` | 所有者 | 在支持时刷新 OAuth token |

`default_open` 只对当前账号生效。开启后，未显式选择连接器的页面对话、IM 与 Cron 运行会自动注入该连接器。

## 自定义 MCP 服务器

| 方法      | 路径                                      | 权限 | 作用                                  |
| ------- | --------------------------------------- | -- | ----------------------------------- |
| `GET`   | `/connectors/custom-mcp`                | 用户 | 读取你的自定义 MCP 服务器配置                   |
| `PUT`   | `/connectors/custom-mcp`                | 用户 | 替换你的自定义 MCP 服务器配置                   |
| `PATCH` | `/connectors/custom-mcp/servers/{name}` | 用户 | 修改单个服务器的 `enabled` 或 `default_open` |
| `POST`  | `/connectors/custom-mcp/test`           | 用户 | 探测内联服务器配置或已保存服务器                    |
| `GET`   | `/connectors/weknora/detect-local`      | 用户 | 检查 Octop 主机上是否能访问本地 WeKnora 服务      |

自定义 MCP OAuth 需要先保存服务器，再执行探测。如果探测结果显示该服务器支持 OAuth 且还没有 token，请用 `target.type = "custom_mcp"` 启动授权流程。

```bash
curl -X POST http://127.0.0.1:8088/api/connectors/custom-mcp/test \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"deepwiki"}'
```

## OAuth

统一 OAuth 启动端点同时支持目录连接器和自定义 MCP 服务器。

| 方法     | 路径                                     | 权限 | 作用                         |
| ------ | -------------------------------------- | -- | -------------------------- |
| `POST` | `/connectors/oauth/start`              | 用户 | 为目录连接器或自定义 MCP 服务器启动 OAuth |
| `POST` | `/connectors/oauth/{kind}/start`       | 用户 | 旧的目录连接器 OAuth 启动端点         |
| `GET`  | `/connectors/oauth/callback`           | 公开 | OAuth 回调地址                 |
| `GET`  | `/connectors/oauth/pending/{state_id}` | 用户 | 轮询 OAuth 结果                |

目录连接器目标：

```bash
curl -X POST http://127.0.0.1:8088/api/connectors/oauth/start \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"target":{"type":"catalog","kind":"notion"}}'
```

自定义 MCP 目标：

```bash
curl -X POST http://127.0.0.1:8088/api/connectors/oauth/start \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"target":{"type":"custom_mcp","server_name":"deepwiki"}}'
```

响应包含 `authorize_url` 与 `state_id`。打开 `authorize_url` 完成提供方登录，然后轮询 `/connectors/oauth/pending/{state_id}`。非 loopback 的 OAuth 回调需要公开 HTTPS Octop 地址。

授权服务器没有动态客户端注册时，探测结果带 `oauth.client_required`。在自定义 MCP 的规格里保存 `oauth_client.client_id`。`client_secret` 只写不回显。把 `<公网地址>/api/connectors/oauth/callback` 登记为回调地址。

## 内置连接器说明

- **WeKnora** 使用自定义字段：`base_url`、可选 `api_key`、可选 `tenant_id`、可选 `knowledge_base_ids`。Octop 会把服务地址规范化到 `/api/v1`。
- **Dify** 使用自定义字段：`mcp_url`。URL 必须是包含 `/mcp/server/` 且以 `/mcp` 结尾的 Dify MCP Server URL。
- 飞书 CLI 与企业微信 CLI 连接器可以上报主机 CLI 状态，并触发主机侧 CLI 安装端点。只应在页面或明确的管理员流程中使用这些端点。
