Official MCP Registry API

components:
  schemas:
    Argument:
      additionalProperties: false
      properties:
        choices:
          description: A list of possible values for the input. If provided, the user must select one of these values.
          items:
            type: string
          type:
            - array
            - "null"
        default:
          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.
          type: string
        description:
          description: A description of the input, which clients can use to provide context to the user.
          type: string
        format:
          description: Specifies the input format. Supported values include filepath, which should be interpreted as a file on the user's filesystem.
          enum:
            - string
            - number
            - boolean
            - filepath
          type: string
        isRepeated:
          description: Whether the argument can be repeated multiple times.
          type: boolean
        isRequired:
          description: Whether the input is required
          type: boolean
        isSecret:
          description: Indicates whether the input is a secret value (e.g., password, token). If true, clients should handle the value securely.
          type: boolean
        name:
          description: The flag name (for named arguments), including any leading dashes. Empty for positional arguments.
          examples:
            - --port
          type: string
        placeholder:
          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.
          type: string
        type:
          description: "Argument type: 'positional' or 'named'"
          examples:
            - positional
          type: string
        value:
          description: The 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.
          type: string
        valueHint:
          description: An identifier for positional arguments. Used in transport URL variable substitution.
          examples:
            - file_path
          type: string
        variables:
          additionalProperties:
            $ref: "#/components/schemas/Input"
          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.
          type: object
      required:
        - type
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: "#/components/schemas/ErrorDetail"
          type:
            - array
            - "null"
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    GitHubOIDCTokenExchangeInputBody:
      additionalProperties: false
      properties:
        oidc_token:
          description: GitHub Actions OIDC token
          type: string
      required:
        - oidc_token
      type: object
    GitHubTokenExchangeInputBody:
      additionalProperties: false
      properties:
        github_token:
          description: GitHub OAuth token
          type: string
      required:
        - github_token
      type: object
    HealthBody:
      additionalProperties: false
      properties:
        github_client_id:
          description: GitHub OAuth App Client ID
          type: string
        status:
          description: Health status
          examples:
            - ok
          type: string
      required:
        - status
      type: object
    Icon:
      additionalProperties: false
      properties:
        mimeType:
          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
          examples:
            - image/png
          type: string
        sizes:
          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
          type:
            - array
            - "null"
        src:
          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.
          examples:
            - https://example.com/icon.png
          format: uri
          maxLength: 255
          type: string
        theme:
          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
          type: string
      required:
        - src
      type: object
    Input:
      additionalProperties: false
      properties:
        choices:
          description: A list of possible values for the input. If provided, the user must select one of these values.
          items:
            type: string
          type:
            - array
            - "null"
        default:
          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.
          type: string
        description:
          description: A description of the input, which clients can use to provide context to the user.
          type: string
        format:
          description: Specifies the input format. Supported values include filepath, which should be interpreted as a file on the user's filesystem.
          enum:
            - string
            - number
            - boolean
            - filepath
          type: string
        isRequired:
          description: Whether the input is required
          type: boolean
        isSecret:
          description: Indicates whether the input is a secret value (e.g., password, token). If true, clients should handle the value securely.
          type: boolean
        placeholder:
          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.
          type: string
        value:
          description: The 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.
          type: string
      type: object
    KeyValueInput:
      additionalProperties: false
      properties:
        choices:
          description: A list of possible values for the input. If provided, the user must select one of these values.
          items:
            type: string
          type:
            - array
            - "null"
        default:
          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.
          type: string
        description:
          description: A description of the input, which clients can use to provide context to the user.
          type: string
        format:
          description: Specifies the input format. Supported values include filepath, which should be interpreted as a file on the user's filesystem.
          enum:
            - string
            - number
            - boolean
            - filepath
          type: string
        isRequired:
          description: Whether the input is required
          type: boolean
        isSecret:
          description: Indicates whether the input is a secret value (e.g., password, token). If true, clients should handle the value securely.
          type: boolean
        name:
          description: Name of the header or environment variable.
          examples:
            - SOME_VARIABLE
          type: string
        placeholder:
          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.
          type: string
        value:
          description: The 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.
          type: string
        variables:
          additionalProperties:
            $ref: "#/components/schemas/Input"
          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.
          type: object
      required:
        - name
      type: object
    Metadata:
      additionalProperties: false
      properties:
        count:
          description: Number of items in current page
          format: int64
          type: integer
        nextCursor:
          description: Pagination cursor for retrieving the next page of results. Use this exact value in the cursor query parameter of your next request.
          type: string
      required:
        - count
      type: object
    OIDCTokenExchangeInputBody:
      additionalProperties: false
      properties:
        oidc_token:
          description: OIDC ID token from any provider
          type: string
      required:
        - oidc_token
      type: object
    Package:
      additionalProperties: false
      properties:
        environmentVariables:
          description: A mapping of environment variables to be set when running the package.
          items:
            $ref: "#/components/schemas/KeyValueInput"
          type:
            - array
            - "null"
        fileSha256:
          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.
          examples:
            - fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce
          pattern: ^[a-f0-9]{64}$
          type: string
        identifier:
          description: Package identifier - either a package name (for registries) or URL (for direct downloads)
          examples:
            - "@modelcontextprotocol/server-brave-search"
          minLength: 1
          type: string
        packageArguments:
          description: A list of arguments to be passed to the package's binary.
          items:
            $ref: "#/components/schemas/Argument"
          type:
            - array
            - "null"
        registryBaseUrl:
          description: Base URL of the package registry
          examples:
            - https://registry.npmjs.org
          format: uri
          type: string
        registryType:
          description: Registry type indicating how to download packages (e.g., 'npm', 'pypi', 'cargo', 'oci', 'nuget', 'mcpb')
          examples:
            - npm
          minLength: 1
          type: string
        runtimeArguments:
          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"
          type:
            - array
            - "null"
        runtimeHint:
          description: A hint to help clients determine the appropriate runtime for the package. This field should be provided when runtimeArguments are present.
          examples:
            - npx
          type: string
        transport:
          $ref: "#/components/schemas/Transport"
          description: Transport protocol configuration for the package
        version:
          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.*').
          examples:
            - 1.0.2
          maxLength: 255
          minLength: 1
          type: string
      required:
        - registryType
        - identifier
        - transport
      type: object
    PingBody:
      additionalProperties: false
      properties:
        pong:
          description: Ping response
          examples:
            - true
          type: boolean
      required:
        - pong
      type: object
    RegistryExtensions:
      additionalProperties: false
      properties:
        isLatest:
          description: Whether this is the latest version of the server
          type: boolean
        publishedAt:
          description: Timestamp when the server was first published to the registry
          format: date-time
          type: string
        status:
          description: Server lifecycle status
          enum:
            - active
            - deprecated
            - deleted
          type: string
        statusChangedAt:
          description: Timestamp when the server status was last changed
          format: date-time
          type: string
        statusMessage:
          description: Optional message explaining status change (e.g., deprecation reason, migration guidance)
          type: string
        updatedAt:
          description: Timestamp when the server entry was last updated
          format: date-time
          type: string
      required:
        - status
        - statusChangedAt
        - publishedAt
        - isLatest
      type: object
    Repository:
      additionalProperties: false
      properties:
        id:
          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'"
          examples:
            - b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9
          type: string
        source:
          description: Repository hosting service identifier. Used by registries to determine validation and API access methods.
          examples:
            - github
          type: string
        subfolder:
          description: Optional relative path from repository root to the server location within a monorepo or nested package structure. Must be a clean relative path.
          examples:
            - src/everything
          type: string
        url:
          description: Repository URL for browsing source code. Should support both web browsing and git clone operations.
          examples:
            - https://github.com/modelcontextprotocol/servers
          format: uri
          type: string
      type: object
    ResponseMeta:
      additionalProperties: false
      properties:
        io.modelcontextprotocol.registry/official:
          $ref: "#/components/schemas/RegistryExtensions"
          description: Official MCP registry metadata
      type: object
    ServerJSON:
      additionalProperties: false
      properties:
        $schema:
          description: JSON Schema URI for this server.json format
          examples:
            - https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json
          format: uri
          minLength: 1
          type: string
        _meta:
          $ref: "#/components/schemas/ServerMeta"
          description: Extension metadata using reverse DNS namespacing for vendor-specific data
        description:
          description: Clear human-readable explanation of server functionality.
          examples:
            - MCP server providing weather data and forecasts via OpenWeatherMap API
          maxLength: 100
          minLength: 1
          type: string
        icons:
          description: Optional set of sized icons that the client can display in a user interface.
          items:
            $ref: "#/components/schemas/Icon"
          type:
            - array
            - "null"
        name:
          description: Server name in reverse-DNS format. Must contain exactly one forward slash separating namespace from server name.
          examples:
            - io.github.user/weather
          maxLength: 200
          minLength: 3
          pattern: ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$
          type: string
        packages:
          description: Array of package configurations
          items:
            $ref: "#/components/schemas/Package"
          type:
            - array
            - "null"
        remotes:
          description: Array of remote configurations
          items:
            $ref: "#/components/schemas/Transport"
          type:
            - array
            - "null"
        repository:
          $ref: "#/components/schemas/Repository"
          description: Optional repository metadata for the MCP server source code.
        title:
          description: Optional human-readable title or display name for the MCP server.
          examples:
            - Weather API
          maxLength: 100
          minLength: 1
          type: string
        version:
          description: Version string for this server. SHOULD follow semantic versioning.
          examples:
            - 1.0.2
          maxLength: 255
          minLength: 1
          type: string
        websiteUrl:
          description: Optional URL to the server's homepage, documentation, or project website.
          examples:
            - https://modelcontextprotocol.io/examples
          format: uri
          type: string
      required:
        - $schema
        - name
        - description
        - version
      type: object
    ServerListResponse:
      additionalProperties: false
      properties:
        metadata:
          $ref: "#/components/schemas/Metadata"
          description: Pagination metadata
        servers:
          description: List of server entries
          items:
            $ref: "#/components/schemas/ServerResponse"
          type:
            - array
            - "null"
      required:
        - servers
        - metadata
      type: object
    ServerMeta:
      additionalProperties: false
      properties:
        io.modelcontextprotocol.registry/publisher-provided:
          additionalProperties: {}
          description: Publisher-provided metadata for downstream registries
          type: object
      type: object
    ServerResponse:
      additionalProperties: false
      properties:
        _meta:
          $ref: "#/components/schemas/ResponseMeta"
          description: Registry-managed metadata
        server:
          $ref: "#/components/schemas/ServerJSON"
          description: Server configuration and metadata
      required:
        - server
        - _meta
      type: object
    SignatureTokenExchangeInput:
      additionalProperties: false
      properties:
        domain:
          description: Domain name
          examples:
            - example.com
          type: string
        signed_timestamp:
          description: Hex-encoded signature of timestamp
          examples:
            - abcdef1234567890
          type: string
        timestamp:
          description: RFC3339 timestamp
          examples:
            - "2023-01-01T00:00:00Z"
          type: string
      required:
        - domain
        - timestamp
        - signed_timestamp
      type: object
    TokenResponse:
      additionalProperties: false
      properties:
        expires_at:
          format: int64
          type: integer
        registry_token:
          type: string
      required:
        - registry_token
        - expires_at
      type: object
    Transport:
      additionalProperties: false
      properties:
        headers:
          description: HTTP headers for streamable-http or sse transports
          items:
            $ref: "#/components/schemas/KeyValueInput"
          type:
            - array
            - "null"
        type:
          description: Transport type (stdio, streamable-http, or sse)
          examples:
            - stdio
          type: string
        url:
          description: URL for streamable-http or sse transports
          examples:
            - https://api.example.com/mcp
          type: string
        variables:
          additionalProperties:
            $ref: "#/components/schemas/Input"
          description: Variables for URL templating in remote transports
          type: object
      required:
        - type
      type: object
    UpdateAllVersionsStatusResponse:
      additionalProperties: false
      properties:
        servers:
          description: List of all updated server versions
          items:
            $ref: "#/components/schemas/ServerResponse"
          type:
            - array
            - "null"
        updatedCount:
          description: Number of versions updated
          format: int64
          type: integer
      required:
        - updatedCount
        - servers
      type: object
    UpdateServerStatusBody:
      additionalProperties: false
      properties:
        status:
          description: New server lifecycle status
          enum:
            - active
            - deprecated
            - deleted
          type: string
        statusMessage:
          description: Optional message explaining the status change (e.g., reason for deprecation)
          maxLength: 500
          type: string
      required:
        - status
      type: object
    ValidationIssue:
      additionalProperties: false
      properties:
        message:
          type: string
        path:
          type: string
        reference:
          type: string
        severity:
          type: string
        type:
          type: string
      required:
        - type
        - path
        - message
        - severity
        - reference
      type: object
    ValidationResult:
      additionalProperties: false
      properties:
        issues:
          items:
            $ref: "#/components/schemas/ValidationIssue"
          type:
            - array
            - "null"
        valid:
          type: boolean
      required:
        - valid
        - issues
      type: object
    VersionBody:
      additionalProperties: false
      properties:
        build_time:
          description: Build timestamp
          examples:
            - "2025-10-14T12:00:00Z"
          type: string
        git_commit:
          description: Git commit SHA
          examples:
            - abc123d
          type: string
        version:
          description: Application version
          examples:
            - v1.0.0
          type: string
      required:
        - version
        - git_commit
        - build_time
      type: object
