API reference
Connectors
Add, test, rotate and remove connectors.
See 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: {
hasSecret: boolean
toolCount: number
omittedTools: number
url: string
name: string
status?: "ok" | "unknown" | "error"
createdAt?: number
updatedAt?: number
orgId: string
slug: string
createdBy: string
enabled?: boolean
connectorId: string
authType: "header" | "none" | "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: {
hasSecret: boolean
toolCount: number
omittedTools: number
url: string
name: string
status?: "ok" | "unknown" | "error"
createdAt?: number
updatedAt?: number
orgId: string
slug: string
createdBy: string
enabled?: boolean
connectorId: string
authType: "header" | "none" | "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" | No | "none" | |
headerName | string | No | trimmed | |
secret | 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: {
hasSecret: boolean
toolCount: number
omittedTools: number
url: string
name: string
status?: "ok" | "unknown" | "error"
createdAt?: number
updatedAt?: number
orgId: string
slug: string
createdBy: string
enabled?: boolean
connectorId: string
authType: "header" | "none" | "bearer"
headerName?: string
lastError?: string
lastCheckedAt?: number
}
}Errors
| Status | Message |
|---|---|
400 | An organization can have up to 50 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: {
hasSecret: boolean
toolCount: number
omittedTools: number
url: string
name: string
status?: "ok" | "unknown" | "error"
createdAt?: number
updatedAt?: number
orgId: string
slug: string
createdBy: string
enabled?: boolean
connectorId: string
authType: "header" | "none" | "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: {
hasSecret: boolean
toolCount: number
omittedTools: number
url: string
name: string
status?: "ok" | "unknown" | "error"
createdAt?: number
updatedAt?: number
orgId: string
slug: string
createdBy: string
enabled?: boolean
connectorId: string
authType: "header" | "none" | "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 |