• English

      • Connectors API

      Use the Connectors API to give agents access to external services and MCP tools. Built-in connectors are saved as connector instances. Custom MCP servers are saved in your account-level custom MCP map.

      Most endpoints require the signed-in user to have the Connectors permission. OAuth callback endpoints are public because the identity provider redirects back to them.

      Catalog and instances

      MethodPathAuthWhat it does
      GET/connectors/cataloguserList built-in connector presets
      GET/connector-instancesuserList your connector instances
      POST/connector-instancesuserCreate a connector instance
      GET/connector-instances/{instance_id}userGet one connector instance
      PATCH/connector-instances/{instance_id}ownerRename, enable, or change default-open settings
      DELETE/connector-instances/{instance_id}ownerDelete a connector instance
      POST/connector-instances/{instance_id}/testownerTest the saved connector
      POST/connector-instances/{instance_id}/refreshownerRefresh OAuth tokens when supported

      default_open is account-level. When it is on, Octop auto-injects that connector into Dashboard, IM, and cron runs that do not make an explicit connector selection.

      Custom MCP servers

      MethodPathAuthWhat it does
      GET/connectors/custom-mcpuserRead your custom MCP server map
      PUT/connectors/custom-mcpuserReplace your custom MCP server map
      PATCH/connectors/custom-mcp/servers/{name}userPatch enabled or default_open for one server
      POST/connectors/custom-mcp/testuserProbe an inline server spec or a saved server
      GET/connectors/weknora/detect-localuserCheck whether a local WeKnora service is reachable from the Octop host

      For custom MCP OAuth, save the server first, then probe it. If the probe result reports OAuth support and no token is configured, start the OAuth flow with 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

      Use the unified OAuth start endpoint for both catalog connectors and custom MCP servers.

      MethodPathAuthWhat it does
      POST/connectors/oauth/startuserStart OAuth for a catalog connector or a custom MCP server
      POST/connectors/oauth/{kind}/startuserLegacy catalog-only OAuth start endpoint
      GET/connectors/oauth/callbackpublicOAuth redirect target
      GET/connectors/oauth/pending/{state_id}userPoll the OAuth result

      Catalog connector target:

      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"}}'

      Custom MCP target:

      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"}}'

      The response contains authorize_url and state_id. Open authorize_url, finish the provider login, then poll /connectors/oauth/pending/{state_id}. Non-loopback OAuth callbacks require a public HTTPS Octop URL.

      Built-in connector notes

      • WeKnora uses custom fields: base_url, optional api_key, optional tenant_id, and optional knowledge_base_ids. Octop normalizes the base URL to /api/v1.
      • Dify uses custom fields: mcp_url. The URL must be a Dify MCP Server URL that contains /mcp/server/ and ends with /mcp.
      • Feishu CLI and WeCom CLI connectors can report host CLI status and run host-side CLI installation endpoints. Use those only from the web UI or an admin workflow that can safely install host tools.