Skip to main content
Connectors are a curated catalog of pre-built integrations, each described by a manifest (auth fields, MCP transport, verify probe, OAuth block). Browse the catalog, verify submitted credentials against the provider, then install to materialize a workspace- or crew-scoped integration. This is the catalog flow; the /api/v1/integrations endpoints remain the path for the “Custom MCP server” escape hatch. List and Get are open to any authenticated role; Verify and Install require a workspace_id and a MANAGER+ role on that workspace.

​
Auth Modes

A manifest’s auth_mode determines how credentials are collected and what the install flow returns next:
auth_modeMeaning
patPersonal access token / API key pasted into form fields
conn_stringConnection string pasted into form fields
mcp_oauthThe MCP server itself drives OAuth 2.1 + DCR; install returns next_step: "mcp_oauth"
byo_oauthBring-your-own OAuth app; install returns next_step: "oauth" plus an oauth_url to open
noneNo credentials required

​
List Connectors

GET /api/v1/connectors
Returns the catalog as an array (stable insertion order; empty array on an empty catalog). Auth: Any authenticated user Response: 200 OK 
[
  {
    "id": "github",
    "name": "GitHub",
    "description": "Issues, PRs, and repo access via the GitHub MCP server",
    "category": "developer-tools",
    "auth_mode": "pat",
    "brand_logo": "https://...",
    "brand_color": "#181717"
  }
]

​
List Item Fields

FieldTypeDescription
idstringConnector ID (manifest id)
namestringDisplay name
descriptionstringShort description
categorystringCatalog category
auth_modestringOne of the auth modes above
brand_logostringBrand logo URL
brand_colorstringBrand accent color
StatusCondition
401Not authenticated

​
Get Connector

GET /api/v1/connectors/{connectorId}
Returns the full manifest verbatim so the frontend can render the schema-driven form (fields, verify block, OAuth block) without a second round-trip. Auth: Any authenticated user
Path ParameterDescription
connectorIdManifest ID
Response: 200 OK — the full connector manifest.
StatusCondition
401Not authenticated
404No connector with this ID

​
Verify Connector

POST /api/v1/connectors/{connectorId}/verify?workspace_id={workspaceId}
Pre-install probe. For pat / conn_string manifests with a verify block, this resolves the submitted field values into the manifest’s verify HTTP request and makes one call against the provider. mcp_oauth, byo_oauth, and none skip the probe (auth happens via redirect) and return ok: true. The outbound probe is SSRF-safe: the resolved URL is validated and dialed through a guarded client that rejects loopback, RFC1918, and cloud-metadata addresses. Auth: MANAGER+ role on the workspace Request Body:
FieldTypeDescription
fieldsobjectMap of user-submitted form values keyed by field key
{ "fields": { "token": "ghp_xxx" } }
Response: 200 OK 
{ "ok": true, "message": "" }
ok: false means the provider rejected the credentials — the call itself succeeded, so treat it as user-correctable, not a server error. The message carries a human-readable cause (e.g. a bounded snippet of the provider’s error response). 4xx is reserved for system-level problems.
StatusCondition
400Invalid body, or a required field is missing
401Not authenticated
403Caller is not MANAGER+
404No connector with this ID

​
Install Connector

POST /api/v1/connectors/{connectorId}/install?workspace_id={workspaceId}
Materializes the manifest’s MCP block against the submitted fields and persists an integration row, encrypting any pat / conn_string / byo_oauth field values into the credential vault. Omit crew_id to install at workspace scope; set it to install at crew scope. Auth: MANAGER+ role on the workspace Request Body:
FieldTypeRequiredDescription
crew_idstringNoCrew ID for crew-scoped install; omit for workspace scope
namestringNoUser-facing label; defaults to the manifest name
fieldsobjectConditionalMap of submitted form values (required fields per the manifest)
{
  "name": "GitHub (org)",
  "fields": { "token": "ghp_xxx" }
}
Response: 201 Created 
{
  "integration_id": "cm1abc123",
  "next_step": "oauth",
  "oauth_url": "https://github.com/login/oauth/authorize?..."
}

​
Response Fields

FieldTypeDescription
integration_idstringID of the created integration row
next_stepstring?"" (complete), "oauth" (open oauth_url), or "mcp_oauth" (hand off to MCP-OAuth/DCR)
oauth_urlstring?Authorization URL to open in a popup (only when next_step is "oauth")
StatusCondition
400Missing workspace_id, invalid body, or a required field is missing
401Not authenticated
403Caller is not MANAGER+
404No connector with this ID