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
  version: "2025-07-09"
  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:
  /v0/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'
  /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"
  /v0/publish:
    post:
      summary: Publish MCP server (Optional)
      description: |
        Publish a new MCP server to the registry or update an existing one.
        
        **Note**: This endpoint is optional for registry implementations. Read-only registries may not provide this functionality.
        
        Authentication mechanism is registry-specific and may vary between implementations.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServerDetail'
            examples:
              basic_server:
                summary: Basic server with NPM package
                value:
                  name: "io.modelcontextprotocol/filesystem"
                  description: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
                  status: "active"
                  repository:
                    url: "https://github.com/modelcontextprotocol/servers"
                    source: "github"
                  version: "1.0.2"
                  packages:
                    - registry_type: "npm"
                      registry_base_url: "https://registry.npmjs.org"
                      identifier: "@modelcontextprotocol/server-filesystem"
                      version: "1.0.2"
                  _meta:
                    io.modelcontextprotocol.registry/publisher-provided:
                      tool: "publisher-cli"
                      version: "1.2.3"
                      build_info:
                        commit: "abc123def456"
                        timestamp: "2023-12-01T10:30:00Z"
              example_org_server:
                summary: Server with example.com organization extensions
                value:
                  name: "com.example/demo-server"
                  description: "Example MCP server demonstrating publisher extensions."
                  status: "active"
                  repository:
                    url: "https://github.com/example/mcp-demo"
                    source: "github"
                  version: "1.0.0"
                  packages:
                    - registry_type: "npm"
                      registry_base_url: "https://registry.npmjs.org"
                      identifier: "@example/mcp-demo-server"
                      version: "1.0.0"
                  _meta:
                    io.modelcontextprotocol.registry/publisher-provided:
                      contact_email: "maintainer@example.com"
                      build_metadata:
                        commit: "abc123"
                        timestamp: "2024-01-15T10:30:00Z"
                    com.example:
                      marketplace_icon: "https://example.com/icon.png"
                      category: ["software_development"]
                      documentation_url: "https://docs.example.org"
                      verified_publisher: true
      responses:
        '200':
          description: Successfully published server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerDetail'
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Invalid or expired Registry JWT token"
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "You do not have permission to publish this server"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Failed to publish server"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Registry-specific authentication token. The authentication mechanism and token format may vary between registry implementations.
        
        Some registries may use JWT tokens, others may use API keys or OAuth. Consult your specific registry's authentication documentation.
  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"
        subfolder:
          type: string
          description: "Optional relative path from repository root to the server location within a monorepo structure"
          example: "src/everything"

    Server:
      type: object
      required:
        - name
        - description
        - version
      properties:
        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:
          type: string
          example: "1.0.2"
          description: "Version string for this server. SHOULD follow semantic versioning (e.g., '1.0.2', '2.1.0-alpha'). Equivalent of Implementation.version in MCP specification."
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time


    ServerList:
      type: object
      required:
        - servers
      properties:
        servers:
          type: array
          items:
            $ref: '#/components/schemas/ServerDetail'
        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
      properties:
        registry_type:
          type: string
          description: Registry type indicating how to download packages (e.g., 'npm', 'pypi', 'oci', 'nuget', 'mcpb')
          examples:
            - "npm"
            - "pypi"
            - "oci"
            - "nuget"
            - "mcpb"
        registry_base_url:
          type: string
          format: uri
          description: Base URL of the package registry
          examples:
            - "https://registry.npmjs.org"
            - "https://pypi.org"
            - "https://docker.io"
            - "https://api.nuget.org"
            - "https://github.com"
            - "https://gitlab.com"
        identifier:
          type: string
          description: Package identifier - either a package name (for registries) or URL (for direct downloads)
          examples:
            - "@modelcontextprotocol/server-brave-search"
            - "https://github.com/example/releases/download/v1.0.0/package.mcpb"
        version:
          type: string
          description: Package version
          example: "1.0.2"
        file_sha256:
          type: string
          description: SHA-256 hash of the package file for integrity verification.
          example: "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce"
        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:
            $schema:
              type: string
              format: uri
              description: JSON Schema URI for this server.json format
              example: "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json"
            packages:
              type: array
              items:
                $ref: '#/components/schemas/Package'
            remotes:
              type: array
              items:
                $ref: '#/components/schemas/Remote'
            _meta:
              type: object
              description: Extension metadata using reverse DNS namespacing
              properties:
                io.modelcontextprotocol.registry/publisher-provided:
                  type: object
                  description: Publisher-specific metadata and build information
                  additionalProperties: true
                  example:
                    tool: "publisher-cli"
                    version: "1.2.3"
                    build_info:
                      commit: "abc123def456"
                      timestamp: "2023-12-01T10:30:00Z"
                      pipeline_id: "build-789"
                io.modelcontextprotocol.registry/official:
                  type: object
                  description: Registry-specific metadata managed by the MCP registry system
                  required:
                    - id
                    - published_at
                    - updated_at
                    - is_latest
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: Unique registry identifier for this server entry
                      example: "550e8400-e29b-41d4-a716-446655440000"
                    published_at:
                      type: string
                      format: date-time
                      description: Timestamp when the server was first published to the registry
                      example: "2023-12-01T10:30:00Z"
                    updated_at:
                      type: string
                      format: date-time
                      description: Timestamp when the server entry was last updated
                      example: "2023-12-01T11:00:00Z"
                    is_latest:
                      type: boolean
                      description: Whether this is the latest version of the server
                      example: true
                  additionalProperties: false
              additionalProperties: true