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_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]
        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.

            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
            - value_hint
          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

    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]
          example: "sse"
        url:
          type: string
          format: uri
          example: "https://mcp-fs.example.com/sse"
        headers:
          type: array
          items:
            $ref: '#/components/schemas/KeyValueInput'

    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'