API reference

Connectors

Add, test, rotate and remove connectors.

`GET /v1/orgs/:orgId/connectors`

Lists connectors. Credentials are never returned.

Auth: user access token or platform agent key · Scope: connectors:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  connectors: {
    toolCount: number
    omittedTools: number
    oauth?: {
      connected: boolean
      server: null | string
      registered: boolean | null
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    lastError?: string
    lastCheckedAt?: number
  }[]
}

`GET /v1/orgs/:orgId/connectors/:connectorId`

A connector with its cached tools and the names they have on the MCP server.

Auth: user access token or platform agent key · Scope: connectors:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:connectorId`	Connector id (`con_…`).

Response 200

{
  connector: {
    toolCount: number
    omittedTools: number
    oauth?: {
      connected: boolean
      server: null | string
      registered: boolean | null
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    lastError?: string
    lastCheckedAt?: number
  }
  tools: {
    exposedName: string
    name: string
    title?: string
    description?: string
    inputSchema: {
      [key: string]: unknown
    }
  }[]
}

Errors

Status	Message
`404`	Connector not found

`POST /v1/orgs/:orgId/connectors`

Registers a remote MCP server.

Auth: user access token or platform agent key · Scope: connectors:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Default	Notes
`name`	`string`	Yes		1–64 characters; trimmed
`slug`	`string`	Yes		matches `^[a-z](?:[a-z0-9-]{0,22}[a-z0-9])?$`; trimmed
`url`	`string`	Yes		1–2,048 characters; trimmed
`authType`	`"none" \| "bearer" \| "header" \| "oauth"`	No	`"none"`
`transport`	`"http" \| "sse"`	No	`"http"`
`headerName`	`string`	No		trimmed
`secret`	`string`	No		1–4,096 characters; matches `^[\x20-\x7E]+$`; trimmed
`oauthClientId`	`string`	No		1–512 characters; trimmed
`oauthClientSecret`	`string`	No		1–4,096 characters; matches `^[\x20-\x7E]+$`; trimmed

Also checked: Enter the credential. Enter a valid header name (for example X-API-Key).

Response 201

{
  connector: {
    toolCount: number
    omittedTools: number
    oauth?: {
      connected: boolean
      server: null | string
      registered: boolean | null
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    lastError?: string
    lastCheckedAt?: number
  }
}

Errors

Status	Message
`400`	An organization can have up to … connectors.
`404`	Connector not found
`409`	Slug "…" is already in use.

`POST /v1/orgs/:orgId/connectors/:connectorId/test`

Connects to the server and caches its tool list. A failed check keeps the last good list and records the error.

Auth: user access token or platform agent key · Scope: connectors:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:connectorId`	Connector id (`con_…`).

Response 200

{
  connector: {
    toolCount: number
    omittedTools: number
    oauth?: {
      connected: boolean
      server: null | string
      registered: boolean | null
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    lastError?: string
    lastCheckedAt?: number
  }
}

Errors

Status	Message
`404`	Connector not found

`PATCH /v1/orgs/:orgId/connectors/:connectorId`

Renames, enables or disables a connector, or replaces its credential.

Auth: user access token or platform agent key · Scope: connectors:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:connectorId`	Connector id (`con_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	No	1–64 characters; trimmed
`enabled`	`boolean`	No
`secret`	`string`	No	1–4,096 characters; matches `^[\x20-\x7E]+$`; trimmed

Also checked: Nothing to update.

Response 200

{
  connector: {
    toolCount: number
    omittedTools: number
    oauth?: {
      connected: boolean
      server: null | string
      registered: boolean | null
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    lastError?: string
    lastCheckedAt?: number
  }
}

Errors

Status	Message
`400`	This connector doesn't use a credential.
`404`	Connector not found

`DELETE /v1/orgs/:orgId/connectors/:connectorId`

Deletes a connector.

Auth: user access token or platform agent key · Scope: connectors:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:connectorId`	Connector id (`con_…`).

Response 204 with no body.

Errors

Status	Message
`404`	Connector not found

`POST /v1/orgs/:orgId/connectors/:connectorId/oauth/start`

OAuth connectors: finds the server's sign-in (and registers a client when the server allows it), stores a one-time state with a PKCE verifier and returns the authorization URL to send the user to.

Auth: user access token or platform agent key · Scope: connectors:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:connectorId`	Connector id (`con_…`).

Request body

Field	Type	Required	Notes
`returnTo`	`string`	No	up to 500 characters

Response 200

{
  url: string
}

Errors

Status	Message
`400`	This connector doesn't use OAuth.
`403`	Signing in to a connector needs a signed-in user.
`404`	Connector not found

`POST /v1/orgs/:orgId/connectors/oauth/callback`

Completes a connector sign-in: consumes the state (one use; same user and org), exchanges the code, stores the tokens encrypted and checks the connector's tools with them.

Auth: user access token or platform agent key · Scope: connectors:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`state`	`string`	Yes	10–300 characters
`code`	`string`	No	1–4,000 characters
`error`	`string`	No	up to 200 characters

Response 200

{
  connected: false
  returnTo: string
  connectorId: string
}
| {
  connected: true
  returnTo: string
  connectorId: string
}

Errors

Status	Message
`404`	Connector not found
`409`	Start the sign-in again.

Connectors

On this page