Add an MCP connection for the workspace or for yourself

POST

/connections/mcp

• Production

Constraints not expressible in JSON Schema, enforced at runtime:

• headerName and headerValue are sent together or not at all.
• clientSecret is accepted only together with its clientId.
• returnPath is a path on this site: it starts with one /, never //.

May require, depending on the request: connections.write, connections.org.write

Authorizations

• bearerAuth

Parameters

Query Parameters

scope

required

org: the workspace’s accounts, used by every member’s tasks; me: the caller’s own, in this workspace.

string

Allowed values: org me

org: the workspace’s accounts, used by every member’s tasks; me: the caller’s own, in this workspace.

Header Parameters

x-uai-org

string

Org scope: me or an org slug. Absent means the caller’s active/personal org. It selects the workspace used for permission checks and for most resource filters; operation-specific access rules still apply.

Request Body ^required

object

name

required

string

>= 1 characters <= 64 characters

url

required

The server’s https endpoint.

string format: uri

<= 2048 characters

headerName

A static header the server takes. Write-only.

string

>= 1 characters <= 128 characters

headerValue

Its value. Write-only.

string

>= 1 characters <= 4096 characters

clientId

An OAuth client of your own, for a server without registration.

string

>= 1 characters <= 512 characters

clientSecret

Its secret. Write-only.

string

>= 1 characters <= 2048 characters

templateId

The catalog entry it is added from.

string

>= 1 characters <= 64 characters

returnPath

Where the sign-in lands the browser back.

string

<= 512 characters /^\//

Responses

200

Successful response.

Any of:

object

object

connection

required

object

id

required

string

scope

required

org: the workspace’s accounts, used by every member’s tasks; me: the caller’s own, in this workspace.

string

Allowed values: org me

name

required

string

slug

required

string

url

required

string

authKind

required

string

Allowed values: oauth token none

policy

required

string

Allowed values: on ask off

status

required

string

Allowed values: connected needs_sign_in signed_out

templateId

required

string | null

createdAt

required

integer

object

object

authorizeUrl

required

Send the browser here to sign in; it comes back to returnPath.

string

400

INVALID_REQUEST — a query parameter does not match the route’s query schema, or the same parameter was sent twice. A repeat is rejected rather than resolved: guards read the first value and a parsed object would keep the last.

BAD_JSON — the body is not valid JSON, or INVALID_REQUEST — the decoded body does not match the route’s request schema.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

401

UNAUTHORIZED — missing or invalid token, or an org-scoped API key (only user-scoped keys are accepted).

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

402

PLAN_LIMIT — the workspace’s plan does not include API access. Every API-key call can return this; session-token calls never do.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

403

FORBIDDEN (lacking the required permission) or SCOPE_REQUIRED (no workspace, or a membership change in progress).

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

404

SCOPE_REQUIRED — the x-uai-org scope names a workspace that does not exist, or one the caller is not a member of. The two are deliberately indistinguishable: a 403 would confirm the workspace exists.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

413

PAYLOAD_TOO_LARGE — the request body exceeds 16384 bytes.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

503

SCOPE_REQUIRED — membership reconciliation required, or membership verification unavailable.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any