339 lines
11 KiB
YAML
339 lines
11 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:
|
|
anyOf:
|
|
- $ref: '#/components/schemas/NamedInput'
|
|
- $ref: '#/components/schemas/TemplateInput'
|
|
|
|
UserInput:
|
|
type: object
|
|
properties:
|
|
description:
|
|
description: A description of the input, which can be used by clients to provide context to the user.
|
|
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
|
|
description: A list of possible values for the input. If given, the user must pick one of these values.
|
|
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. For environment variables and headers, this is the environment variable or header names. For arguments, this is solely for reference and not part of the command line.
|
|
description:
|
|
description: A description of the input, which can be used by clients to provide context to the user.
|
|
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. Input which is not `is_required` is replaced with its `default` value, or otherwise an empty string.
|
|
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:
|
|
anyOf:
|
|
- $ref: '#/components/schemas/NamedInput'
|
|
- $ref: '#/components/schemas/TemplateInput'
|
|
|
|
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'
|