17eb56d4c7Adds optional website_url field to the server.json schema allowing publishers to provide a url to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements. Issue: #183 PR: #130 Discussion: #274 ## Motivation and Context This change addresses the need identified in #130, #183 and #274 for a standardized way to direct users to an official landing page similar to `homepage` used in NPM ([example](https://www.npmjs.com/package/@modelcontextprotocol/sdk)). It is also serves as a viable option for MCP Servers that don't follow typical package manager patterns (e.g., embedded in a Desktop app). ## How Has This Been Tested? - Schema validation: All 13 example server.json files validate successfully against the updated schema - Go validator tests: Added additional test cases covering URL format validation and namespace matching - Run all checks: Updated example files to work with anonymous publishing and verified `make check` passes ## Breaking Changes None. The website_url field is optional and backward compatible with existing server.json files. ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [x] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update ## Checklist - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [x] I have added appropriate error handling - [x] I have added or updated documentation as needed ## Additional context Security considerations: - Website URL validation enforces that the domain matches the publisher's reverse-DNS namespace - HTTP/HTTPS protocols are required (no file:// or other schemes) - Validation is consistent with existing remote URL validation patterns
524 lines
19 KiB
YAML
524 lines
19 KiB
YAML
openapi: 3.1.0
|
|
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
|
|
$id: https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi
|
|
info:
|
|
title: MCP Server Registry API
|
|
version: "2025-07-09"
|
|
summary: API for discovering and accessing MCP server metadata
|
|
description: |
|
|
Specification for a theoretical REST API that serves up metadata about MCP servers.
|
|
license:
|
|
name: MIT
|
|
identifier: MIT
|
|
|
|
paths:
|
|
/v0/servers:
|
|
get:
|
|
summary: List MCP servers
|
|
description: Returns a list of all registered MCP servers
|
|
parameters:
|
|
- name: cursor
|
|
in: query
|
|
description: Pagination cursor for retrieving next set of results
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: limit
|
|
in: query
|
|
description: Maximum number of items to return
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
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"
|
|
/v0/publish:
|
|
post:
|
|
summary: Publish MCP server (Optional)
|
|
description: |
|
|
Publish a new MCP server to the registry or update an existing one.
|
|
|
|
**Note**: This endpoint is optional for registry implementations. Read-only registries may not provide this functionality.
|
|
|
|
Authentication mechanism is registry-specific and may vary between implementations.
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServerDetail'
|
|
examples:
|
|
basic_server:
|
|
summary: Basic server with NPM package
|
|
value:
|
|
name: "io.modelcontextprotocol/filesystem"
|
|
description: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
|
|
status: "active"
|
|
repository:
|
|
url: "https://github.com/modelcontextprotocol/servers"
|
|
source: "github"
|
|
version: "1.0.2"
|
|
packages:
|
|
- registry_type: "npm"
|
|
registry_base_url: "https://registry.npmjs.org"
|
|
identifier: "@modelcontextprotocol/server-filesystem"
|
|
version: "1.0.2"
|
|
_meta:
|
|
io.modelcontextprotocol.registry/publisher-provided:
|
|
tool: "publisher-cli"
|
|
version: "1.2.3"
|
|
build_info:
|
|
commit: "abc123def456"
|
|
timestamp: "2023-12-01T10:30:00Z"
|
|
example_org_server:
|
|
summary: Server with example.com organization extensions
|
|
value:
|
|
name: "com.example/demo-server"
|
|
description: "Example MCP server demonstrating publisher extensions."
|
|
status: "active"
|
|
repository:
|
|
url: "https://github.com/example/mcp-demo"
|
|
source: "github"
|
|
version: "1.0.0"
|
|
packages:
|
|
- registry_type: "npm"
|
|
registry_base_url: "https://registry.npmjs.org"
|
|
identifier: "@example/mcp-demo-server"
|
|
version: "1.0.0"
|
|
_meta:
|
|
io.modelcontextprotocol.registry/publisher-provided:
|
|
contact_email: "maintainer@example.com"
|
|
build_metadata:
|
|
commit: "abc123"
|
|
timestamp: "2024-01-15T10:30:00Z"
|
|
com.example:
|
|
marketplace_icon: "https://example.com/icon.png"
|
|
category: ["software_development"]
|
|
documentation_url: "https://docs.example.org"
|
|
verified_publisher: true
|
|
responses:
|
|
'200':
|
|
description: Successfully published server
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ServerDetail'
|
|
'401':
|
|
description: Unauthorized - Invalid or missing authentication token
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Invalid or expired Registry JWT token"
|
|
'403':
|
|
description: Forbidden - Insufficient permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "You do not have permission to publish this server"
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: "Failed to publish server"
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
Registry-specific authentication token. The authentication mechanism and token format may vary between registry implementations.
|
|
|
|
Some registries may use JWT tokens, others may use API keys or OAuth. Consult your specific registry's authentication documentation.
|
|
schemas:
|
|
Repository:
|
|
type: object
|
|
required:
|
|
- url
|
|
- source
|
|
- id
|
|
properties:
|
|
url:
|
|
type: string
|
|
format: uri
|
|
example: "https://github.com/modelcontextprotocol/servers"
|
|
source:
|
|
type: string
|
|
example: "github"
|
|
id:
|
|
type: string
|
|
example: "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
|
|
subfolder:
|
|
type: string
|
|
description: "Optional relative path from repository root to the server location within a monorepo structure"
|
|
example: "src/everything"
|
|
|
|
Server:
|
|
type: object
|
|
required:
|
|
- name
|
|
- description
|
|
- version
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: "Reverse DNS name of the MCP server"
|
|
example: "io.github.modelcontextprotocol/filesystem"
|
|
description:
|
|
type: string
|
|
description: "Human-readable description of the server's functionality"
|
|
example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
|
|
status:
|
|
type: string
|
|
enum: [active, deprecated]
|
|
default: active
|
|
description: "Server lifecycle status. 'deprecated' indicates the server is no longer recommended for new usage."
|
|
example: "active"
|
|
repository:
|
|
$ref: '#/components/schemas/Repository'
|
|
version:
|
|
type: string
|
|
example: "1.0.2"
|
|
description: "Version string for this server. SHOULD follow semantic versioning (e.g., '1.0.2', '2.1.0-alpha'). Equivalent of Implementation.version in MCP specification."
|
|
website_url:
|
|
type: string
|
|
format: uri
|
|
description: "Optional URL to the server's homepage, documentation, or project website. This provides a central link for users to learn more about the server. Particularly useful when the server has custom installation instructions or setup requirements."
|
|
example: "https://modelcontextprotocol.io/examples"
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
|
|
ServerList:
|
|
type: object
|
|
required:
|
|
- servers
|
|
properties:
|
|
servers:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ServerDetail'
|
|
metadata:
|
|
type: object
|
|
properties:
|
|
next_cursor:
|
|
type: string
|
|
description: Cursor for next page of results
|
|
count:
|
|
type: integer
|
|
description: Number of items in current page
|
|
example: 30
|
|
|
|
Package:
|
|
type: object
|
|
properties:
|
|
registry_type:
|
|
type: string
|
|
description: Registry type indicating how to download packages (e.g., 'npm', 'pypi', 'oci', 'nuget', 'mcpb')
|
|
examples:
|
|
- "npm"
|
|
- "pypi"
|
|
- "oci"
|
|
- "nuget"
|
|
- "mcpb"
|
|
registry_base_url:
|
|
type: string
|
|
format: uri
|
|
description: Base URL of the package registry
|
|
examples:
|
|
- "https://registry.npmjs.org"
|
|
- "https://pypi.org"
|
|
- "https://docker.io"
|
|
- "https://api.nuget.org"
|
|
- "https://github.com"
|
|
- "https://gitlab.com"
|
|
identifier:
|
|
type: string
|
|
description: Package identifier - either a package name (for registries) or URL (for direct downloads)
|
|
examples:
|
|
- "@modelcontextprotocol/server-brave-search"
|
|
- "https://github.com/example/releases/download/v1.0.0/package.mcpb"
|
|
version:
|
|
type: string
|
|
description: Package version
|
|
example: "1.0.2"
|
|
file_sha256:
|
|
type: string
|
|
description: SHA-256 hash of the package file for integrity verification.
|
|
example: "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce"
|
|
runtime_hint:
|
|
type: string
|
|
description: A hint to help clients determine the appropriate runtime for the package. This field should be provided when `runtime_arguments` are present.
|
|
examples: [npx, uvx, dnx]
|
|
runtime_arguments:
|
|
type: array
|
|
description: A list of arguments to be passed to the package's runtime command (such as docker or npx). The `runtime_hint` field should be provided when `runtime_arguments` are present.
|
|
items:
|
|
$ref: '#/components/schemas/Argument'
|
|
package_arguments:
|
|
type: array
|
|
description: A list of arguments to be passed to the package's binary.
|
|
items:
|
|
$ref: '#/components/schemas/Argument'
|
|
environment_variables:
|
|
type: array
|
|
description: A mapping of environment variables to be set when running the package.
|
|
items:
|
|
$ref: '#/components/schemas/KeyValueInput'
|
|
|
|
Input:
|
|
type: object
|
|
properties:
|
|
description:
|
|
description: A description of the input, which clients can use to provide context to the user.
|
|
type: string
|
|
is_required:
|
|
type: boolean
|
|
default: false
|
|
format:
|
|
type: string
|
|
description: |
|
|
Specifies the input format. Supported values include `filepath`, which should be interpreted as a file on the user's filesystem.
|
|
|
|
When the input is converted to a string, booleans should be represented by the strings "true" and "false", and numbers should be represented as decimal values.
|
|
enum: [string, number, boolean, filepath]
|
|
default: string
|
|
value:
|
|
type: string
|
|
description: |
|
|
The default value for the input. If this is not set, the user may be prompted to provide a value. If a value is set, it should not be configurable by end users.
|
|
|
|
Identifiers wrapped in `{curly_braces}` will be replaced with the corresponding properties from the input `variables` map. If an identifier in braces is not found in `variables`, or if `variables` is not provided, the `{curly_braces}` substring should remain unchanged.
|
|
is_secret:
|
|
type: boolean
|
|
description: Indicates 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 provided, the user must select one of these values.
|
|
items:
|
|
type: string
|
|
example: []
|
|
|
|
InputWithVariables:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Input'
|
|
- type: object
|
|
properties:
|
|
variables:
|
|
type: object
|
|
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.
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/Input'
|
|
|
|
PositionalArgument:
|
|
description: A positional input is a value inserted verbatim into the command line.
|
|
allOf:
|
|
- $ref: '#/components/schemas/InputWithVariables'
|
|
- type: object
|
|
required:
|
|
- type
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [positional]
|
|
example: "positional"
|
|
value_hint:
|
|
type: string
|
|
description: An identifier-like hint for the value. This is not part of the command line, but can be used by client configuration and to provide hints to users.
|
|
example: file_path
|
|
is_repeated:
|
|
type: boolean
|
|
description: Whether the argument can be repeated multiple times in the command line.
|
|
default: false
|
|
anyOf:
|
|
- required:
|
|
- value
|
|
- required:
|
|
- value_hint
|
|
|
|
NamedArgument:
|
|
description: A command-line `--flag={value}`.
|
|
allOf:
|
|
- $ref: '#/components/schemas/InputWithVariables'
|
|
- type: object
|
|
required:
|
|
- type
|
|
- name
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [named]
|
|
example: "named"
|
|
name:
|
|
type: string
|
|
description: The flag name, including any leading dashes.
|
|
example: "--port"
|
|
is_repeated:
|
|
type: boolean
|
|
description: Whether the argument can be repeated multiple times.
|
|
default: false
|
|
|
|
KeyValueInput:
|
|
allOf:
|
|
- $ref: '#/components/schemas/InputWithVariables'
|
|
- type: object
|
|
required:
|
|
- name
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Name of the header or environment variable.
|
|
example: SOME_VARIABLE
|
|
|
|
Argument:
|
|
anyOf:
|
|
- $ref: '#/components/schemas/PositionalArgument'
|
|
- $ref: '#/components/schemas/NamedArgument'
|
|
|
|
Remote:
|
|
type: object
|
|
required:
|
|
- transport_type
|
|
- url
|
|
properties:
|
|
transport_type:
|
|
type: string
|
|
enum: [streamable, sse]
|
|
description: Transport protocol type
|
|
example: "sse"
|
|
url:
|
|
type: string
|
|
format: uri
|
|
description: Remote server URL
|
|
example: "https://mcp-fs.example.com/sse"
|
|
headers:
|
|
type: array
|
|
description: HTTP headers to include
|
|
items:
|
|
$ref: '#/components/schemas/KeyValueInput'
|
|
|
|
ServerDetail:
|
|
description: Schema for a static representation of an MCP server. Used in various contexts related to discovery, installation, and configuration.
|
|
allOf:
|
|
- $ref: '#/components/schemas/Server'
|
|
- type: object
|
|
properties:
|
|
$schema:
|
|
type: string
|
|
format: uri
|
|
description: JSON Schema URI for this server.json format
|
|
example: "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json"
|
|
packages:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Package'
|
|
remotes:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Remote'
|
|
_meta:
|
|
type: object
|
|
description: Extension metadata using reverse DNS namespacing
|
|
properties:
|
|
io.modelcontextprotocol.registry/publisher-provided:
|
|
type: object
|
|
description: Publisher-specific metadata and build information
|
|
additionalProperties: true
|
|
example:
|
|
tool: "publisher-cli"
|
|
version: "1.2.3"
|
|
build_info:
|
|
commit: "abc123def456"
|
|
timestamp: "2023-12-01T10:30:00Z"
|
|
pipeline_id: "build-789"
|
|
io.modelcontextprotocol.registry/official:
|
|
type: object
|
|
description: Registry-specific metadata managed by the MCP registry system
|
|
required:
|
|
- id
|
|
- published_at
|
|
- updated_at
|
|
- is_latest
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique registry identifier for this server entry
|
|
example: "550e8400-e29b-41d4-a716-446655440000"
|
|
published_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the server was first published to the registry
|
|
example: "2023-12-01T10:30:00Z"
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the server entry was last updated
|
|
example: "2023-12-01T11:00:00Z"
|
|
is_latest:
|
|
type: boolean
|
|
description: Whether this is the latest version of the server
|
|
example: true
|
|
additionalProperties: false
|
|
additionalProperties: true
|