Arclan Registry API

openapi: 3.2.0
info:
  title: Arclan MCP Registry API
  version: '1.0'
  description: 'Arclan continuously discovers, validates, and scores MCP (Model Context Protocol) servers.

    Every server in the registry has passed at least one live MCP handshake, or is classified

    by the reason it has not (auth-gated, unreachable, stdio-only, etc.).


    Trust signals - uptime, handshake success rate, latency percentiles, read/write classification,

    and derived flags - are available on every response via the `include` query parameter.


    Base URL: https://arclan.ai'
servers:
- url: https://arclan.ai
  description: Production
tags:
- name: Registry
paths:
  /api/registry:
    get:
      operationId: listServers
      summary: List MCP servers
      description: 'Returns a paginated list of MCP servers. By default returns connectable states only

        (active, mcp_partial, auth_gated). Use `status=all` for the full set.


        Add `include=trust,auth,capabilities,flags` to get decomposed trust signals on each server.

        Use filters like `production_safe=true` or `max_latency_p95=500` to narrow to production-ready servers.'
      parameters:
      - name: status
        in: query
        description: 'Filter by server status. Default returns connectable states (active, mcp_partial, auth_gated).

          Pass `all` for every state.

          '
        schema:
          type: string
          enum:
          - active
          - auth_gated
          - degraded
          - mcp_partial
          - stdio
          - unreachable
          - invalid
          - zombie
          - all
      - name: include
        in: query
        description: 'Comma-separated list of extra blocks to include on each server object.

          - `trust` - uptime_24h, uptime_7d, handshake_success_rate, latency percentiles, last_successful_check

          - `auth` - auth type and scoping

          - `capabilities` - read/write classification and tool count

          - `flags` - derived boolean flags (production_safe, read_only, unstable, high_latency, requires_auth)

          '
        schema:
          type: string
          example: trust,auth,capabilities,flags
      - name: production_safe
        in: query
        description: 'When `true`, returns only servers where uptime_7d > 0.97, handshake_success_rate > 0.95,

          and status is active. Strict inequalities.

          '
        schema:
          type: boolean
      - name: read_only
        in: query
        description: Return only servers whose tools are classified as read-only (no write verbs).
        schema:
          type: boolean
      - name: min_uptime
        in: query
        description: 'Minimum 7-day uptime fraction (0.0-1.0). Example: 0.95'
        schema:
          type: number
          minimum: 0
          maximum: 1
      - name: max_latency_p95
        in: query
        description: 'Maximum p95 validation latency in milliseconds. Example: 500'
        schema:
          type: integer
      - name: auth_type
        in: query
        description: Filter by auth type.
        schema:
          type: string
          enum:
          - none
          - bearer
          - api_key
          - oauth
      - name: capability
        in: query
        description: Full-text filter on tool names, server name, and description.
        schema:
          type: string
      - name: min_score
        in: query
        description: Minimum composite score (0-100).
        schema:
          type: integer
          minimum: 0
          maximum: 100
      - name: transport
        in: query
        schema:
          type: string
          enum:
          - http
          - sse
          - stdio
          - unknown
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryListResponse'
      tags:
      - Registry
  /api/registry/{id}:
    get:
      operationId: getServer
      summary: Get a single MCP server
      description: 'Returns full detail for one server, including test history, agent reports,

        and the complete trust/auth/capabilities/flags blocks (always present on this endpoint).'
      parameters:
      - name: id
        in: query
        required: true
        description: Server slug ID (e.g. `mcp-xpay-sh-sse`)
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerDetail'
        '404':
          description: Not found
      tags:
      - Registry
  /api/registry/{id}/health:
    get:
      operationId: getServerHealth
      summary: 30-day daily health history
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      tags:
      - Registry
components:
  schemas:
    ServerDetail:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    RegistryListResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true