> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budecosystem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors Reference

> API surfaces, payloads, scopes, and connector operations

## Primary Admin Surfaces

| Surface                     | Purpose                                                                            |
| --------------------------- | ---------------------------------------------------------------------------------- |
| **Connectors tab**          | Browse registry connectors and start the add-connection flow.                      |
| **Connections tab**         | Manage configured MCP gateways and custom connections.                             |
| **Triggers tab**            | Manage shared event connections for trigger providers.                             |
| **Agent Connections panel** | Authorize available gateways, list tools, attach tools, and detach from one agent. |

## MCP Gateway Operations

| Operation                 | Endpoint Pattern                                   | Notes                                          |
| ------------------------- | -------------------------------------------------- | ---------------------------------------------- |
| List registry connectors  | `GET /connectors/registry`                         | Supports pagination and name search.           |
| Get registry connector    | `GET /connectors/registry/{connector_id}`          | Returns metadata and credential schema.        |
| Configure connector       | `POST /connectors/gateways`                        | Creates a gateway from a registry connector.   |
| Create custom gateway     | `POST /connectors/custom`                          | Bypasses the registry for a custom MCP server. |
| List configured           | `GET /connectors/configured`                       | Can include disabled connections.              |
| Toggle configured gateway | `PATCH /connectors/configured/{gateway_id}/toggle` | Enables or disables availability.              |
| Update connection tags    | `PATCH /connectors/configured/{gateway_id}`        | Updates client tags and agent scope tags.      |
| Delete gateway            | `DELETE /connectors/gateways/{gateway_id}`         | Removes the shared gateway.                    |

## Agent Tool Operations

| Operation               | Endpoint Pattern                                                  | Notes                                    |
| ----------------------- | ----------------------------------------------------------------- | ---------------------------------------- |
| List available gateways | `GET /connectors/available`                                       | Can filter by project ID.                |
| Start OAuth             | `POST /connectors/{gateway_id}/oauth/initiate`                    | Accepts a return URL.                    |
| OAuth callback          | `POST /connectors/oauth/callback`                                 | Completes with code and state.           |
| OAuth status            | `GET /connectors/{gateway_id}/oauth/status`                       | Shows authorization state.               |
| Fetch tools             | `POST /connectors/{gateway_id}/fetch-tools`                       | Loads tools after authorization.         |
| List tools              | `GET /connectors/{gateway_id}/tools`                              | Supports pagination.                     |
| Attach tools            | `POST /prompts/{prompt_id}/connections/{gateway_id}/attach-tools` | Stores selected tool IDs for one agent.  |
| Detach connection       | `DELETE /prompts/{prompt_id}/connections/{gateway_id}/detach`     | Removes the gateway from one agent only. |

## Event Connection Operations

| Operation                | Endpoint Pattern                                    | Notes                                          |
| ------------------------ | --------------------------------------------------- | ---------------------------------------------- |
| List descriptors         | `GET /events/descriptors`                           | Descriptor catalog and credential field specs. |
| List shared connections  | `GET /events/shared-connections`                    | Optional project filter.                       |
| Create shared connection | `POST /events/shared-connections`                   | Supports project and global scope.             |
| Update shared connection | `PATCH /events/shared-connections/{connection_id}`  | Rename or replace project share set.           |
| Delete shared connection | `DELETE /events/shared-connections/{connection_id}` | Cascades provider subscriptions.               |

## Scope Payload

```json theme={null}
{
  "enabled": true,
  "global": false,
  "projects": ["project_123"]
}
```

For event connections, global scope omits `project_ids`; project scope sends a non-empty `project_ids` array.

```mermaid theme={null}
flowchart TD
  A{Scope} -->|global| B[Omit project_ids]
  A -->|project| C[Send project_ids]
  C --> D[Deduplicate IDs]
  D --> E[Always include current project]
```