openapi: 3.1.0
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
$id: https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi
info:
  title: MCP Server Registry API
  summary: API for discovering and accessing MCP server metadata
  description: |
    Specification for a theoretical REST API that serves up metadata about MCP servers.
  license:
    name: MIT
    identifier: MIT

paths:
  /servers:
    get:
      summary: List MCP servers
      description: Returns a list of all registered MCP servers
      parameters:
        - name: cursor
          in: query
          description: Pagination cursor for retrieving next set of results
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of items to return
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A list of MCP servers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerList'
  /servers/{id}:
    get:
      summary: Get MCP server details
      description: Returns detailed information about a specific MCP server
      parameters:
        - name: id
          in: path
          required: true
          description: Unique ID of the server
          schema:
            type: string
            format: uuid
        - name: version
          in: query
          description: Desired MCP server version
          schema:
            type: string
      responses:
        '200':
          description: Detailed server information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerDetail'
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Server not found"
components:
  schemas:
    Repository:
      type: object
      required:
        - url
        - source
        - id
      properties:
        url:
          type: string
          format: uri
          example: "https://github.com/modelcontextprotocol/servers"
        source:
          type: string
          example: "github"
        id:
          type: string
          example: "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"

    Server:
      type: object
      required:
        - name
        - description
        - version_detail
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        name:
          type: string
          description: "Reverse DNS name of the MCP server"
          example: "io.github.modelcontextprotocol/filesystem"
        description:
          type: string
          description: "Human-readable description of the server's functionality"
          example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
        status:
          type: string
          enum: [active, deprecated]
          default: active
          description: "Server lifecycle status. 'deprecated' indicates the server is no longer recommended for new usage."
          example: "active"
        repository:
          $ref: '#/components/schemas/Repository'
        version_detail:
          $ref: '#/components/schemas/VersionDetail'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    VersionDetail:
      type: object
      required:
        - version
        - release_date
        - is_latest
      properties:
        version:
          type: string
          example: "1.0.2"
          description: Equivalent of Implementation.version in MCP specification.
        release_date:
          type: string
          format: date-time
          example: "2023-06-15T10:30:00Z"
          description: Datetime that the MCP server version was published to the registry.
        is_latest:
          type: boolean
          example: true
          description: Whether the MCP server version is the latest version available in the registry.

    ServerList:
      type: object
      required:
        - servers
      properties:
        servers:
          type: array
          items:
            $ref: '#/components/schemas/Server'
        metadata:
          type: object
          properties:
            next_cursor:
              type: string
              description: Cursor for next page of results
            count:
              type: integer
              description: Number of items in current page
              example: 30

    Package:
      type: object
      required:
        - registry_name
        - name
        - version
      properties:
        registry_name:
          type: string
          description: Package registry type
          example: "npm"
        name:
          type: string
          description: Package name in the registry
          example: "io.modelcontextprotocol/filesystem"
        version:
          type: string
          description: Package version
          example: "1.0.2"
        runtime_hint:
          type: string
          description: A hint to help clients determine the appropriate runtime for the package. This field should be provided when `runtime_arguments` are present.
          examples: [npx, uvx, dnx]
        runtime_arguments:
          type: array
          description: A list of arguments to be passed to the package's runtime command (such as docker or npx). The `runtime_hint` field should be provided when `runtime_arguments` are present.
          items:
            $ref: '#/components/schemas/Argument'
        package_arguments:
          type: array
          description: A list of arguments to be passed to the package's binary.
          items:
            $ref: '#/components/schemas/Argument'
        environment_variables:
          type: array
          description: A mapping of environment variables to be set when running the package.
          items:
            $ref: '#/components/schemas/KeyValueInput'

    Input:
      type: object
      properties:
        description:
          description: A description of the input, which clients can use to provide context to the user.
          type: string
        is_required:
          type: boolean
          default: false
        format:
          type: string
          description: |
            Specifies the input format. Supported values include `filepath`, which should be interpreted as a file on the user's filesystem.

            When the input is converted to a string, booleans should be represented by the strings "true" and "false", and numbers should be represented as decimal values.
          enum: [string, number, boolean, filepath]
          default: string
        value:
          type: string
          description: |
            The default value for the input. If this is not set, the user may be prompted to provide a value. If a value is set, it should not be configurable by end users.

            Identifiers wrapped in `{curly_braces}` will be replaced with the corresponding properties from the input `variables` map. If an identifier in braces is not found in `variables`, or if `variables` is not provided, the `{curly_braces}` substring should remain unchanged.
        is_secret:
          type: boolean
          description: Indicates whether the input is a secret value (e.g., password, token). If true, clients should handle the value securely.
          default: false
        default:
          type: string
          description: The default value for the input.
        choices:
          type: array
          description: A list of possible values for the input. If provided, the user must select one of these values.
          items:
            type: string
          example: []

    InputWithVariables:
      allOf:
        - $ref: '#/components/schemas/Input'
        - type: object
          properties:
            variables:
              type: object
              description: A map of variable names to their values. Keys in the input `value` that are wrapped in `{curly_braces}` will be replaced with the corresponding variable values.
              additionalProperties:
                $ref: '#/components/schemas/Input'

    PositionalArgument:
      description: A positional input is a value inserted verbatim into the command line.
      allOf:
        - $ref: '#/components/schemas/InputWithVariables'
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum: [positional]
              example: "positional"
            value_hint:
              type: string
              description: An identifier-like hint for the value. This is not part of the command line, but can be used by client configuration and to provide hints to users.
              example: file_path
            is_repeated:
              type: boolean
              description: Whether the argument can be repeated multiple times in the command line.
              default: false
          anyOf:
            - required:
                - value
            - required:
                - value_hint

    NamedArgument:
      description: A command-line `--flag={value}`.
      allOf:
        - $ref: '#/components/schemas/InputWithVariables'
        - type: object
          required:
            - type
            - name
          properties:
            type:
              type: string
              enum: [named]
              example: "named"
            name:
              type: string
              description: The flag name, including any leading dashes.
              example: "--port"
            is_repeated:
              type: boolean
              description: Whether the argument can be repeated multiple times.
              default: false

    KeyValueInput:
      allOf:
        - $ref: '#/components/schemas/InputWithVariables'
        - type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Name of the header or environment variable.
              example: SOME_VARIABLE

    Argument:
      anyOf:
        - $ref: '#/components/schemas/PositionalArgument'
        - $ref: '#/components/schemas/NamedArgument'

    Remote:
      type: object
      required:
        - transport_type
        - url
      properties:
        transport_type:
          type: string
          enum: [streamable, sse]
          description: Transport protocol type
          example: "sse"
        url:
          type: string
          format: uri
          description: Remote server URL
          example: "https://mcp-fs.example.com/sse"
        headers:
          type: array
          description: HTTP headers to include
          items:
            $ref: '#/components/schemas/KeyValueInput'

    ServerDetail:
      description: Schema for a static representation of an MCP server. Used in various contexts related to discovery, installation, and configuration.
      allOf:
        - $ref: '#/components/schemas/Server'
        - type: object
          properties:
            packages:
              type: array
              items:
                $ref: '#/components/schemas/Package'
            remotes:
              type: array
              items:
                $ref: '#/components/schemas/Remote'