openapi.yaml

openapi: 3.1.0
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
$id: https://modelcontextprotocol.io/schemas/draft/2025-09-29/server-registry-openapi
info:
  title: MCP Server Registry API
  version: "2025-09-29"
  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

tags:
  - name: servers
    description: Operations for discovering and retrieving MCP servers
  - name: publish
    description: Operations for publishing MCP servers to the registry

paths:
  /v0/servers:
    get:
      tags: [servers]
      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.

            Cursors are opaque strings returned in the `metadata.nextCursor` field of paginated responses. Always use the exact cursor value returned by the API.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of items to return
          required: false
          schema:
            type: integer
        - name: search
          in: query
          description: Search servers by name (substring match)
          required: false
          schema:
            type: string
            example: "filesystem"
        - name: updated_since
          in: query
          description: Filter servers updated since timestamp (RFC3339 datetime)
          required: false
          schema:
            type: string
            format: date-time
            example: "2025-08-07T13:15:04.280Z"
        - name: version
          in: query
          description: Filter by version ('latest' for latest version, or an exact version like '1.2.3')
          required: false
          schema:
            type: string
            example: "1.2.3"
      responses:
        '200':
          description: A list of MCP servers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerList'
  /v0/servers/{serverName}/versions:
    get:
      tags: [servers]
      summary: List all versions of an MCP server
      description: Returns all available versions for a specific MCP server, ordered by publication date (newest first)
      parameters:
        - name: serverName
          in: path
          required: true
          description: URL-encoded server name (e.g., "com.example%2Fmy-server")
          schema:
            type: string
            example: "com.example%2Fmy-server"
      responses:
        '200':
          description: A list of all versions for the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerList'
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Server not found"
  /v0/servers/{serverName}/versions/{version}:
    get:
      tags: [servers]
      summary: Get specific MCP server version
      description: Returns detailed information about a specific version of an MCP server. Use the special version `latest` to get the latest version.
      parameters:
        - name: serverName
          in: path
          required: true
          description: URL-encoded server name (e.g., "com.example%2Fmy-server")
          schema:
            type: string
            example: "com.example%2Fmy-server"
        - name: version
          in: path
          required: true
          description: URL-encoded version to retrieve (e.g., "1.0.0" or "1.0.0%2B20130313144700" for versions with build metadata)
          schema:
            type: string
            example: "1.0.0"
      responses:
        '200':
          description: Detailed server information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerResponse'
        '404':
          description: Server or version not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Server not found"
  /v0/publish:
    post:
      tags: [publish]
      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."
                  title: "Filesystem"
                  repository:
                    url: "https://github.com/modelcontextprotocol/servers"
                    source: "github"
                  version: "1.0.2"
                  packages:
                    - registryType: "npm"
                      registryBaseUrl: "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"
                      buildInfo:
                        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."
                  title: "Demo Server"
                  repository:
                    url: "https://github.com/example/mcp-demo"
                    source: "github"
                  version: "1.0.0"
                  packages:
                    - registryType: "npm"
                      registryBaseUrl: "https://registry.npmjs.org"
                      identifier: "@example/mcp-demo-server"
                      version: "1.0.0"
                  _meta:
                    io.modelcontextprotocol.registry/publisher-provided:
                      contactEmail: "maintainer@example.com"
                      buildMetadata:
                        commit: "abc123"
                        timestamp: "2024-01-15T10:30:00Z"
                    com.example:
                      marketplaceIcon: "https://example.com/icon.png"
                      category: ["software_development"]
                      documentationUrl: "https://docs.example.org"
                      verifiedPublisher: true
      responses:
        '200':
          description: Successfully published server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerResponse'
        '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
      description: "Repository metadata for the MCP server source code. Enables users and security experts to inspect the code, improving transparency."
      required:
        - url
        - source
      properties:
        url:
          type: string
          format: uri
          description: "Repository URL for browsing source code. Should support both web browsing and git clone operations."
          example: "https://github.com/modelcontextprotocol/servers"
        source:
          type: string
          description: "Repository hosting service identifier. Used by registries to determine validation and API access methods."
          example: "github"
        id:
          type: string
          description: "Repository identifier from the hosting service (e.g., GitHub repo ID). Owned and determined by the source forge. Should remain stable across repository renames and may be used to detect repository resurrection attacks - if a repository is deleted and recreated, the ID should change. For GitHub, use: gh api repos/<owner>/<repo> --jq '.id'"
          example: "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
        subfolder:
          type: string
          description: "Optional relative path from repository root to the server location within a monorepo or nested package structure. Must be a clean relative path."
          example: "src/everything"

    ServerList:
      type: object
      required:
        - servers
      properties:
        servers:
          type: array
          items:
            $ref: '#/components/schemas/ServerResponse'
        metadata:
          type: object
          properties:
            nextCursor:
              type: string
              description: |
                Pagination cursor for retrieving the next page of results.
                Use this exact value in the `cursor` query parameter of your next request. If null or empty, there are no more results.
            count:
              type: integer
              description: Number of items in current page
              example: 30

    Package:
      type: object
      required:
        - registryType
        - identifier
        - transport
      properties:
        registryType:
          type: string
          description: Registry type indicating how to download or locate packages (e.g., 'npm', 'pypi', 'oci', 'nuget', 'mcpb', 'on_device'). The 'on_device' type represents a pre-installed server that should be launched locally and not downloaded.
          examples:
            - "npm"
            - "pypi"
            - "oci"
            - "nuget"
            - "mcpb"
            - "on_device"
        registryBaseUrl:
          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. Must be a specific version. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3', '>=1.2.3', '1.x', '1.*')."
          example: "1.0.2"
          minLength: 1
          not:
            const: "latest"
        fileSha256:
          type: string
          description: "SHA-256 hash of the package file for integrity verification. Required for MCPB packages and optional for other package types. Authors are responsible for generating correct SHA-256 hashes when creating server.json. If present, MCP clients must validate the downloaded file matches the hash before running packages to ensure file integrity."
          example: "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce"
          pattern: "^[a-f0-9]{64}$"
        runtimeHint:
          type: string
          description: A hint to help clients determine the appropriate runtime for the package. This field should be provided when `runtimeArguments` are present.
          examples: [npx, uvx, docker, dnx]
        transport:
          anyOf:
            - $ref: '#/components/schemas/StdioTransport'
            - $ref: '#/components/schemas/StreamableHttpTransport'
            - $ref: '#/components/schemas/SseTransport'
          description: Transport protocol configuration for the package
        runtimeArguments:
          type: array
          description: A list of arguments to be passed to the package's runtime command (such as docker or npx). The `runtimeHint` field should be provided when `runtimeArguments` are present.
          items:
            $ref: '#/components/schemas/Argument'
        packageArguments:
          type: array
          description: A list of arguments to be passed to the package's binary.
          items:
            $ref: '#/components/schemas/Argument'
        environmentVariables:
          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
        isRequired:
          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.\n\nWhen 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 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.
        isSecret:
          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.  This should be a valid value for the input.  If you want to provide input examples or guidance, use the `placeholder` field instead."
        placeholder:
          type: string
          description: "A placeholder for the input to be displaying during configuration. This is used to provide examples or guidance about the expected form or content of 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"
            valueHint:
              type: string
              description: "An identifier for the positional argument. It is not part of the command line. It may be used by client configuration as a label identifying the argument. It is also used to identify the value in transport URL variable substitution."
              example: file_path
            isRepeated:
              type: boolean
              description: Whether the argument can be repeated multiple times in the command line.
              default: false
          anyOf:
            - required:
                - valueHint
            - required:
                - value

    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"
            isRepeated:
              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:
      description: "Warning: Arguments construct command-line parameters that may contain user-provided input. This creates potential command injection risks if clients execute commands in a shell environment. For example, a malicious argument value like ';rm -rf ~/Development' could execute dangerous commands. Clients should prefer non-shell execution methods (e.g., posix_spawn) when possible to eliminate injection risks entirely. Where not possible, clients should obtain consent from users or agents to run the resolved command before execution."
      anyOf:
        - $ref: '#/components/schemas/PositionalArgument'
        - $ref: '#/components/schemas/NamedArgument'

    StdioTransport:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum: [stdio]
          description: Transport type
          example: "stdio"

    StreamableHttpTransport:
      type: object
      required:
        - type
        - url
      properties:
        type:
          type: string
          enum: [streamable-http]
          description: Transport type
          example: "streamable-http"
        url:
          type: string
          description: URL template for the streamable-http transport. Variables in {curly_braces} reference argument valueHints, argument names, or environment variable names. After variable substitution, this should produce a valid URI.
          example: "https://api.example.com/mcp"
        headers:
          type: array
          description: HTTP headers to include
          items:
            $ref: '#/components/schemas/KeyValueInput'

    SseTransport:
      type: object
      required:
        - type
        - url
      properties:
        type:
          type: string
          enum: [sse]
          description: Transport type
          example: "sse"
        url:
          type: string
          format: uri
          description: Server-Sent Events endpoint URL
          example: "https://mcp-fs.example.com/sse"
        headers:
          type: array
          description: HTTP headers to include
          items:
            $ref: '#/components/schemas/KeyValueInput'

    Icon:
      type: object
      description: An optionally-sized icon that can be displayed in a user interface.
      required:
        - src
      properties:
        src:
          type: string
          format: uri
          description: "A standard URI pointing to an icon resource. Must be an HTTPS URL. Consumers SHOULD take steps to ensure URLs serving icons are from the same domain as the server or a trusted domain. Consumers SHOULD take appropriate precautions when consuming SVGs as they can contain executable JavaScript."
          example: "https://example.com/icon.png"
          maxLength: 255
        mimeType:
          type: string
          description: "Optional MIME type override if the source MIME type is missing or generic. Must be one of: image/png, image/jpeg, image/jpg, image/svg+xml, image/webp."
          enum: [image/png, image/jpeg, image/jpg, image/svg+xml, image/webp]
          example: "image/png"
        sizes:
          type: array
          description: "Optional array of strings that specify sizes at which the icon can be used. Each string should be in WxH format (e.g., '48x48', '96x96') or 'any' for scalable formats like SVG. If not provided, the client should assume that the icon can be used at any size."
          items:
            type: string
            pattern: "^(\\d+x\\d+|any)$"
          examples:
            - ["48x48", "96x96"]
            - ["any"]
        theme:
          type: string
          description: "Optional specifier for the theme this icon is designed for. 'light' indicates the icon is designed to be used with a light background, and 'dark' indicates the icon is designed to be used with a dark background. If not provided, the client should assume the icon can be used with any theme."
          enum: [light, dark]

    ServerDetail:
      description: Schema for a static representation of an MCP server. Used in various contexts related to discovery, installation, and configuration.
      type: object
      required:
        - name
        - description
        - version
      properties:
        name:
          type: string
          description: "Server name in reverse-DNS format. Must contain exactly one forward slash separating namespace from server name."
          example: "io.github.user/weather"
          minLength: 3
          maxLength: 200
          pattern: "^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$"
        description:
          type: string
          description: "Clear human-readable explanation of server functionality. Should focus on capabilities, not implementation details."
          example: "MCP server providing weather data and forecasts via OpenWeatherMap API"
          minLength: 1
          maxLength: 100
        title:
          type: string
          description: "Optional human-readable title or display name for the MCP server. MCP subregistries or clients MAY choose to use this for display purposes."
          example: "Weather API"
          minLength: 1
          maxLength: 100
        repository:
          $ref: '#/components/schemas/Repository'
          description: "Optional repository metadata for the MCP server source code. Recommended for transparency and security inspection."
        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. Non-semantic versions are allowed but may not sort predictably. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3', '>=1.2.3', '1.x', '1.*')."
          maxLength: 255
        websiteUrl:
          type: string
          format: uri
          description: "Optional URL to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements."
          example: "https://modelcontextprotocol.io/examples"
        icons:
          type: array
          description: "Optional set of sized icons that the client can display in a user interface. Clients that support rendering icons MUST support at least the following MIME types: image/png and image/jpeg (safe, universal compatibility). Clients SHOULD also support: image/svg+xml (scalable but requires security precautions) and image/webp (modern, efficient format)."
          items:
            $ref: '#/components/schemas/Icon'
        $schema:
          type: string
          format: uri
          description: JSON Schema URI for this server.json format
          example: "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json"
        packages:
          type: array
          items:
            $ref: '#/components/schemas/Package'
        remotes:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/StreamableHttpTransport'
              - $ref: '#/components/schemas/SseTransport'
        _meta:
          type: object
          description: "Extension metadata using reverse DNS namespacing for vendor-specific data"
          properties:
            io.modelcontextprotocol.registry/publisher-provided:
              type: object
              description: "Publisher-provided metadata for downstream registries"
              additionalProperties: true
              example:
                tool: "publisher-cli"
                version: "1.2.3"
                buildInfo:
                  commit: "abc123def456"
                  timestamp: "2023-12-01T10:30:00Z"
                  pipelineId: "build-789"

    ServerResponse:
      description: API response format with separated server data and registry metadata
      type: object
      required:
        - server
        - _meta
      properties:
        server:
          $ref: '#/components/schemas/ServerDetail'
        _meta:
          type: object
          description: Registry-managed metadata
          properties:
            io.modelcontextprotocol.registry/official:
              type: object
              description: Official MCP registry metadata
              properties:
                status:
                  type: string
                  enum: ["active", "deprecated", "deleted"]
                  description: Server lifecycle status
                  example: "active"
                publishedAt:
                  type: string
                  format: date-time
                  description: Timestamp when the server was first published to the registry
                  example: "2023-12-01T10:30:00Z"
                updatedAt:
                  type: string
                  format: date-time
                  description: Timestamp when the server entry was last updated
                  example: "2023-12-01T11:00:00Z"
                isLatest:
                  type: boolean
                  description: Whether this is the latest version of the server
                  example: true
              additionalProperties: false
          additionalProperties: true