Skip to content
Artist Alley

Register a new MCP-client server

POST
/admin/ai/mcp-clients

Creates a new mcp_server_registration row. The operator- chosen name is the audit-dashboard identifier + the router’s slot key; collisions return 409.

Newly-registered servers default to enabled=false; the operator flips the toggle after whitelisting the tools they want to expose.

Requires mcp.client.admin.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Create payload for POST /admin/ai/mcp-clients.

object
name
required
string
>= 1 characters <= 128 characters
url
required
string
>= 1 characters
transport
string
default: http
Allowed values: http stdio
auth_kind
string
default: none
Allowed values: none bearer header mtls
auth_secret_ref

Write-only. The bearer token / header value used to authenticate to this server. Never returned on any read — responses carry auth_secret_set instead (#711).

string format: password
auth_header_name
string
privacy_class
string
default: cloud
Allowed values: local cloud
enabled
boolean
rate_limit_per_second
integer
default: 2 >= 1
rate_limit_per_minute
integer
default: 60 >= 1
health_check_interval_s
integer
default: 60 >= 1

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Registered

One registered MCP server. Each registration becomes one ai.Provider in the router; the operator-chosen name is the audit-dashboard identifier and the dispatcher slot key.

object
id
required
string format: uuid
name
required
string
>= 1 characters <= 128 characters
url
required
string
>= 1 characters
transport
required
string
Allowed values: http stdio
auth_kind
required
string
Allowed values: none bearer header mtls
auth_secret_set
required

True when an auth secret is currently stored for this server. The secret itself is NEVER returned — despite the _ref name on the write side it holds the live bearer token / header value, and a stored credential has no read-back workflow, so no capability reads it back (#711). Set it via POST / PATCH auth_secret_ref.

boolean
auth_header_name
string
nullable
privacy_class
required
string
Allowed values: local cloud
enabled
required
boolean
rate_limit_per_second
required
integer
>= 1
rate_limit_per_minute
required
integer
>= 1
health_check_interval_s
required
integer
>= 1
last_health_check_at
string format: date-time
nullable
last_health_status
string
nullable
Allowed values: healthy degraded unreachable
last_health_error
string
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time

400

Section titled “400 ”

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

401

Section titled “401 ”

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

403

Section titled “403 ”

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

409

Section titled “409 ”

Conflict (slug taken, would create cycle, etc.)

object
error
required

Human-readable error summary

string
Example
the request could not be completed