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
    
    Argument:
      type: object
      required:
        - name
        - description
        - is_required
      properties:
        name:
          type: string
          example: "path"
        description:
          type: string
          example: "Path to access"
        is_required:
          type: boolean
          example: true
        is_repeatable:
          type: boolean
          example: false
        is_editable:
          type: boolean
          example: true
        choices:
          type: array
          items:
            type: string
          example: []
        default_value:
          type: string
          example: "/Users/username/Desktop"
    
    PositionalArgument:
      allOf:
        - $ref: '#/components/schemas/Argument'
        - type: object
          required:
            - position
          properties:
            position:
              type: integer
              example: 1
    
    NamedArgument:
      allOf:
        - $ref: '#/components/schemas/Argument'
        - type: object
          properties:
            short_flag:
              type: string
              example: "-y"
            long_flag:
              type: string
              example: "--mount"
            requires_value:
              type: boolean
              example: true
    
    Subcommand:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          example: "run"
        description:
          type: string
          example: "Run the Docker container"
        is_required:
          type: boolean
          example: true
        subcommands:
          type: array
          items:
            $ref: '#/components/schemas/Subcommand'
        positional_arguments:
          type: array
          items:
            $ref: '#/components/schemas/PositionalArgument'
        named_arguments:
          type: array
          items:
            $ref: '#/components/schemas/NamedArgument'
    
    Command:
      type: object
      properties:
        name:
          type: string
          enum: [npx, docker, pypi, uvx] # TODO: Add all supported commands as a whitelist
          example: "npx"
        subcommands:
          type: array
          items:
            $ref: '#/components/schemas/Subcommand'
        positional_arguments:
          type: array
          items:
            $ref: '#/components/schemas/PositionalArgument'
        named_arguments:
          type: array
          items:
            $ref: '#/components/schemas/NamedArgument'
    
    EnvironmentVariable:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          example: "LOG_LEVEL"
        description:
          type: string
          example: "Logging level (debug, info, warn, error)"
        required:
          type: boolean
          example: false
        default_value:
          type: string
          example: "info"
    
    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"
        command:
          $ref: '#/components/schemas/Command'
        environment_variables:
          type: array
          items:
            $ref: '#/components/schemas/EnvironmentVariable'
    
    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"
    
    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'