Topic 7: Registry and versioning
The MCP Registry and server.json
The MCP Registry at registry.modelcontextprotocol.io is the official catalog of public MCP servers. It stores metadata, not code: where the package lives (PyPI, npm, OCI, and others), how to run it, and which remote URLs serve it. It verifies that you own the namespace you publish under (io.github.<user>/... through GitHub login, com.example/... through DNS) and that you own the package. Its own documentation marks it as a preview: breaking changes or data resets may occur before general availability. It is designed to be consumed by aggregators (marketplaces, company-internal catalogs) that add curation and security scanning on top.
A server describes itself in server.json. The current schema version, per the registry repository at the time of writing, is 2025-12-11, identified by its $schema URL. Here is one for the notes assistant (the GitHub organization and PyPI package are illustrative; they are not actually published):
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "io.github.nare-lab/notes-assistant",
"title": "Research Notes",
"description": "Search, read, and create Markdown research notes in a local folder.",
"version": "1.1.0",
"repository": {
"url": "https://github.com/nare-lab/notes-assistant",
"source": "github"
},
"websiteUrl": "https://github.com/nare-lab/notes-assistant#readme",
"packages": [
{
"registryType": "pypi",
"registryBaseUrl": "https://pypi.org",
"identifier": "notes-assistant-mcp",
"version": "1.1.0",
"runtimeHint": "uvx",
"transport": {
"type": "stdio"
},
"environmentVariables": [
{
"name": "NOTES_DIR",
"description": "Folder that holds the Markdown notes.",
"format": "filepath",
"isRequired": true
}
]
}
],
"remotes": [
{
"type": "streamable-http",
"url": "https://notes.nare-lab.example/mcp"
}
]
}