From 453956d9758d73f0bc131a5867591bc1145ea5a9 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 12 Dec 2025 09:33:57 -0800 Subject: [PATCH] chore: Release server.json schema version 2025-12-11 (#841) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prepared by Claude Code, iterated and reviewed by me. ## Summary This PR releases the server.json schema version `2025-12-11`, incorporating URL template variables for remote servers from #570. ### What's New - **URL Template Variables for Remote Servers** - Remote servers can now define configurable variables in URLs using `{curly_braces}` notation, enabling multi-tenant deployments. ### Schema Version - `2025-10-17` → `2025-12-11` ## Release Sequence 1. ~~**First: Merge static repo PR** - https://github.com/modelcontextprotocol/static/pull/11 (publishes schema to versioned URL)~~ 2. **Then: Merge this PR** - Updates registry code to reference the new schema version ## Changes in This PR - [x] Update CHANGELOG.md with release notes - [x] Update `CurrentSchemaVersion` in `pkg/model/constants.go` - [x] Update schema example URL in `docs/reference/api/openapi.yaml` - [x] Update schema URL in `pkg/api/v0/types.go` - [x] Update all documentation examples to use new schema version - [x] Regenerate `server.schema.json` ## Test Plan - [x] `make check` passes (lint, schema validation, example validation) - [x] Unit tests pass for validators and publisher commands 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.5 --- cmd/publisher/commands/publish_test.go | 4 +- data/seed.json | 8 +-- .../modelcontextprotocol-io/package-types.mdx | 10 +-- docs/modelcontextprotocol-io/quickstart.mdx | 4 +- .../registry-aggregators.mdx | 2 +- .../remote-servers.mdx | 66 +++++++++++++++++-- docs/modelcontextprotocol-io/versioning.mdx | 2 +- docs/reference/api/openapi.yaml | 2 +- docs/reference/server-json/CHANGELOG.md | 28 ++++++++ .../server-json/generic-server-json.md | 30 ++++----- docs/reference/server-json/server.schema.json | 2 +- pkg/api/v0/types.go | 2 +- pkg/model/constants.go | 2 +- 13 files changed, 124 insertions(+), 38 deletions(-) diff --git a/cmd/publisher/commands/publish_test.go b/cmd/publisher/commands/publish_test.go index 8527020..c18c004 100644 --- a/cmd/publisher/commands/publish_test.go +++ b/cmd/publisher/commands/publish_test.go @@ -44,8 +44,8 @@ func TestPublishCommand_DeprecatedSchema(t *testing.T) { errorSubstr: "deprecated schema detected", }, { - name: "current 2025-10-17 schema should pass validation", - schema: "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + name: "current 2025-12-11 schema should pass validation", + schema: "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", expectError: false, }, { diff --git a/data/seed.json b/data/seed.json index 92fa625..7f65a4a 100644 --- a/data/seed.json +++ b/data/seed.json @@ -1,6 +1,6 @@ [ { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.domdomegg/airtable-mcp-server", "description": "Read and write access to Airtable database schemas, tables, and records.", "repository": { @@ -62,7 +62,7 @@ ] }, { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.domdomegg/airtable-mcp-server", "description": "Read and write access to Airtable database schemas, tables, and records.", "repository": { @@ -115,7 +115,7 @@ ] }, { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.domdomegg/time-mcp-nuget", "description": "Get the current UTC time in RFC 3339 format.", "repository": { @@ -136,7 +136,7 @@ ] }, { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.domdomegg/time-mcp-pypi", "description": "Get the current UTC time in RFC 3339 format.", "repository": { diff --git a/docs/modelcontextprotocol-io/package-types.mdx b/docs/modelcontextprotocol-io/package-types.mdx index 57960a3..4ce97b2 100644 --- a/docs/modelcontextprotocol-io/package-types.mdx +++ b/docs/modelcontextprotocol-io/package-types.mdx @@ -15,7 +15,7 @@ npm packages use `"registryType": "npm"` in `server.json`. For example: ```json server.json highlight={9} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.username/email-integration-mcp", "title": "Email Integration", "description": "Send emails and manage email accounts", @@ -53,7 +53,7 @@ PyPI packages use `"registryType": "pypi"` in `server.json`. For example: ```json server.json highlight={9} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.username/database-query-mcp", "title": "Database Query", "description": "Execute SQL queries and manage database connections", @@ -91,7 +91,7 @@ NuGet packages use `"registryType": "nuget"` in `server.json`. For example: ```json server.json highlight={9} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.username/azure-devops-mcp", "title": "Azure DevOps", "description": "Manage Azure DevOps work items and pipelines", @@ -135,7 +135,7 @@ Docker/OCI images use `"registryType": "oci"` in `server.json`. For example: ```json server.json highlight={9} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.username/kubernetes-manager-mcp", "title": "Kubernetes Manager", "description": "Deploy and manage Kubernetes resources", @@ -170,7 +170,7 @@ MCPB packages use `"registryType": "mcpb"` in `server.json`. For example: ```json server.json highlight={9} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.username/image-processor-mcp", "title": "Image Processor", "description": "Process and transform images with various filters", diff --git a/docs/modelcontextprotocol-io/quickstart.mdx b/docs/modelcontextprotocol-io/quickstart.mdx index 212951f..c1c0301 100644 --- a/docs/modelcontextprotocol-io/quickstart.mdx +++ b/docs/modelcontextprotocol-io/quickstart.mdx @@ -143,7 +143,7 @@ Open the generated `server.json` file, and you should see contents like: ```json server.json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.my-username/weather", "description": "An MCP server for weather information.", "repository": { @@ -177,7 +177,7 @@ Edit the contents as necessary: ```diff server.json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.my-username/weather", "description": "An MCP server for weather information.", "repository": { diff --git a/docs/modelcontextprotocol-io/registry-aggregators.mdx b/docs/modelcontextprotocol-io/registry-aggregators.mdx index 685944f..07ebb1e 100644 --- a/docs/modelcontextprotocol-io/registry-aggregators.mdx +++ b/docs/modelcontextprotocol-io/registry-aggregators.mdx @@ -75,7 +75,7 @@ The subregistry OpenAPI spec allows subregistries to inject custom metadata via ```json server.json highlight={17-26} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.username/email-integration-mcp", "title": "Email Integration", "description": "Send emails and manage email accounts", diff --git a/docs/modelcontextprotocol-io/remote-servers.mdx b/docs/modelcontextprotocol-io/remote-servers.mdx index 4b0c85e..8e88748 100644 --- a/docs/modelcontextprotocol-io/remote-servers.mdx +++ b/docs/modelcontextprotocol-io/remote-servers.mdx @@ -7,7 +7,7 @@ The MCP Registry supports remote MCP servers via the `remotes` property in `serv ```json server.json highlight={7-12} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "com.example/acme-analytics", "title": "ACME Analytics", "description": "Real-time business intelligence and reporting platform", @@ -31,7 +31,7 @@ Specify the transport by setting the `type` property of the `remotes` entry to e ```json server.json highlight={9,13} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "com.example/acme-analytics", "title": "ACME Analytics", "description": "Real-time business intelligence and reporting platform", @@ -49,13 +49,71 @@ Specify the transport by setting the `type` property of the `remotes` entry to e } ``` +## URL Template Variables + +Remote servers can define URL template variables using `{curly_braces}` notation. This enables multi-tenant deployments where a single server definition can support multiple endpoints with configurable values: + +```json server.json highlight={10-17} +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "com.example/acme-analytics", + "title": "ACME Analytics", + "description": "Real-time business intelligence and reporting platform", + "version": "2.0.0", + "remotes": [ + { + "type": "streamable-http", + "url": "https://{tenant_id}.analytics.example.com/mcp", + "variables": { + "tenant_id": { + "description": "Your tenant identifier (e.g., 'us-cell1', 'emea-cell1')", + "isRequired": true + } + } + } + ] +} +``` + +When configuring this server, users provide their `tenant_id` value, and the URL template gets resolved to the appropriate endpoint (e.g., `https://us-cell1.analytics.example.com/mcp`). + +Variables support additional properties like `default`, `choices`, and `isSecret`: + +```json server.json highlight={12-22} +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "com.example/multi-region-mcp", + "title": "Multi-Region MCP", + "description": "MCP server with regional endpoints", + "version": "1.0.0", + "remotes": [ + { + "type": "streamable-http", + "url": "https://api.example.com/{region}/mcp", + "variables": { + "region": { + "description": "Deployment region", + "isRequired": true, + "choices": [ + "us-east-1", + "eu-west-1", + "ap-southeast-1" + ], + "default": "us-east-1" + } + } + } + ] +} +``` + ## HTTP Headers MCP clients can be instructed to send specific HTTP headers by adding the `headers` property to the `remotes` entry: ```json server.json highlight={11-18} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "com.example/acme-analytics", "title": "ACME Analytics", "description": "Real-time business intelligence and reporting platform", @@ -83,7 +141,7 @@ The `remotes` property can coexist with the `packages` property in `server.json` ```json server.json highlight={7-22} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.username/email-integration-mcp", "title": "Email Integration", "description": "Send emails and manage email accounts", diff --git a/docs/modelcontextprotocol-io/versioning.mdx b/docs/modelcontextprotocol-io/versioning.mdx index ddaedbe..7a4da6e 100644 --- a/docs/modelcontextprotocol-io/versioning.mdx +++ b/docs/modelcontextprotocol-io/versioning.mdx @@ -7,7 +7,7 @@ MCP servers **MUST** define a version string in `server.json`. For example: ```json server.json highlight={6} { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.username/email-integration-mcp", "title": "Email Integration", "description": "Send emails and manage email accounts", diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml index ceb6369..39098da 100644 --- a/docs/reference/api/openapi.yaml +++ b/docs/reference/api/openapi.yaml @@ -728,7 +728,7 @@ components: type: string format: uri description: JSON Schema URI for this server.json format - example: "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json" + example: "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json" packages: type: array items: diff --git a/docs/reference/server-json/CHANGELOG.md b/docs/reference/server-json/CHANGELOG.md index 3fcf0c0..78d246d 100644 --- a/docs/reference/server-json/CHANGELOG.md +++ b/docs/reference/server-json/CHANGELOG.md @@ -16,6 +16,34 @@ When ready for release, changes in this section will be moved to a dated version --- +## 2025-12-11 + +### Changed + +#### URL Template Variables for Remote Servers ([#570](https://github.com/modelcontextprotocol/registry/pull/570)) + +Remote servers can now define URL template variables using `{curly_braces}` notation. This enables multi-tenant deployments where a single server definition can support multiple endpoints with configurable values. + +**Example:** +```json +{ + "remotes": [{ + "type": "streamable-http", + "url": "https://{tenant_id}.api.example.com/mcp", + "variables": { + "tenant_id": { + "description": "Your tenant identifier", + "isRequired": true + } + } + }] +} +``` + +**Migration:** No changes required. Existing servers continue to work unchanged. + +--- + ## 2025-10-17 ### Changed diff --git a/docs/reference/server-json/generic-server-json.md b/docs/reference/server-json/generic-server-json.md index 71a0ecc..b525bde 100644 --- a/docs/reference/server-json/generic-server-json.md +++ b/docs/reference/server-json/generic-server-json.md @@ -38,7 +38,7 @@ When publishing to the official registry, custom metadata must be placed under t ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.modelcontextprotocol.anonymous/brave-search", "description": "MCP server for Brave Search API integration", "title": "Brave Search", @@ -85,7 +85,7 @@ For MCP servers located within a subdirectory of a larger repository (monorepo s ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.modelcontextprotocol/everything", "description": "MCP server that exercises all the features of the MCP protocol", "title": "Everything", @@ -124,7 +124,7 @@ Suppose your MCP server application requires a `mcp start` CLI arguments to star ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.joelverhagen/knapcode-samplemcpserver", "description": "Sample NuGet MCP server for a random number and random weather", "version": "0.4.0-beta", @@ -168,7 +168,7 @@ This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcp ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.modelcontextprotocol/filesystem", "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.", "title": "Filesystem", @@ -268,7 +268,7 @@ This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcp ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.modelcontextprotocol.anonymous/mcp-fs", "description": "Cloud-hosted MCP filesystem server", "repository": { @@ -302,7 +302,7 @@ This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcp ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.example/weather-mcp", "description": "Python MCP server for weather data access", "title": "Weather", @@ -358,7 +358,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6. ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.joelverhagen/knapcode-samplemcpserver", "description": "Sample NuGet MCP server for a random number and random weather", "repository": { @@ -407,7 +407,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6. ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.example/database-manager", "description": "MCP server for database operations with support for multiple database types", "repository": { @@ -516,7 +516,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6. ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.modelcontextprotocol.anonymous/hybrid-mcp", "description": "MCP server available as both local package and remote service", "title": "Hybrid", @@ -602,7 +602,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6. ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.modelcontextprotocol/text-editor", "description": "MCP Bundle server for advanced text editing capabilities", "title": "Text Editor", @@ -645,7 +645,7 @@ Some CLI tools bundle an MCP server, without a standalone MCP package or a publi ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.snyk/cli-mcp", "description": "MCP server provided by the Snyk CLI", "title": "Snyk", @@ -680,7 +680,7 @@ For MCP servers that follow a custom installation path or are embedded in applic ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.modelcontextprotocol.anonymous/embedded-mcp", "description": "MCP server embedded in a Desktop app", "websiteUrl": "https://anonymous.modelcontextprotocol.io/embedded-mcp-guide", @@ -695,7 +695,7 @@ This example demonstrates URL templating for remote servers, useful for multi-te ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.modelcontextprotocol.anonymous/multi-tenant-server", "description": "MCP server with configurable remote endpoint", "title": "Multi-Tenant Server", @@ -721,7 +721,7 @@ The same URL templating works with SSE transport: ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.modelcontextprotocol.anonymous/events-server", "description": "MCP server using SSE with tenant-specific endpoints", "version": "1.0.0", @@ -746,7 +746,7 @@ This example demonstrates URL templating for local/package servers, where variab ```json { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.example/configurable-server", "description": "Local MCP server with configurable port", "title": "Configurable Server", diff --git a/docs/reference/server-json/server.schema.json b/docs/reference/server-json/server.schema.json index 5c1c51d..e25191b 100644 --- a/docs/reference/server-json/server.schema.json +++ b/docs/reference/server-json/server.schema.json @@ -404,7 +404,7 @@ "properties": { "$schema": { "description": "JSON Schema URI for this server.json format", - "example": "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json", + "example": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "format": "uri", "type": "string" }, diff --git a/pkg/api/v0/types.go b/pkg/api/v0/types.go index b6eab37..513e125 100644 --- a/pkg/api/v0/types.go +++ b/pkg/api/v0/types.go @@ -32,7 +32,7 @@ type ServerMeta struct { } type ServerJSON struct { - Schema string `json:"$schema" required:"true" minLength:"1" format:"uri" doc:"JSON Schema URI for this server.json format" example:"https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json"` + Schema string `json:"$schema" required:"true" minLength:"1" format:"uri" doc:"JSON Schema URI for this server.json format" example:"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json"` Name string `json:"name" minLength:"3" maxLength:"200" pattern:"^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$" doc:"Server name in reverse-DNS format. Must contain exactly one forward slash separating namespace from server name." example:"io.github.user/weather"` Description string `json:"description" minLength:"1" maxLength:"100" doc:"Clear human-readable explanation of server functionality." example:"MCP server providing weather data and forecasts via OpenWeatherMap API"` Title string `json:"title,omitempty" minLength:"1" maxLength:"100" doc:"Optional human-readable title or display name for the MCP server." example:"Weather API"` diff --git a/pkg/model/constants.go b/pkg/model/constants.go index 1473c92..e817f2a 100644 --- a/pkg/model/constants.go +++ b/pkg/model/constants.go @@ -36,7 +36,7 @@ const ( // Schema versions const ( // CurrentSchemaVersion is the current supported schema version date - CurrentSchemaVersion = "2025-10-17" + CurrentSchemaVersion = "2025-12-11" // CurrentSchemaURL is the full URL to the current schema CurrentSchemaURL = "https://static.modelcontextprotocol.io/schemas/" + CurrentSchemaVersion + "/server.schema.json" )