info:
  description: |-
    A community driven registry service for Model Context Protocol (MCP) servers.

    [GitHub repository](https://github.com/modelcontextprotocol/registry) | [Documentation](https://github.com/modelcontextprotocol/registry/tree/main/docs)
  title: Official MCP Registry
  version: 1.0.0
openapi: 3.1.0
paths:
  /v0.1/auth/dns:
    post:
      description: Authenticate using DNS TXT record public key and signed timestamp
      operationId: exchange-dns-token-v0.1
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignatureTokenExchangeInput"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      summary: Exchange DNS signature for Registry JWT
      tags:
        - auth
  /v0.1/auth/github-at:
    post:
      description: Exchange a GitHub OAuth access token for a short-lived Registry JWT token
      operationId: exchange-github-token-v0.1
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GitHubTokenExchangeInputBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      summary: Exchange GitHub OAuth access token for Registry JWT
      tags:
        - auth
  /v0.1/auth/github-oidc:
    post:
      description: Exchange a GitHub Actions OIDC token for a short-lived Registry JWT token
      operationId: exchange-github-oidc-token-v0.1
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GitHubOIDCTokenExchangeInputBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      summary: Exchange GitHub OIDC token for Registry JWT
      tags:
        - auth
  /v0.1/auth/http:
    post:
      description: Authenticate using HTTP-hosted public key and signed timestamp
      operationId: exchange-http-token-v0.1
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignatureTokenExchangeInput"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      summary: Exchange HTTP signature for Registry JWT
      tags:
        - auth
  /v0.1/auth/oidc:
    post:
      description: Exchange an OIDC ID token from any configured provider for a short-lived Registry JWT token
      operationId: exchange-oidc-token-v0.1
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OIDCTokenExchangeInputBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      summary: Exchange OIDC ID token for Registry JWT
      tags:
        - auth
  /v0.1/health:
    get:
      description: Check the health status of the API
      operationId: get-health-v0.1
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthBody"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      summary: Health check
      tags:
        - health
  /v0.1/ping:
    get:
      description: Simple ping endpoint
      operationId: ping-v0.1
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PingBody"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      summary: Ping
      tags:
        - ping
  /v0.1/publish:
    post:
      description: Publish a new MCP server to the registry or update an existing one
      operationId: publish-server-v0.1
      parameters:
        - description: Registry JWT token (obtained from /v0/auth/token/github)
          in: header
          name: Authorization
          required: true
          schema:
            description: Registry JWT token (obtained from /v0/auth/token/github)
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServerJSON"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerResponse"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      security:
        - bearer: []
      summary: Publish MCP server
      tags:
        - publish
  /v0.1/servers:
    get:
      description: Get a paginated list of MCP servers from the registry
      operationId: list-servers-v0.1
      parameters:
        - description: Pagination cursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Pagination cursor
            examples:
              - server-cursor-123
            type: string
        - description: Number of items per page
          explode: false
          in: query
          name: limit
          schema:
            default: 30
            description: Number of items per page
            examples:
              - 50
            format: int64
            maximum: 100
            minimum: 1
            type: integer
        - description: Filter servers updated since timestamp (RFC3339 datetime)
          explode: false
          in: query
          name: updated_since
          schema:
            description: Filter servers updated since timestamp (RFC3339 datetime)
            examples:
              - "2025-08-07T13:15:04.

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/agentic-ai-foundation/refs/heads/main/openapi/agentic-ai-foundation-mcp-registry-openapi.yaml