332 lines
9.9 KiB
YAML
332 lines
9.9 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: MCP Server Registry API
|
|
summary: API for discovering and accessing MCP servers metadata
|
|
description: |
|
|
REST API that centralizes metadata about publicly available MCP servers by allowing server creators to submit
|
|
and maintain metadata about their servers in a standardized format. This API enables MCP client
|
|
applications and "server aggregator" type consumers to discover and install MCP servers.
|
|
version: 0.0.1
|
|
contact:
|
|
name: MCP Community Working Group
|
|
license:
|
|
name: MIT
|
|
identifier: MIT
|
|
servers:
|
|
# TODO: Still think a unique name would be better; maybe we open a public discussion on the topic and let people submit ideas?
|
|
- url: https://registry.modelcontextprotocol.io
|
|
description: MCP Server Registry
|
|
# TODO: Webhooks here would be interesting, but out of scope for MVP
|
|
|
|
paths:
|
|
/v0/servers:
|
|
get:
|
|
summary: List MCP servers
|
|
description: Returns a list of all registered MCP servers
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
description: Number of results per page (maximum 5000)
|
|
schema:
|
|
type: integer
|
|
default: 5000
|
|
maximum: 5000
|
|
minimum: 1
|
|
- name: offset
|
|
in: query
|
|
description: Number of results to skip for pagination
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
minimum: 0
|
|
responses:
|
|
'200':
|
|
description: A list of MCP servers
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServerList'
|
|
/v0/servers/{id}:
|
|
get:
|
|
summary: Get MCP server details
|
|
description: Returns detailed information about a specific MCP server
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: Unique ID of the server
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: version
|
|
in: query
|
|
description: Desired MCP server version
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Detailed server information
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServerDetail'
|
|
'404':
|
|
description: Server not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Server not found"
|
|
components:
|
|
schemas:
|
|
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
|
|
Repository:
|
|
type: object
|
|
required:
|
|
- url
|
|
- source
|
|
- id
|
|
properties:
|
|
url:
|
|
type: string
|
|
format: uri
|
|
example: "https://github.com/modelcontextprotocol/servers"
|
|
source:
|
|
type: string
|
|
enum: [github, gitlab] # TODO: Add all supported sources as a whitelist
|
|
example: "github"
|
|
id:
|
|
type: string
|
|
example: "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
|
|
|
|
Server:
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- repository
|
|
- version_detail
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
example: "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1"
|
|
name:
|
|
type: string
|
|
example: "@modelcontextprotocol/servers/src/filesystem"
|
|
description:
|
|
type: string
|
|
example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
|
|
repository:
|
|
$ref: '#/components/schemas/Repository'
|
|
version_detail:
|
|
type: object
|
|
required:
|
|
- version
|
|
- release_date
|
|
- is_latest
|
|
properties:
|
|
version:
|
|
type: string
|
|
example: "1.0.2"
|
|
description: Equivalent of Implementation.version in MCP specification.
|
|
release_date:
|
|
type: string
|
|
format: date-time
|
|
example: "2023-06-15T10:30:00Z"
|
|
description: Datetime that the MCP server version was published to the registry.
|
|
is_latest:
|
|
type: boolean
|
|
example: true
|
|
description: Whether the MCP server version is the latest version available in the registry.
|
|
$schema: "https://json-schema.org/draft/2020-12/schema"
|
|
|
|
ServerList:
|
|
type: object
|
|
required:
|
|
- servers
|
|
- total_count
|
|
properties:
|
|
servers:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Server'
|
|
next:
|
|
type: string
|
|
format: uri
|
|
example: "https://registry.modelcontextprotocol.io/servers?offset=50"
|
|
total_count:
|
|
type: integer
|
|
example: 1
|
|
|
|
Package:
|
|
type: object
|
|
required:
|
|
- registry_name
|
|
- name
|
|
- version
|
|
properties:
|
|
registry_name:
|
|
type: string
|
|
enum: [npm, docker, pypi, homebrew]
|
|
example: "npm"
|
|
name:
|
|
type: string
|
|
example: "@modelcontextprotocol/server-filesystem"
|
|
version:
|
|
type: string
|
|
example: "1.0.2"
|
|
runtime_arguments:
|
|
type: array
|
|
description: List of arguments passed to the package's runtime command (such as docker or npx).
|
|
items:
|
|
$ref: '#/components/schemas/Input'
|
|
arguments:
|
|
type: array
|
|
description: List of arguments passed to the package's binary.
|
|
items:
|
|
$ref: '#/components/schemas/Input'
|
|
environment_variables:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/NamedInput'
|
|
|
|
UserInput:
|
|
type: object
|
|
properties:
|
|
description:
|
|
type: string
|
|
is_required:
|
|
type: boolean
|
|
default: false
|
|
is_repeated:
|
|
type: boolean
|
|
description: Whether the input can be repeated multiple times in the command line.
|
|
default: false
|
|
format:
|
|
type: string
|
|
description: Input format. Includes a variety of standardized formats, including `filepath`, which should be interpreted as a file on the user's filesystem.
|
|
enum: [string, number, boolean, array, filepath]
|
|
default: string
|
|
value:
|
|
type: string
|
|
description: The default value for the input. If this is not set, the user will be asked to provide a value.
|
|
is_secret:
|
|
type: boolean
|
|
description: Whether the input is a secret value (e.g., password, token). If true, clients should handle the value securely.
|
|
default: false
|
|
default:
|
|
type: string
|
|
description: The default value for the input.
|
|
choices:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: []
|
|
|
|
PositionalInput:
|
|
description: A positional input is a value inserted verbatim into the command line.
|
|
allOf:
|
|
- $ref: '#/components/schemas/UserInput'
|
|
- type: object
|
|
required:
|
|
- type
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [positional]
|
|
example: "positional"
|
|
|
|
NamedInput:
|
|
description: A command-line `--flag={value}`, named environment variable or header.
|
|
allOf:
|
|
- $ref: '#/components/schemas/UserInput'
|
|
- type: object
|
|
required:
|
|
- type
|
|
- name
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [named]
|
|
example: "named"
|
|
name:
|
|
type: string
|
|
example: "--port"
|
|
|
|
TemplateInput:
|
|
- type: object
|
|
required:
|
|
- type
|
|
- template
|
|
- name
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [template]
|
|
name:
|
|
type: string
|
|
example: mount_config
|
|
description: The name of the input, which can be used by clients as an identifier to reference the input. It is not present in the generated command line.
|
|
description:
|
|
type: string
|
|
is_required:
|
|
type: boolean
|
|
is_repeated:
|
|
type: boolean
|
|
description: Whether the input can be repeated multiple times in the command line.
|
|
template:
|
|
type: string
|
|
description: The template string that will be used to generate the value. Values wrapped in `{curly_braces}` will be replaced with the corresponding properties.
|
|
example: "--mount=type=bind,src={host_path},dst={container_path}"
|
|
properties:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/UserInput'
|
|
|
|
Input:
|
|
anyOf:
|
|
- $ref: '#/components/schemas/PositionalInput'
|
|
- $ref: '#/components/schemas/NamedInput'
|
|
- $ref: '#/components/schemas/TemplateInput'
|
|
|
|
Remote:
|
|
type: object
|
|
required:
|
|
- transport_type
|
|
- url
|
|
properties:
|
|
transport_type:
|
|
type: string
|
|
enum: [streamable, sse]
|
|
example: "sse"
|
|
url:
|
|
type: string
|
|
format: uri
|
|
example: "https://mcp-fs.example.com/sse"
|
|
headers:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/NamedInput'
|
|
|
|
ServerDetail:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Server'
|
|
- type: object
|
|
properties:
|
|
package_canonical:
|
|
type: string
|
|
enum: [npm, docker, pypi, crates]
|
|
example: "npm"
|
|
packages:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Package'
|
|
remotes:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Remote'
|