openapi: 3.1.0
info:
  title: MCP Server Registry API
  summary: API for discovering and accessing MCP servers metadata
  description: |
    REST API that centralizes metadata about publicly available MCP servers by allowing server creators to submit
    and maintain metadata about their servers in a standardized format. This API enables MCP client
    applications and "server aggregator" type consumers to discover and install MCP servers.
  version: 0.0.1
  contact:
    name: MCP Community Working Group
  license:
    name: MIT
    identifier: MIT
servers:
  # TODO: Still think a unique name would be better; maybe we open a public discussion on the topic and let people submit ideas?
  - url: https://registry.modelcontextprotocol.io
    description: MCP Server Registry
# TODO: Webhooks here would be interesting, but out of scope for MVP

paths:
  /v0/servers:
    get:
      summary: List MCP servers
      description: Returns a list of all registered MCP servers
      parameters:
        - name: limit
          in: query
          description: Number of results per page (maximum 5000)
          schema:
            type: integer
            default: 5000
            maximum: 5000
            minimum: 1
        - name: offset
          in: query
          description: Number of results to skip for pagination
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        '200':
          description: A list of MCP servers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerList'
  /v0/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:
    jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
    Repository:
      type: object
      required:
        - url
        - source
        - id
      properties:
        url:
          type: string
          format: uri
          example: "https://github.com/modelcontextprotocol/servers"
        source:
          type: string
          enum: [github, gitlab] # TODO: Add all supported sources as a whitelist
          example: "github"
        id:
          type: string
          example: "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"

    Server:
      type: object
      required:
        - id
        - name
        - description
        - repository
        - version_detail
      properties:
        id:
          type: string
          format: uuid
          example: "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1"
        name:
          type: string
          example: "@modelcontextprotocol/servers/src/filesystem"
        description:
          type: string
          example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
        repository:
          $ref: '#/components/schemas/Repository'
        version_detail:
          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.
      $schema: "https://json-schema.org/draft/2020-12/schema"

    ServerList:
      type: object
      required:
        - servers
        - total_count
      properties:
        servers:
          type: array
          items:
            $ref: '#/components/schemas/Server'
        next:
          type: string
          format: uri
          example: "https://registry.modelcontextprotocol.io/servers?offset=50"
        total_count:
          type: integer
          example: 1

    Package:
      type: object
      required:
        - registry_name
        - name
        - version
      properties:
        registry_name:
          type: string
          enum: [npm, docker, pypi, homebrew]
          example: "npm"
        name:
          type: string
          example: "@modelcontextprotocol/server-filesystem"
        version:
          type: string
          example: "1.0.2"
        runtime_arguments:
          type: array
          description: List of arguments passed to the package's runtime command (such as docker or npx).
          items:
            $ref: '#/components/schemas/Input'
        package_arguments:
          type: array
          description: List of arguments passed to the package's binary.
          items:
            $ref: '#/components/schemas/Input'
        environment_variables:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/NamedInput'
              - $ref: '#/components/schemas/TemplateInput'

    UserInput:
      type: object
      properties:
        description:
          description: A description of the input, which can be used by clients to provide context to the user.
          type: string
        is_required:
          type: boolean
          default: false
        is_repeated:
          type: boolean
          description: Whether the input can be repeated multiple times in the command line.
          default: false
        format:
          type: string
          description: Input format. Includes a variety of standardized formats, including `filepath`, which should be interpreted as a file on the user's filesystem.
          enum: [string, number, boolean, array, filepath]
          default: string
        value:
          type: string
          description: The default value for the input. If this is not set, the user will be asked to provide a value.
        is_secret:
          type: boolean
          description: 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 given, the user must pick one of these values.
          items:
            type: string
          example: []

    PositionalInput:
      description: A positional input is a value inserted verbatim into the command line.
      allOf:
        - $ref: '#/components/schemas/UserInput'
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum: [positional]
              example: "positional"

    NamedInput:
      description: A command-line `--flag={value}`, named environment variable or header.
      allOf:
        - $ref: '#/components/schemas/UserInput'
        - type: object
          required:
            - type
            - name
          properties:
            type:
              type: string
              enum: [named]
              example: "named"
            name:
              type: string
              example: "--port"

    TemplateInput:
      - type: object
        required:
          - type
          - template
          - name
        properties:
          type:
            type: string
            enum: [template]
          name:
            type: string
            example: mount_config
            description: The name of the input, which can be used by clients as an identifier to reference the input. For environment variables and headers, this is the environment variable or header names. For arguments, this is solely for reference and not part of the command line.
          description:
            description: A description of the input, which can be used by clients to provide context to the user.
            type: string
          is_required:
            type: boolean
          is_repeated:
            type: boolean
            description: Whether the input can be repeated multiple times in the command line.
          template:
            type: string
            description: The template string that will be used to generate the value. Values wrapped in `{curly_braces}` will be replaced with the corresponding properties. Input which is not `is_required` is replaced with its `default` value, or otherwise an empty string.
            example: "--mount=type=bind,src={host_path},dst={container_path}"
          properties:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/UserInput'

    Input:
      anyOf:
        - $ref: '#/components/schemas/PositionalInput'
        - $ref: '#/components/schemas/NamedInput'
        - $ref: '#/components/schemas/TemplateInput'

    Remote:
      type: object
      required:
        - transport_type
        - url
      properties:
        transport_type:
          type: string
          enum: [streamable, sse]
          example: "sse"
        url:
          type: string
          format: uri
          example: "https://mcp-fs.example.com/sse"
        headers:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/NamedInput'
              - $ref: '#/components/schemas/TemplateInput'

    ServerDetail:
      allOf:
        - $ref: '#/components/schemas/Server'
        - type: object
          properties:
            package_canonical:
              type: string
              enum: [npm, docker, pypi, crates]
              example: "npm"
            packages:
              type: array
              items:
                $ref: '#/components/schemas/Package'
            remotes:
              type: array
              items:
                $ref: '#/components/schemas/Remote'