> ## 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.

# List Server Directory

> List server directories with pagination.



## OpenAPI

````yaml /api-reference/openapi.yaml get /api/registry/v1/server-directory
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/server-directory:
    get:
      tags:
        - registry
      summary: List Server Directory
      description: List server directories with pagination.
      operationId: list_mcp_server_directory
      parameters:
        - name: search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Search server directories by name or description
            title: Search
          description: Search server directories by name or description
        - name: category
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
              - type: 'null'
            description: Filter by category slug(s)
            title: Category
          description: Filter by category slug(s)
        - name: order_by
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: 'Order by field: name or created_at (default: name)'
            default: name
            title: Order By
          description: 'Order by field: name or created_at (default: name)'
        - 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_servers
          in: query
          required: false
          schema:
            type: boolean
            description: Include server instances for the current user's organization
            default: false
            title: Include Servers
          description: Include server instances for the current user's organization
        - name: include_local
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              BCP-4300: false drops catalogs that run locally through the
              Barndoor CLI (embedded and local sources) before pagination, so
              page counts match what an org without the `local-cli-mcp-tooling`
              flag is shown. Defaults to true (unchanged listing).
            default: true
            title: Include Local
          description: >-
            BCP-4300: false drops catalogs that run locally through the Barndoor
            CLI (embedded and local sources) before pagination, so page counts
            match what an org without the `local-cli-mcp-tooling` flag is shown.
            Defaults to true (unchanged listing).
        - 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: source
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Filter by source: barndoor, third_party, internal,
              custom_third_party, custom_internal, local, embedded, or aliases
              'custom' / 'local' (which expand to their component sources)
            title: Source
          description: >-
            Filter by source: barndoor, third_party, internal,
            custom_third_party, custom_internal, local, embedded, or aliases
            'custom' / 'local' (which expand to their component sources)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PaginationResponse_MCPServerDirectoryReadWithServers_
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PaginationResponse_MCPServerDirectoryReadWithServers_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/MCPServerDirectoryReadWithServers'
          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[MCPServerDirectoryReadWithServers]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MCPServerDirectoryReadWithServers:
      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.
        categories:
          items:
            $ref: '#/components/schemas/MCPServerCategory'
          type: array
          title: Categories
          default: []
        active_server_ids:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          title: Active Server Ids
        credential_modes:
          anyOf:
            - $ref: '#/components/schemas/DirectoryCredentialModes'
            - type: 'null'
          description: >-
            The OAuth credential modes a new server from this directory can use,
            for the calling organization. `null` for a directory whose provider
            does not use OAuth, and on the responses of the directory create and
            update routes.
        registered_mcp_servers:
          anyOf:
            - items:
                $ref: '#/components/schemas/ServerResponse'
              type: array
            - type: 'null'
          title: Registered Mcp Servers
      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
        - categories
        - active_server_ids
        - credential_modes
        - registered_mcp_servers
      title: MCPServerDirectoryReadWithServers
    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
    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
    MCPServerCategory:
      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
        name:
          type: string
          title: Name
        slug:
          type: string
          title: Slug
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - id
        - created_at
        - updated_at
        - name
        - slug
        - description
      title: MCPServerCategory
    DirectoryCredentialModes:
      properties:
        automatic:
          type: string
          enum:
            - cimd
            - dcr
            - manual
          title: Automatic
          description: >-
            The mode server create selects with `credential_mode: auto`: `cimd`
            when the provider accepts Barndoor's client ID metadata document,
            else `dcr` when it has a registration endpoint, else `manual`.
            Depends on the organization's rollout of the metadata document, so
            it can differ between organizations for the same directory.
        managed:
          type: boolean
          title: Managed
          description: >-
            Barndoor's managed OAuth client can be requested with
            `credential_mode: managed`.
        default:
          type: string
          enum:
            - managed
            - cimd
            - dcr
            - manual
          title: Default
          description: >-
            The mode to preselect when creating a server: `managed` when it is
            available and `automatic` would otherwise leave the administrator to
            enter a client ID, else `automatic`.
      type: object
      required:
        - automatic
        - managed
        - default
      title: DirectoryCredentialModes
      description: >-
        The OAuth credential modes a new server from this directory can use, for
        the calling organization.
    ServerResponse:
      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
        cascaded_fields:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          title: Cascaded Fields
        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
        - cascaded_fields
        - deleted_at
        - credential_mode
        - uses_cimd
        - tools_count
        - resources_count
      title: ServerResponse
      description: |-
        Response model for MCP server with computed fields.

        This model includes both database fields and computed fields like
        connection_status, url, and proxy_url that are added at runtime.
    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).
  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.