• 简体中文

      • 连接器 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" 启动授权流程。

      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 结果

      目录连接器目标：

      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 目标：

      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 地址。

      内置连接器说明

      • 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 安装端点。只应在页面或明确的管理员流程中使用这些端点。