> ## Documentation Index
> Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Mcp Servers



## OpenAPI

````yaml /api-reference/openapi.yaml get /api/registry/v1/servers
openapi: 3.1.0
info:
  title: Barndoor.ai Public API
  description: Unified public API specification for Barndoor.ai platform
  version: 2.18.0
servers:
  - url: https://{host}
    description: Barndoor public API
    variables:
      host:
        default: platform.barndoor.ai
        description: >-
          The host serving your Barndoor deployment. Defaults to production;
          override it for another environment or a dedicated deployment.
security:
  - ApiKey: []
  - OAuth2:
      - openid
      - profile
      - email
tags:
  - name: dlp
    x-group: Data Control Center
  - name: identity
    x-group: Identity
  - name: llm-gateway
    x-group: LLM Gateway
  - name: notification
    x-group: Notifications
  - name: policy
    x-group: Policies
  - name: registry
    x-group: MCP Gateway
  - name: system-management
    x-group: Log Exports
paths:
  /api/registry/v1/servers:
    get:
      tags:
        - registry
      summary: Get Mcp Servers
      operationId: list_mcp_servers
      parameters:
        - name: search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Search servers by name, slug, or source
            title: Search
          description: Search servers by name, slug, or source
        - name: availability_status
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: >-
              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.
            title: Availability Status
          description: >-
            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.
        - name: order_by
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              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.
            enum:
              - name
              - created_at
              - attention
            default: name
            title: Order By
          description: >-
            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.
        - name: order
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: 'Order direction: asc or desc (default: asc)'
            default: asc
            title: Order
          description: 'Order direction: asc or desc (default: asc)'
        - name: include_service_accounts
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Include service account connections for can_manage_policies
              computation (does not affect connection_status)
            default: false
            title: Include Service Accounts
          description: >-
            Include service account connections for can_manage_policies
            computation (does not affect connection_status)
        - name: include_connection_status
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Include connection_status computation (requires Bao calls). Set to
              false for better performance when connection_status is not needed.
            default: true
            title: Include Connection Status
          description: >-
            Include connection_status computation (requires Bao calls). Set to
            false for better performance when connection_status is not needed.
        - name: audience_scoped
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              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.
            default: false
            title: Audience Scoped
          description: >-
            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.
        - name: include_local
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: >-
              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.
            title: Include Local
          description: >-
            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.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: Page number (1-based)
            default: 1
            title: Page
          description: Page number (1-based)
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Number of items per page (max 100)
            default: 10
            title: Limit
          description: Number of items per page (max 100)
        - name: connection_status
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
              - type: string
              - type: 'null'
            description: >-
              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'].
            title: Connection Status
          description: >-
            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'].
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
              - type: 'null'
            description: >-
              Filter by server status: pending, active, error. For multiple
              values, repeat the parameter (e.g., ?status=active&status=error)
            title: Status
          description: >-
            Filter by server status: pending, active, error. For multiple
            values, repeat the parameter (e.g., ?status=active&status=error)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginationResponse_ServerListResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PaginationResponse_ServerListResponse_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ServerListResponse'
          type: array
          title: Data
          description: Array of items for current page
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
          description: Pagination metadata
      type: object
      required:
        - data
        - pagination
      title: PaginationResponse[ServerListResponse]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ServerListResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        enabled:
          type: boolean
          title: Enabled
          default: true
        configuration:
          additionalProperties: true
          type: object
          title: Configuration
        name:
          type: string
          title: Name
        slug:
          type: string
          title: Slug
        oauth_base_url_override:
          anyOf:
            - type: string
            - type: 'null'
          title: Oauth Base Url Override
        client_id:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Client Id
        client_secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Secret
        uses_managed_credentials:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Uses Managed Credentials
        ema_enabled:
          type: boolean
          title: Ema Enabled
          default: false
        scopes:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          title: Scopes
        organization_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Organization Id
        mcp_server_directory_id:
          type: string
          format: uuid
          title: Mcp Server Directory Id
        status:
          type: string
        meta:
          title: Meta
        tools_fetch_status:
          type: string
        tools_fetch_error:
          title: Tools Fetch Error
        tools_fetched_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Tools Fetched At
        tools_fetch_requested_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Tools Fetch Requested At
        published_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Published At
        mcp_server_directory:
          $ref: '#/components/schemas/MCPServerDirectoryBase'
        mcp_server_service_connection:
          anyOf:
            - $ref: '#/components/schemas/ServerConnectionResponse'
            - type: 'null'
        connection_status:
          anyOf:
            - $ref: '#/components/schemas/ConnectionStatus'
            - type: 'null'
        connection_error_reason:
          anyOf:
            - $ref: '#/components/schemas/ConnectionErrorReason'
            - type: 'null'
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        proxy_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Proxy Url
        can_manage_policies:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Can Manage Policies
        attention_tier:
          anyOf:
            - $ref: '#/components/schemas/AttentionTier'
            - type: 'null'
        publish_blockers:
          anyOf:
            - items:
                $ref: '#/components/schemas/PublishBlocker'
              type: array
            - type: 'null'
          title: Publish Blockers
        deleted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Deleted At
        credential_mode:
          $ref: '#/components/schemas/CredentialMode'
          description: >-
            Where the server's OAuth client credentials come from. `managed`:
            Barndoor's managed OAuth client for this provider. `cimd`:
            Barndoor's client ID metadata document. `dcr`: a client registered
            with the provider through dynamic client registration. `manual`: a
            client ID entered by an administrator. `static_client`: a per-server
            client that was either entered by hand or registered through dynamic
            client registration by a request that did not name
            `credential_mode`, so Barndoor cannot tell which. It changes when an
            update stores a client whose source is known: managed credentials, a
            client Barndoor registers, or a new client ID sent with
            `credential_mode: manual`. `none`: the server holds no OAuth client
            (not yet configured, or its provider does not use OAuth).
        uses_cimd:
          type: boolean
          title: Uses Cimd
          description: >-
            Deprecated: use `credential_mode`. Whether this live server
            identifies itself to the provider with Barndoor's OAuth Client ID
            Metadata Document.
          default: false
          deprecated: true
        tools_count:
          type: integer
          title: Tools Count
          readOnly: true
        resources_count:
          type: integer
          title: Resources Count
          readOnly: true
      type: object
      required:
        - id
        - created_at
        - updated_at
        - enabled
        - configuration
        - name
        - slug
        - oauth_base_url_override
        - client_id
        - client_secret
        - uses_managed_credentials
        - ema_enabled
        - scopes
        - organization_id
        - mcp_server_directory_id
        - status
        - meta
        - tools_fetch_status
        - tools_fetch_error
        - tools_fetched_at
        - tools_fetch_requested_at
        - published_at
        - mcp_server_directory
        - mcp_server_service_connection
        - connection_status
        - connection_error_reason
        - url
        - proxy_url
        - can_manage_policies
        - attention_tier
        - publish_blockers
        - deleted_at
        - credential_mode
        - uses_cimd
        - tools_count
        - resources_count
      title: ServerListResponse
      description: >-
        List-row shape for GET /servers.


        ``cascaded_fields`` is excluded from list payloads and the OpenAPI
        schema

        (same mechanism as ``tools``/``resources`` above): it's connect-flow
        data

        for a single server, sourced from Bao, and is only served by the

        single-server GET endpoints.
    PaginationMeta:
      properties:
        page:
          type: integer
          title: Page
          description: Current page number
        limit:
          type: integer
          title: Limit
          description: Items per page
        total:
          type: integer
          title: Total
          description: Total number of items
        pages:
          type: integer
          title: Pages
          description: Total number of pages
        previous_page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Previous Page
          description: Previous page number (null if first page)
        next_page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Next Page
          description: Next page number (null if last page)
      type: object
      required:
        - page
        - limit
        - total
        - pages
        - previous_page
        - next_page
      title: PaginationMeta
      description: Pagination metadata.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    MCPServerDirectoryBase:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        runtime:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Runtime
        configuration_schema:
          additionalProperties: true
          type: object
          title: Configuration Schema
        tool_manifest:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Tool Manifest
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        icon:
          anyOf:
            - type: string
            - type: 'null'
          title: Icon
        slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Slug
        organization_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Organization Id
        url:
          type: string
          title: Url
        protocol:
          $ref: '#/components/schemas/Protocol'
          default: mcp
        source:
          $ref: '#/components/schemas/ServerSource'
          default: barndoor
        provider:
          type: string
          title: Provider
          description: The provider name to use when registering with OpenBao
          default: custom
        provider_options:
          title: Provider Options
        scopes:
          items:
            type: string
          type: array
          title: Scopes
        oauth_metadata:
          additionalProperties: true
          type: object
          title: Oauth Metadata
        protected_resource_metadata:
          additionalProperties: true
          type: object
          title: Protected Resource Metadata
        allow_oauth_override:
          type: boolean
          title: Allow Oauth Override
          default: false
        meta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
        auth_params:
          title: Auth Params
        credential_schema:
          title: Credential Schema
        public:
          type: boolean
          title: Public
          default: false
        requires_auth:
          type: boolean
          title: Requires Auth
          default: false
        requires_auth_observed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Requires Auth Observed At
          description: >-
            When requires_auth was last observed. NULL = not observed since the
            last URL change.
      type: object
      required:
        - id
        - created_at
        - updated_at
        - runtime
        - configuration_schema
        - tool_manifest
        - name
        - description
        - icon
        - slug
        - organization_id
        - url
        - protocol
        - source
        - provider
        - provider_options
        - scopes
        - oauth_metadata
        - protected_resource_metadata
        - allow_oauth_override
        - meta
        - auth_params
        - credential_schema
        - public
        - requires_auth
        - requires_auth_observed_at
      title: MCPServerDirectoryBase
    ServerConnectionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        mcp_server_id:
          type: string
          format: uuid
          title: Mcp Server Id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        application_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Application Id
        status:
          type: string
          title: Status
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        created_at:
          type: string
          format: date-time
          title: Created At
        connected_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Connected At
        last_accessed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Accessed At
        connected_by_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connected By User Id
        account_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Email
        error_reason:
          anyOf:
            - $ref: '#/components/schemas/ConnectionErrorReason'
            - type: 'null'
      type: object
      required:
        - id
        - mcp_server_id
        - status
        - created_at
      title: ServerConnectionResponse
      description: Public service-connection shape exposed from server endpoints.
    ConnectionStatus:
      type: string
      enum:
        - pending
        - connected
        - available
        - error
      title: ConnectionStatus
      description: |-
        Connection status values for MCP servers.

        These values represent the computed connection status of a server
        from the user's perspective, taking into account server configuration,
        Bao registration, and user connections.
    ConnectionErrorReason:
      type: string
      enum:
        - authorization_not_completed
        - authorization_denied
        - reauthorization_required
        - other
      title: ConnectionErrorReason
      description: >-
        Why a connection is in ``error``, as a code safe to show its owner.


        It is derived from ``error_message``, which can hold an arbitrary
        exception

        string and is never shown in its place.
    AttentionTier:
      type: string
      enum:
        - pending_publish
        - connection_error
        - pending_credentials
        - pending_connection
        - available
      title: AttentionTier
      description: >-
        BCP-3815 — API vocabulary for the :func:`attention_rank_expr` tiers.


        Emitted as ``attention_tier`` on server read payloads so the client
        badges a

        server from the same CASE that filters (``availability_filter_expr``),
        sorts

        (``order_by=attention``) and counts (``/servers/summary``) it — one

        classification, declared once, instead of a second hand-written copy in

        TypeScript that could drift with every suite green.
    PublishBlocker:
      type: string
      enum:
        - not_operationally_available
        - no_active_policy
      title: PublishBlocker
      description: >-
        BCP-3815 — why ``POST /servers/{id}/publish`` would currently 422.


        One value per gate the publish route enforces, in the order it checks
        them.
    CredentialMode:
      type: string
      enum:
        - managed
        - cimd
        - dcr
        - manual
        - static_client
        - none
      title: CredentialMode
      description: >-
        Where a server's OAuth client credentials come from.


        `static_client`: a per-server client that was either entered by hand or

        dynamically registered, written by a request that did not name the mode,
        so

        the row cannot tell which. `none`: the row holds no OAuth client (a
        pending

        server, a non-OAuth directory, or a local-provider install).
    Protocol:
      type: string
      enum:
        - mcp
        - sse
      title: Protocol
      description: Protocol enum for MCP server communication.
    ServerSource:
      type: string
      enum:
        - barndoor
        - third_party
        - internal
        - custom_third_party
        - custom_internal
        - local
        - embedded
      title: ServerSource
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: >-
        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.
    OAuth2:
      type: oauth2
      x-issuer: https://auth.barndoor.ai/realms/barndoor
      description: >-
        An OAuth 2.0 access token from Barndoor's identity provider, sent as
        `Authorization: Bearer <token>`. Public clients must use PKCE.
        Interchangeable with an API key.
      flows:
        authorizationCode:
          authorizationUrl: >-
            https://auth.barndoor.ai/realms/barndoor/protocol/openid-connect/auth
          tokenUrl: >-
            https://auth.barndoor.ai/realms/barndoor/protocol/openid-connect/token
          scopes:
            openid: Issue an OIDC ID token identifying the caller.
            profile: Read the caller's basic profile claims.
            email: Read the caller's email address.
            offline_access: Issue a refresh token. Optional — no operation requires it.
        clientCredentials:
          tokenUrl: >-
            https://auth.barndoor.ai/realms/barndoor/protocol/openid-connect/token
          scopes:
            openid: Issue an OIDC ID token identifying the caller.
            profile: Read the caller's basic profile claims.
            email: Read the caller's email address.
            offline_access: Issue a refresh token. Optional — no operation requires it.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.