Stacklok registry API

openapi: 3.2.0
info:
  contact:
    url: https://github.com/stacklok/toolhive
  description: 'API for accessing MCP server registry data and deployed server information

    This API provides endpoints to query the MCP (Model Context Protocol) server registry,

    get information about available servers, and check the status of deployed servers.


    Authentication is required by default. Use Bearer token authentication with a valid

    OAuth/OIDC access token. The /.well-known/oauth-protected-resource endpoint provides

    OAuth discovery metadata (RFC 9728).'
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: ToolHive clients Registry API
  version: '0.1'
tags:
- name: registry
paths:
  /registry/{registryName}/v0.1/servers:
    get:
      description: Get a list of available servers from a specific registry
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: Pagination cursor for retrieving next set of results
        in: query
        name: cursor
        schema:
          type: string
      - description: Maximum number of items to return
        in: query
        name: limit
        schema:
          type: integer
      - description: Search servers by name (substring match)
        in: query
        name: search
        schema:
          type: string
      - description: Filter by version ('latest' for latest version, or an exact version like '1.2.3')
        in: query
        name: version
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v0.ServerListResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Registry not found
      security:
      - BearerAuth: []
      summary: List servers in specific registry
      tags:
      - registry
  /registry/{registryName}/v0.1/servers/{serverName}/versions:
    get:
      description: Returns all available versions for a specific MCP server from a specific registry
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: URL-encoded server name (e.g., \
        in: path
        name: serverName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v0.ServerListResponse'
          description: A list of all versions for the server
        '400':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Server not found
      security:
      - BearerAuth: []
      summary: List all versions of an MCP server in specific registry
      tags:
      - registry
  /registry/{registryName}/v0.1/servers/{serverName}/versions/{version}:
    get:
      description: 'Returns detailed information about a specific version of an MCP server from a specific registry.

        Use the special version `latest` to get the latest version.'
      parameters:
      - description: Registry name
        in: path
        name: registryName
        required: true
        schema:
          type: string
      - description: URL-encoded server name (e.g., \
        in: path
        name: serverName
        required: true
        schema:
          type: string
      - description: URL-encoded version to retrieve (e.g., \
        in: path
        name: version
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v0.ServerResponse'
          description: Detailed server information
        '400':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Server or version not found
      security:
      - BearerAuth: []
      summary: Get specific MCP server version in specific registry
      tags:
      - registry
  /api/v1beta/registry:
    get:
      description: Get a list of the current registries
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.registryListResponse'
          description: OK
      summary: List registries
      tags:
      - registry
    post:
      description: Add a new registry
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '501':
          content:
            application/json:
              schema:
                type: string
          description: Not Implemented
      summary: Add a registry
      tags:
      - registry
  /api/v1beta/registry/{name}:
    delete:
      description: Remove a specific registry
      parameters:
      - description: Registry name
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '204':
          content:
            application/json:
              schema:
                type: string
          description: No Content
        '403':
          content:
            application/json:
              schema:
                type: string
          description: Forbidden - blocked by policy
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found
      summary: Remove a registry
      tags:
      - registry
    get:
      description: Get details of a specific registry
      parameters:
      - description: Registry name
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.getRegistryResponse'
          description: OK
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found
      summary: Get a registry
      tags:
      - registry
    put:
      description: Update registry URL or local path for the default registry
      parameters:
      - description: Registry name (must be 'default')
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
              - $ref: '#/components/schemas/pkg_api_v1.UpdateRegistryRequest'
                description: Registry configuration
                summary: body
        description: Registry configuration
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.UpdateRegistryResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: string
          description: Forbidden - blocked by policy
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found
        '502':
          content:
            application/json:
              schema:
                type: string
          description: Bad Gateway - Registry validation failed
        '504':
          content:
            application/json:
              schema:
                type: string
          description: Gateway Timeout - Registry unreachable
      summary: Update registry configuration
      tags:
      - registry
  /api/v1beta/registry/{name}/refresh:
    post:
      description: Force a refresh of the server-side registry cache for the default registry
      parameters:
      - description: Registry name (must be 'default')
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Registry refreshed
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.registryErrorResponse'
          description: Registry authentication required or upstream registry unavailable
      summary: Refresh registry cache
      tags:
      - registry
  /api/v1beta/registry/{name}/servers:
    get:
      description: Get a list of servers in a specific registry
      parameters:
      - description: Registry name
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.listServersResponse'
          description: OK
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found
      summary: List servers in a registry
      tags:
      - registry
  /api/v1beta/registry/{name}/servers/{serverName}:
    get:
      description: Get details of a specific server in a registry
      parameters:
      - description: Registry name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: ImageMetadata name
        in: path
        name: serverName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pkg_api_v1.getServerResponse'
          description: OK
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found
      summary: Get a server from a registry
      tags:
      - registry
  /api/v1beta/registry/auth/login:
    post:
      description: Trigger an interactive OAuth flow to authenticate with the configured registry. Only available in serve mode.
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Authenticated successfully
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad Request - Registry OAuth not configured
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Registry login
      tags:
      - registry
  /api/v1beta/registry/auth/logout:
    post:
      description: Clear cached OAuth tokens for the configured registry. Only available in serve mode.
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Logged out successfully
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad Request - Registry OAuth not configured
        '500':
          content:
            application/json:
              schema:
                type: string
          description: Internal Server Error
      summary: Registry logout
      tags:
      - registry
components:
  schemas:
    registry.RemoteServerMetadata:
      description: Remote server details (if it's a remote server)
      properties:
        custom_metadata:
          additionalProperties: {}
          description: CustomMetadata allows for additional user-defined metadata
          type: object
        description:
          description: Description is a human-readable description of the server's purpose and functionality
          type: string
        env_vars:
          description: 'EnvVars defines environment variables that can be passed to configure the client

            These might be needed for client-side configuration when connecting to the remote server'
          items:
            $ref: '#/components/schemas/registry.EnvVar'
          type: array
          uniqueItems: false
        headers:
          description: 'Headers defines HTTP headers that can be passed to the remote server for authentication

            These are used with the thv proxy command''s authentication features'
          items:
            $ref: '#/components/schemas/registry.Header'
          type: array
          uniqueItems: false
        metadata:
          $ref: '#/components/schemas/registry.Metadata'
        name:
          description: 'Name is the identifier for the MCP server, used when referencing the server in commands

            If not provided, it will be auto-generated from the registry key'
          type: string
        oauth_config:
          $ref: '#/components/schemas/registry.OAuthConfig'
        overview:
          description: 'Overview is a longer Markdown-formatted description for web display.

            Unlike the Description field (limited to 500 chars), this supports

            full Markdown and is intended for rich rendering on catalog pages.'
          type: string
        proxy_port:
          description: 'ProxyPort is the port for the HTTP proxy to listen on (host port)

            If not specified, a random available port will be assigned'
          type: integer
        repository_url:
          description: RepositoryURL is the URL to the source code repository for the server
          type: string
        stateless:
          description: Stateless indicates the server only supports POST (no SSE/GET)
          type: boolean
        status:
          description: Status indicates whether the server is currently active or deprecated
          type: string
        tags:
          description: Tags are categorization labels for the server to aid in discovery and filtering
          items:
            type: string
          type: array
          uniqueItems: false
        tier:
          description: Tier represents the tier classification level of the server, e.g., "Official" or "Community"
          type: string
        title:
          description: 'Title is an optional human-readable display name for the server.

            If not provided, the Name field is used for display purposes.'
          type: string
        tools:
          description: Tools is a list of tool names provided by this MCP server
          items:
            type: string
          type: array
          uniqueItems: false
        transport:
          description: 'Transport defines the communication protocol for the server

            For containers: stdio, sse, or streamable-http

            For remote servers: sse or streamable-http (stdio not supported)'
          type: string
        url:
          description: URL is the endpoint URL for the remote MCP server (e.g., https://api.example.com/mcp)
          type: string
      type: object
    registry.Group:
      properties:
        description:
          description: Description is a human-readable description of the group's purpose and functionality
          type: string
        name:
          description: Name is the identifier for the group, used when referencing the group in commands
          type: string
        remote_servers:
          additionalProperties:
            $ref: '#/components/schemas/registry.RemoteServerMetadata'
          description: RemoteServers is a map of server names to their corresponding remote server definitions within this group
          type: object
        servers:
          additionalProperties:
            $ref: '#/components/schemas/registry.ImageMetadata'
          description: Servers is a map of server names to their corresponding server definitions within this group
          type: object
      type: object
    permissions.Profile:
      description: Permission profile to apply
      properties:
        name:
          description: Name is the name of the profile
          type: string
        network:
          $ref: '#/components/schemas/permissions.NetworkPermissions'
        privileged:
          description: 'Privileged indicates whether the container should run in privileged mode

            When true, the container has access to all host devices and capabilities

            Use with extreme caution as this removes most security isolation'
          type: boolean
        read:
          description: 'Read is a list of mount declarations that the container can read from

            These can be in the following formats:

            - A single path: The same path will be mounted from host to container

            - host-path:container-path: Different paths for host and container

            - resource-uri:container-path: Mount a resource identified by URI to a container path'
          items:
            type: string
          type: array
          uniqueItems: false
        write:
          description: 'Write is a list of mount declarations that the container can write to

            These follow the same format as Read mounts but with write permissions'
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    model.Transport:
      description: Transport is required and specifies the transport protocol configuration
      properties:
        headers:
          items:
            $ref: '#/components/schemas/model.KeyValueInput'
          type: array
          uniqueItems: false
        type:
          example: stdio
          type: string
        url:
          example: https://api.example.com/mcp
          type: string
        variables:
          additionalProperties:
            $ref: '#/components/schemas/model.Input'
          type: object
      type: object
    model.Package:
      properties:
        environmentVariables:
          description: EnvironmentVariables are set when running the package
          items:
            $ref: '#/components/schemas/model.KeyValueInput'
          type: array
          uniqueItems: false
        fileSha256:
          description: FileSHA256 is the SHA-256 hash for integrity verification (required for mcpb, optional for others)
          example: fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce
          pattern: ^[a-f0-9]{64}$
          type: string
        identifier:
          description: "Identifier is the package identifier:\n  - For NPM/PyPI/NuGet: package name or ID\n  - For OCI: full image reference (e.g., \"ghcr.io/owner/repo:v1.0.0\")\n  - For MCPB: direct download URL"
          example: '@modelcontextprotocol/server-brave-search'
          minLength: 1
          type: string
        packageArguments:
          description: PackageArguments are passed to the package's binary
          items:
            $ref: '#/components/schemas/model.Argument'
          type: array
          uniqueItems: false
        registryBaseUrl:
          description: RegistryBaseURL is the base URL of the package registry (used by npm, pypi, nuget, cargo; not used by oci, mcpb)
          example: https://registry.npmjs.org
          format: uri
          type: string
        registryType:
          description: RegistryType indicates how to download packages (e.g., "npm", "pypi", "cargo", "oci", "nuget", "mcpb")
          example: npm
          minLength: 1
          type: string
        runtimeArguments:
          description: RuntimeArguments are passed to the package's runtime command (e.g., docker, npx)
          items:
            $ref: '#/components/schemas/model.Argument'
          type: array
          uniqueItems: false
        runtimeHint:
          description: RunTimeHint suggests the appropriate runtime for the package
          example: npx
          type: string
        transport:
          $ref: '#/components/schemas/model.Transport'
        version:
          description: Version is the package version (required for npm, pypi, nuget; optional for mcpb; not used by oci where version is in the identifier)
          example: 1.0.2
          maxLength: 255
          minLength: 1
          type: string
      type: object
    pkg_api_v1.RegistryType:
      description: Type of registry (file, url, or default)
      enum:
      - file
      - url
      - api
      - default
      type: string
      x-enum-varnames:
      - RegistryTypeFile
      - RegistryTypeURL
      - RegistryTypeAPI
      - RegistryTypeDefault
    registry.EnvVar:
      properties:
        default:
          description: 'Default is the value to use if the environment variable is not explicitly provided

            Only used for non-required variables'
          type: string
        description:
          description: Description is a human-readable explanation of the variable's purpose
          type: string
        name:
          description: Name is the environment variable name (e.g., API_KEY)
          type: string
        required:
          description: 'Required indicates whether this environment variable must be provided

            If true and not provided via command line or secrets, the user will be prompted for a value'
          type: boolean
        secret:
          description: 'Secret indicates whether this environment variable contains sensitive information

            If true, the value will be stored as a secret rather than as a plain environment variable'
          type: boolean
      type: object
    registry.Metadata:
      description: Metadata contains additional information about the server such as popularity metrics
      properties:
        kubernetes:
          $ref: '#/components/schemas/registry.KubernetesMetadata'
        last_updated:
          description: LastUpdated is the timestamp when the server was last updated, in RFC3339 format
          type: string
        stars:
          description: Stars represents the popularity rating or number of stars for the server
          type: integer
      type: object
    registry.Header:
      properties:
        choices:
          description: Choices provides a list of valid values for the header (optional)
          items:
            type: string
          type: array
          uniqueItems: false
        default:
          description: 'Default is the value to use if the header is not explicitly provided

            Only used for non-required headers'
          type: string
        description:
          description: Description is a human-readable explanation of the header's purpose
          type: string
        name:
          description: Name is the header name (e.g., X-API-Key, Authorization)
          type: string
        required:
          description: 'Required indicates whether this header must be provided

            If true and not provided via command line or secrets, the user will be prompted for a value'
          type: boolean
        secret:
          description: 'Secret indicates whether this header contains sensitive information

            If true, the value will be stored as a secret rather than as plain text'
          type: boolean
      type: object
    model.ArgumentType:
      enum:
      - positional
      - named
      example: positional
      type: string
      x-enum-varnames:
      - ArgumentTypePositional
      - ArgumentTypeNamed
    v0.ServerListResponse:
      properties:
        metadata:
          $ref: '#/components/schemas/v0.Metadata'
        servers:
          items:
            $ref: '#/components/schemas/v0.ServerResponse'
          type: array
          uniqueItems: false
      type: object
    registry.KubernetesMetadata:
      description: 'Kubernetes contains Kubernetes-specific metadata when the MCP server is deployed in a cluster.

        This field is optional and only populated when:

        - The server is served from ToolHive Registry Server

        - The server was auto-discovered from a Kubernetes deployment

        - The Kubernetes resource has the required registry annotations'
      properties:
        image:
          description: Image is the container image used by the Kubernetes workload (applicable to MCPServer)
          type: string
        kind:
          description: Kind is the Kubernetes resource kind (e.g., MCPServer, VirtualMCPServer, MCPRemoteProxy)
          type: string
        name:
          description: Name is the Kubernetes resource name
          type: string
        namespace:
          description: Namespace is the Kubernetes namespace where the resource is deployed
          type: string
        transport:
          description: Transport is the transport type configured for the Kubernetes workload (applicable to MCPServer)
          type: string
        uid:
          description: UID is the Kubernetes resource UID
          type: string
      type: object
    registry.ImageMetadata:
      description: Container server details (if it's a container server)
      properties:
        args:
          description: 'Args are the default command-line arguments to pass to the MCP server container.

            These arguments will be used only if no command-line arguments are provided by the user.

            If the user provides arguments, they will override these defaults.'
          items:
            type: string
          type: array
          uniqueItems: false
        custom_metadata:
          additionalProperties: {}
          description: CustomMetadata allows for additional user-defined metadata
          type: object
        description:
          description: Description is a human-readable description of the server's purpose and functionality
          type: string
        docker_tags:
          description: DockerTags lists the available Docker tags for this server image
          items:
            type: string
          type: array
          uniqueItems: false
        env_vars:
          description: EnvVars defines environment variables that can be passed to the server
          items:
            $ref: '#/components/schemas/registry.EnvVar'
          type: array
          uniqueItems: false
        image:
          description: Image is the Docker image reference for the MCP server
          type: string
        metadata:
          $ref: '#/components/schemas/registry.Metadata'
        name:
          description: 'Name is the identifier for the MCP server, used when referencing the server in commands

            If not provided, it will be auto-generated from the registry key'
          type: string
        overview:
          description: 'Overview is a longer Markdown-formatted description for web display.

            Unlike the Description field (limited to 500 chars), this supports

            full Markdown and is intended for rich rendering on catalog pages.'
          type: string
        permissions:
          $ref: '#/components/schemas/permissions.Profile'
        provenance:
          $ref: '#/components/schemas/registry.Provenance'
        proxy_port:
          description: 'ProxyPort is the port for the HTTP proxy to listen on (host port)

            If not specified, a random available port will be assigned'
          type: integer
        repository_url:
          description: RepositoryURL is the URL to the source code repository for the server
          type: string
        stateless:
          description: Stateless indicates the server only supports POST (no SSE/GET)
          type: boolean
        status:
          description: Status indicates whether the server is currently active or deprecated
          type: string
        tags:
          description: Tags are categorization labels for the server to aid in discovery and filtering
          items:
            type: string
          type: array
          uniqueItems: false
        target_port:
          description: TargetPort is the port for the container to expose (only applicable to SSE and Streamable HTTP transports)
          type: integer
        tier:
          description: Tier represents the tier classification level of the server, e.g., "Official" or "Community"
          type: string
        title:
          description: 'Title is an optional human-readable display name for the server.

            If not provided, the Name field is used for display purposes.'
          type: string
        tools:
          description: Tools is a list of tool names provided by this MCP server
          items:
            type: string
          type: array
          uniqueItems: false
        transport:
          description: 'Transport defines the communication protocol for the server

            For containers: stdio, sse, or streamable-http

            For remote servers: sse or streamable-http (stdio not supported)'
          type: string
      type: object
    model.Repository:
      properties:
        id:
          example: b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9
          type: string
        source:
          example: github
          type: string
        subfolder:
          example: src/everything
          type: string
        url:
          example: https://github.com/modelcontextprotocol/servers
          format: uri
          type: string
      type: object
    permissions.InboundNetworkPermissions:
      description: Inbound defines inbound network permissions
      properties:
        allow_host:
          description: AllowHost is a list of allowed hosts for inbound connections
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    github_com_stacklok_toolhive-core_registry_types.Registry:
      description: Full registry data
      properties:
        groups:
          description: Groups is a slice of group definitions containing related MCP servers
          items:
            $ref: '#/components/schemas/registry.Group'
          type: array
          uniqueItems: false
        last_updated:
          description: LastUpdate

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stacklok/refs/heads/main/openapi/stacklok-registry-api-openapi.yml