Stacklok Sources API
The Sources API from Stacklok — 3 operation(s) for sources.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/stacklok:stacklok-sources-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
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 Registry clients V1 Sources API
version: '0.1'
tags:
- name: Sources
paths:
/v1/sources:
get:
description: List all sources
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceListResponse'
description: Sources list
'500':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Internal server error
summary: List sources
tags:
- Sources
operationId: getV1Sources
x-operation-id-source: derived
/v1/sources/{name}:
delete:
description: Delete a source by name
parameters:
- description: Source Name
in: path
name: name
required: true
schema:
type: string
responses:
'204':
description: Source deleted
'400':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Bad request
'403':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Cannot modify config-created source
'404':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Source not found
'409':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Source in use
'500':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Internal server error
summary: Delete source
tags:
- Sources
operationId: deleteV1SourcesByName
x-operation-id-source: derived
get:
description: Get a source by name
parameters:
- description: Source Name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo'
description: Source details
'400':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Bad request
'404':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Source not found
'500':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Internal server error
summary: Get source
tags:
- Sources
operationId: getV1SourcesByName
x-operation-id-source: derived
put:
description: Create a new source or update an existing one
parameters:
- description: Source Name
in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
- $ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceCreateRequest'
description: Source configuration
summary: request
description: Source configuration
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo'
description: Source updated
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo'
description: Source created
'400':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Bad request
'403':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Cannot modify config-created source
'409':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Managed source limit reached
'500':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Internal server error
summary: Create or update source
tags:
- Sources
operationId: putV1SourcesByName
x-operation-id-source: derived
/v1/sources/{name}/entries:
get:
description: List all entries for a source
parameters:
- description: Source Name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceEntriesResponse'
description: Source entries
'400':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Bad request
'404':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Source not found
'500':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Internal server error
summary: List source entries
tags:
- Sources
operationId: getV1SourcesByNameEntries
x-operation-id-source: derived
components:
schemas:
github_com_stacklok_toolhive-registry-server_internal_config.APIConfig:
description: API endpoint source
properties:
endpoint:
description: "Endpoint is the base API URL (without path)\nThe registry handler will append the appropriate paths for the MCP Registry API v0.1:\n - /v0.1/servers - List all servers\n - /v0.1/servers/{name}/versions - List server versions\n - /v0.1/servers/{name}/versions/{version} - Get specific version\nExample: \"http://my-registry-api.default.svc.cluster.local/registry\""
type: string
timeout:
description: 'Timeout is the per-request timeout for HTTP requests to the API endpoint
Accepts a Go duration string (e.g., "30s", "1m"); must be > 0 and <= 5m
Defaults to 10s if not specified
Useful for public or occasionally-slow upstreams where the default is too aggressive'
type: string
type: object
github_com_stacklok_toolhive-registry-server_internal_service.SourceEntriesResponse:
properties:
entries:
items:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceEntryInfo'
type: array
uniqueItems: false
type: object
github_com_stacklok_toolhive-registry-server_internal_config.GitAuthConfig:
description: Auth contains optional authentication for private repositories
properties:
passwordFile:
description: 'PasswordFile is the path to a file containing the Git password/token
Must be an absolute path; whitespace is trimmed from the content'
type: string
username:
description: Username is the Git username for HTTP Basic authentication
type: string
type: object
github_com_stacklok_toolhive-registry-server_internal_service.CreationType:
description: API or CONFIG
enum:
- API
- CONFIG
type: string
x-enum-varnames:
- CreationTypeAPI
- CreationTypeCONFIG
github_com_stacklok_toolhive-registry-server_internal_service.SourceSyncStatus:
properties:
attemptCount:
description: Number of sync attempts
type: integer
lastAttempt:
description: Last sync attempt
type: string
lastSyncTime:
description: Last completed sync attempt
type: string
message:
description: Status or error message
type: string
phase:
description: complete, syncing, failed
type: string
serverCount:
description: Number of servers in registry
type: integer
skillCount:
description: Number of skills in registry
type: integer
type: object
github_com_stacklok_toolhive-registry-server_internal_config.FilterConfig:
description: Filtering rules
properties:
names:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.NameFilterConfig'
tags:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.TagFilterConfig'
type: object
github_com_stacklok_toolhive-registry-server_internal_service.EntryVersionInfo:
properties:
createdAt:
type: string
description:
type: string
title:
type: string
updatedAt:
type: string
version:
type: string
type: object
github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo:
properties:
claims:
additionalProperties: {}
description: Authorization claims
type: object
createdAt:
type: string
creationType:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.CreationType'
filterConfig:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.FilterConfig'
name:
type: string
sourceConfig:
description: Type-specific source configuration
sourceType:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.SourceType'
syncSchedule:
description: Sync interval string
type: string
syncStatus:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceSyncStatus'
type:
description: MANAGED, FILE, REMOTE, KUBERNETES
type: string
updatedAt:
type: string
type: object
github_com_stacklok_toolhive-registry-server_internal_config.KubernetesConfig:
description: Kubernetes discovery source
type: object
github_com_stacklok_toolhive-registry-server_internal_config.SourceType:
description: git, api, file, managed, kubernetes
enum:
- git
- api
- file
- managed
- kubernetes
type: string
x-enum-varnames:
- SourceTypeGit
- SourceTypeAPI
- SourceTypeFile
- SourceTypeManaged
- SourceTypeKubernetes
github_com_stacklok_toolhive-registry-server_internal_config.FileConfig:
description: Local file or URL source
properties:
data:
description: 'Data is the inline registry data as a JSON string
Mutually exclusive with Path and URL - exactly one must be specified
Useful for API-created registries where the data is provided directly'
type: string
path:
description: 'Path is the path to the registry.json file on the local filesystem
Can be absolute or relative to the working directory
Mutually exclusive with URL and Data - exactly one must be specified'
type: string
timeout:
description: 'Timeout is the timeout for HTTP requests when using URL
Defaults to 30s if not specified
Only applicable when URL is set'
type: string
url:
description: 'URL is the HTTP/HTTPS URL to fetch the registry file from
Mutually exclusive with Path and Data - exactly one must be specified
HTTPS is required unless the host is localhost or THV_REGISTRY_INSECURE_URL=true'
type: string
type: object
github_com_stacklok_toolhive-registry-server_internal_config.ManagedConfig:
description: Managed registry (no sync)
type: object
github_com_stacklok_toolhive-registry-server_internal_config.GitConfig:
description: Git repository source
properties:
auth:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.GitAuthConfig'
branch:
description: Branch is the Git branch to use (mutually exclusive with Tag and Commit)
type: string
commit:
description: Commit is the Git commit SHA to use (mutually exclusive with Branch and Tag)
type: string
path:
description: Path is the path to the registry file within the repository
type: string
repository:
description: Repository is the Git repository URL (HTTP/HTTPS/SSH)
type: string
tag:
description: Tag is the Git tag to use (mutually exclusive with Branch and Commit)
type: string
type: object
github_com_stacklok_toolhive-registry-server_internal_service.SourceEntryInfo:
properties:
claims:
additionalProperties: {}
type: object
entryType:
type: string
name:
type: string
versions:
items:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.EntryVersionInfo'
type: array
uniqueItems: false
type: object
github_com_stacklok_toolhive-registry-server_internal_service.SourceListResponse:
properties:
sources:
items:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_service.SourceInfo'
type: array
uniqueItems: false
type: object
github_com_stacklok_toolhive-registry-server_internal_service.SourceCreateRequest:
properties:
api:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.APIConfig'
claims:
additionalProperties: {}
description: Authorization claims
type: object
file:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.FileConfig'
filter:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.FilterConfig'
git:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.GitConfig'
kubernetes:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.KubernetesConfig'
managed:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.ManagedConfig'
syncPolicy:
$ref: '#/components/schemas/github_com_stacklok_toolhive-registry-server_internal_config.SyncPolicyConfig'
type: object
github_com_stacklok_toolhive-registry-server_internal_config.TagFilterConfig:
properties:
exclude:
items:
type: string
type: array
uniqueItems: false
include:
items:
type: string
type: array
uniqueItems: false
type: object
github_com_stacklok_toolhive-registry-server_internal_config.SyncPolicyConfig:
description: Sync schedule configuration
properties:
interval:
type: string
type: object
github_com_stacklok_toolhive-registry-server_internal_config.NameFilterConfig:
properties:
exclude:
items:
type: string
type: array
uniqueItems: false
include:
items:
type: string
type: array
uniqueItems: false
type: object
securitySchemes:
BearerAuth:
description: 'OAuth 2.0 Bearer token authentication. Format: "Bearer {token}"'
in: header
name: Authorization
type: apiKey
externalDocs:
description: ''
url: ''