Skip to main content
GET
Get Mcp Servers

Authorizations

Authorization
string
header
required

A Barndoor API key, sent as Authorization: Bearer <key>. Keys are prefixed bdai_ and are opaque — do not attempt to decode one. Interchangeable with an OAuth 2.0 access token.

Query Parameters

search
string | null

Search servers by name, slug, or source

availability_status
boolean | null

Filter by availability status. With the publishing flag on (BCP-3039), True means the state an admin listing renders as Available — published AND still operationally sound — and False is every other state (Pending Publish, Connection Error, Pending Credentials, Pending Connection). Publishing itself is one-way: a published server that later degrades answers False here but stays published, so audience_scoped listings still consider it.

order_by
enum<string>
default:name

Order by field: name, created_at, or attention (default: name). attention (BCP-3664) sorts attention-needing servers first — Pending Publish, Connection Error, Pending Credentials, Pending Connection, then Available — tie-broken by name ASC, then id ASC (the id term is what makes the order total, so paging is deterministic); order is ignored for this field. The rank is computed in SQL from DB-derived state, so it can disagree with the Bao-recomputed can_manage_policies the legacy (non-DB-first) listing path returns. Unrecognized values fall back to created_at rather than erroring — this parameter is under the public API stability contract, so the advertised enum narrows generated clients without tightening server-side validation.

Available options:
name,
created_at,
attention
order
string | null
default:asc

Order direction: asc or desc (default: asc)

include_service_accounts
boolean
default:false

Include service account connections for can_manage_policies computation (does not affect connection_status)

include_connection_status
boolean
default:true

Include connection_status computation (requires Bao calls). Set to false for better performance when connection_status is not needed.

audience_scoped
boolean
default:false

BCP-3661: restrict the listing to servers this user may discover — published AND named by an active allow rule on one of the server's ACTIVE policies. Opt-in, because this same endpoint serves admin surfaces (policy authoring, connector pickers) that must keep seeing every server; filtering those would make a new server impossible to write its first policy for. Set it on end-user surfaces (My Apps) only. NOT gated by the mcp-server-publishing flag — an explicit request is always honoured (a flag-eval outage must not silently serve the unfiltered listing); the rollout gate is whether a surface sends the parameter at all (BCP-3735). Fails closed with HTTP 503 when the visible set cannot be resolved.

include_local
boolean | null

BCP-4300: include servers that run locally through the Barndoor CLI (embedded and local catalogs). Omitted, the registry resolves it from the org's local-cli-mcp-tooling flag (fail-closed); an explicit value is always honoured.

page
integer
default:1

Page number (1-based)

Required range: x >= 1
limit
integer
default:10

Number of items per page (max 100)

Required range: 1 <= x <= 100
connection_status

Filter by connection status: connected, available, pending, error, not_connected. For multiple values, repeat the parameter (e.g., ?connection_status=connected&connection_status=available). 'not_connected' expands to ['pending', 'error', 'available'].

status
string[] | null

Filter by server status: pending, active, error. For multiple values, repeat the parameter (e.g., ?status=active&status=error)

Response

Successful Response

data
ServerListResponse · object[]
required

Array of items for current page

pagination
PaginationMeta · object
required

Pagination metadata