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

# 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

| Method   | Path                                         | Auth  | What it does                                    |
| -------- | -------------------------------------------- | ----- | ----------------------------------------------- |
| `GET`    | `/connectors/catalog`                        | user  | List built-in connector presets                 |
| `GET`    | `/connector-instances`                       | user  | List your connector instances                   |
| `POST`   | `/connector-instances`                       | user  | Create a connector instance                     |
| `GET`    | `/connector-instances/{instance_id}`         | user  | Get one connector instance                      |
| `PATCH`  | `/connector-instances/{instance_id}`         | owner | Rename, enable, or change default-open settings |
| `DELETE` | `/connector-instances/{instance_id}`         | owner | Delete a connector instance                     |
| `POST`   | `/connector-instances/{instance_id}/test`    | owner | Test the saved connector                        |
| `POST`   | `/connector-instances/{instance_id}/refresh` | owner | Refresh 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

| Method  | Path                                    | Auth | What it does                                                           |
| ------- | --------------------------------------- | ---- | ---------------------------------------------------------------------- |
| `GET`   | `/connectors/custom-mcp`                | user | Read your custom MCP server map                                        |
| `PUT`   | `/connectors/custom-mcp`                | user | Replace your custom MCP server map                                     |
| `PATCH` | `/connectors/custom-mcp/servers/{name}` | user | Patch `enabled` or `default_open` for one server                       |
| `POST`  | `/connectors/custom-mcp/test`           | user | Probe an inline server spec or a saved server                          |
| `GET`   | `/connectors/weknora/detect-local`      | user | Check 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"`.

```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

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

| Method | Path                                   | Auth   | What it does                                               |
| ------ | -------------------------------------- | ------ | ---------------------------------------------------------- |
| `POST` | `/connectors/oauth/start`              | user   | Start OAuth for a catalog connector or a custom MCP server |
| `POST` | `/connectors/oauth/{kind}/start`       | user   | Legacy catalog-only OAuth start endpoint                   |
| `GET`  | `/connectors/oauth/callback`           | public | OAuth redirect target                                      |
| `GET`  | `/connectors/oauth/pending/{state_id}` | user   | Poll the OAuth result                                      |

Catalog connector target:

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

Custom MCP target:

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

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.

When the authorization server has no dynamic client registration, the probe sets `oauth.client_required`. Save `oauth_client.client_id` on the custom MCP spec. `client_secret` is write-only. Register `<public base>/api/connectors/oauth/callback` as the redirect URI.

## 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.
