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
20 KiB
20 KiB
server.json Format Specification
A server.json file is a standardized way to describe MCP servers for registry publishing, client discovery, and package management.
Also see:
- For step-by-step instructions on creating and using server.json files, see the publishing guide.
- For understanding the validation requirements when publishing to the official registry, see official registry requirements.
Browse the Complete Schema
📋 View the full specification interactively: Open server.schema.json in a schema viewer like json-schema.app.
The schema contains all field definitions, validation rules, examples, and detailed descriptions.
The official registry has some more restrictions on top of this. See the official registry requirements for details.
Examples
Basic Server with NPM Package
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.modelcontextprotocol.anonymous/brave-search",
"description": "MCP server for Brave Search API integration",
"status": "active",
"website_url": "https://anonymous.modelcontextprotocol.io/examples",
"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-brave-search",
"version": "1.0.2",
"transport": {
"type": "stdio"
},
"environment_variables": [
{
"name": "BRAVE_API_KEY",
"description": "Brave Search API Key",
"is_required": true,
"is_secret": true
}
]
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "npm-publisher",
"version": "1.0.1",
"build_info": {
"timestamp": "2023-12-01T10:30:00Z"
}
}
}
}
Server in a Monorepo with Subfolder
For MCP servers located within a subdirectory of a larger repository (monorepo structure), use the subfolder field to specify the relative path:
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.modelcontextprotocol/everything",
"description": "MCP server that exercises all the features of the MCP protocol",
"status": "active",
"repository": {
"url": "https://github.com/modelcontextprotocol/servers",
"source": "github",
"subfolder": "src/everything"
},
"version": "0.6.2",
"packages": [
{
"registry_type": "npm",
"registry_base_url": "https://registry.npmjs.org",
"identifier": "@modelcontextprotocol/everything",
"version": "0.6.2",
"transport": {
"type": "stdio"
}
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "npm-publisher",
"version": "1.0.1",
"build_info": {
"timestamp": "2023-12-01T10:30:00Z"
}
}
}
}
Constant (fixed) arguments needed to start the MCP server
Suppose your MCP server application requires a mcp start CLI arguments to start in MCP server mode. Express these as positional arguments like this:
{
"name": "io.github.joelverhagen/knapcode-samplemcpserver",
"description": "Sample NuGet MCP server for a random number and random weather",
"version": "0.4.0-beta",
"packages": [
{
"registry_type": "nuget",
"registry_base_url": "https://api.nuget.org",
"identifier": "Knapcode.SampleMcpServer",
"version": "0.4.0-beta",
"transport": {
"type": "stdio"
},
"package_arguments": [
{
"type": "positional",
"value": "mcp"
},
{
"type": "positional",
"value": "start"
}
]
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "nuget-publisher",
"version": "2.1.0",
"build_info": {
"timestamp": "2023-11-15T14:22:00Z",
"pipeline_id": "nuget-build-456"
}
}
}
}
This will essentially instruct the MCP client to execute dnx Knapcode.SampleMcpServer@0.4.0-beta -- mcp start instead of the default dnx Knapcode.SampleMcpServer@0.4.0-beta (when no package_arguments are provided).
Filesystem Server with Multiple Packages
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.github.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",
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
},
"version": "1.0.2",
"packages": [
{
"registry_type": "npm",
"registry_base_url": "https://registry.npmjs.org",
"identifier": "@modelcontextprotocol/server-filesystem",
"version": "1.0.2",
"transport": {
"type": "stdio"
},
"package_arguments": [
{
"type": "positional",
"value_hint": "target_dir",
"description": "Path to access",
"default": "/Users/username/Desktop",
"is_required": true,
"is_repeated": true
}
],
"environment_variables": [
{
"name": "LOG_LEVEL",
"description": "Logging level (debug, info, warn, error)",
"default": "info"
}
]
},
{
"registry_type": "oci",
"registry_base_url": "https://docker.io",
"identifier": "mcp/filesystem",
"version": "1.0.2",
"transport": {
"type": "stdio"
},
"runtime_arguments": [
{
"type": "named",
"description": "Mount a volume into the container",
"name": "--mount",
"value": "type=bind,src={source_path},dst={target_path}",
"is_required": true,
"is_repeated": true,
"variables": {
"source_path": {
"description": "Source path on host",
"format": "filepath",
"is_required": true
},
"target_path": {
"description": "Path to mount in the container. It should be rooted in `/project` directory.",
"is_required": true,
"default": "/project"
}
}
}
],
"package_arguments": [
{
"type": "positional",
"value_hint": "target_dir",
"value": "/project"
}
],
"environment_variables": [
{
"name": "LOG_LEVEL",
"description": "Logging level (debug, info, warn, error)",
"default": "info"
}
]
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "ci-publisher",
"version": "3.2.1",
"build_info": {
"commit": "a1b2c3d4e5f6789",
"timestamp": "2023-12-01T10:30:00Z",
"pipeline_id": "filesystem-build-789",
"environment": "production"
}
}
}
}
Remote Server Example
{
"name": "io.modelcontextprotocol.anonymous/mcp-fs",
"description": "Cloud-hosted MCP filesystem server",
"repository": {
"url": "https://github.com/example/remote-fs",
"source": "github",
"id": "xyz789ab-cdef-0123-4567-890ghijklmno"
},
"version": "2.0.0",
"remotes": [
{
"type": "sse",
"url": "http://mcp-fs.anonymous.modelcontextprotocol.io/sse"
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "cloud-deployer",
"version": "2.4.0",
"build_info": {
"commit": "f7e8d9c2b1a0",
"timestamp": "2023-12-05T08:45:00Z",
"deployment_id": "remote-fs-deploy-456",
"region": "us-west-2"
}
}
}
}
Python Package Example
{
"name": "io.github.example/weather-mcp",
"description": "Python MCP server for weather data access",
"repository": {
"url": "https://github.com/example/weather-mcp",
"source": "github",
"id": "def456gh-ijkl-7890-mnop-qrstuvwxyz12"
},
"version": "0.5.0",
"packages": [
{
"registry_type": "pypi",
"registry_base_url": "https://pypi.org",
"identifier": "weather-mcp-server",
"version": "0.5.0",
"runtime_hint": "uvx",
"transport": {
"type": "stdio"
},
"environment_variables": [
{
"name": "WEATHER_API_KEY",
"description": "API key for weather service",
"is_required": true,
"is_secret": true
},
{
"name": "WEATHER_UNITS",
"description": "Temperature units (celsius, fahrenheit)",
"default": "celsius"
}
]
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "poetry-publisher",
"version": "1.8.3",
"build_info": {
"python_version": "3.11.5",
"timestamp": "2023-11-28T16:20:00Z",
"build_id": "pypi-weather-123",
"dependencies_hash": "sha256:a9b8c7d6e5f4"
}
}
}
}
NuGet (.NET) Package Example
The dnx tool ships with the .NET 10 SDK, starting with Preview 6.
{
"name": "io.github.joelverhagen/knapcode-samplemcpserver",
"description": "Sample NuGet MCP server for a random number and random weather",
"repository": {
"url": "https://github.com/joelverhagen/Knapcode.SampleMcpServer",
"source": "github",
"id": "example-nuget-id-0000-1111-222222222222"
},
"version": "0.5.0",
"packages": [
{
"registry_type": "nuget",
"registry_base_url": "https://api.nuget.org",
"identifier": "Knapcode.SampleMcpServer",
"version": "0.5.0",
"runtime_hint": "dnx",
"transport": {
"type": "stdio"
},
"environment_variables": [
{
"name": "WEATHER_CHOICES",
"description": "Comma separated list of weather descriptions to randomly select.",
"is_required": true,
"is_secret": false
}
]
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "dotnet-publisher",
"version": "8.0.100",
"build_info": {
"dotnet_version": "8.0.0",
"timestamp": "2023-12-10T12:15:00Z",
"configuration": "Release",
"target_framework": "net8.0",
"build_number": "20231210.1"
}
}
}
}
Complex Docker Server with Multiple Arguments
{
"name": "io.github.example/database-manager",
"description": "MCP server for database operations with support for multiple database types",
"repository": {
"url": "https://github.com/example/database-manager-mcp",
"source": "github",
"id": "ghi789jk-lmno-1234-pqrs-tuvwxyz56789"
},
"version": "3.1.0",
"packages": [
{
"registry_type": "oci",
"registry_base_url": "https://docker.io",
"identifier": "example/database-manager-mcp",
"version": "3.1.0",
"transport": {
"type": "stdio"
},
"runtime_arguments": [
{
"type": "named",
"name": "--network",
"value": "host",
"description": "Use host network mode"
},
{
"type": "named",
"name": "-e",
"value": "DB_TYPE={db_type}",
"description": "Database type to connect to",
"is_repeated": true,
"variables": {
"db_type": {
"description": "Type of database",
"choices": [
"postgres",
"mysql",
"mongodb",
"redis"
],
"is_required": true
}
}
}
],
"package_arguments": [
{
"type": "named",
"name": "--host",
"description": "Database host",
"default": "localhost",
"is_required": true
},
{
"type": "named",
"name": "--port",
"description": "Database port",
"format": "number"
},
{
"type": "positional",
"value_hint": "database_name",
"description": "Name of the database to connect to",
"is_required": true
}
],
"environment_variables": [
{
"name": "DB_USERNAME",
"description": "Database username",
"is_required": true
},
{
"name": "DB_PASSWORD",
"description": "Database password",
"is_required": true,
"is_secret": true
},
{
"name": "SSL_MODE",
"description": "SSL connection mode",
"default": "prefer",
"choices": [
"disable",
"prefer",
"require"
]
}
]
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "docker-buildx",
"version": "0.12.1",
"build_info": {
"docker_version": "24.0.7",
"timestamp": "2023-12-08T14:30:00Z",
"platform": "linux/amd64,linux/arm64",
"registry": "docker.io",
"image_digest": "sha256:1a2b3c4d5e6f7890"
}
}
}
}
Server with Remote and Package Options
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.modelcontextprotocol.anonymous/hybrid-mcp",
"description": "MCP server available as both local package and remote service",
"repository": {
"url": "https://github.com/example/hybrid-mcp",
"source": "github",
"id": "klm012no-pqrs-3456-tuvw-xyz789abcdef"
},
"version": "1.5.0",
"packages": [
{
"registry_type": "npm",
"registry_base_url": "https://registry.npmjs.org",
"identifier": "@example/hybrid-mcp-server",
"version": "1.5.0",
"runtime_hint": "npx",
"transport": {
"type": "stdio"
},
"package_arguments": [
{
"type": "named",
"name": "--mode",
"description": "Operation mode",
"default": "local",
"choices": [
"local",
"cached",
"proxy"
]
}
]
}
],
"remotes": [
{
"type": "sse",
"url": "https://mcp.anonymous.modelcontextprotocol.io/sse",
"headers": [
{
"name": "X-API-Key",
"description": "API key for authentication",
"is_required": true,
"is_secret": true
},
{
"name": "X-Region",
"description": "Service region",
"default": "us-east-1",
"choices": [
"us-east-1",
"eu-west-1",
"ap-southeast-1"
]
}
]
},
{
"type": "streamable-http",
"url": "https://mcp.anonymous.modelcontextprotocol.io/http"
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "hybrid-deployer",
"version": "1.7.2",
"build_info": {
"timestamp": "2023-12-03T11:00:00Z",
"deployment_strategy": "blue-green",
"npm_version": "10.2.4",
"node_version": "20.10.0",
"service_endpoints": {
"sse": "deployed",
"streamable": "deployed"
}
}
}
}
}
MCP Bundle (MCPB) Package Example
{
"name": "io.modelcontextprotocol/text-editor",
"description": "MCP Bundle server for advanced text editing capabilities",
"repository": {
"url": "https://github.com/modelcontextprotocol/text-editor-mcpb",
"source": "github"
},
"version": "1.0.2",
"packages": [
{
"registry_type": "mcpb",
"registry_base_url": "https://github.com",
"identifier": "https://github.com/modelcontextprotocol/text-editor-mcpb/releases/download/v1.0.2/text-editor.mcpb",
"version": "1.0.2",
"file_sha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
"transport": {
"type": "stdio"
}
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "mcpb-publisher",
"version": "1.0.0",
"build_info": {
"timestamp": "2023-12-02T09:15:00Z",
"bundle_format": "mcpb-v1"
}
}
}
}
This example shows an MCPB (MCP Bundle) package that:
- Is hosted on GitHub Releases (an allowlisted provider)
- Includes a SHA-256 hash for integrity verification
- Can be downloaded and executed directly by MCP clients that support MCPB
Embedded MCP inside a CLI tool
Some CLI tools bundle an MCP server, without a standalone MCP package or a public repository. In these cases, reuse the existing packages shape by pointing at the host CLI package and supplying the package_arguments and runtime_hint if needed to start the MCP server.
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.snyk/cli-mcp",
"description": "MCP server provided by the Snyk CLI",
"status": "active",
"version": "1.1298.0",
"packages": [
{
"registry_type": "npm",
"registry_base_url": "https://registry.npmjs.org",
"identifier": "snyk",
"version": "1.1298.0",
"transport": {
"type": "stdio"
},
"package_arguments": [
{ "type": "positional", "value": "mcp" },
{
"type": "named",
"name": "-t",
"description": "Transport type for MCP server",
"default": "stdio",
"choices": ["stdio", "sse"]
}
]
}
]
}
Server with Custom Installation Path
For MCP servers that follow a custom installation path or are embedded in applications without standalone packages, use the website_url field to direct users to setup documentation:
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.modelcontextprotocol.anonymous/embedded-mcp",
"description": "MCP server embedded in a Desktop app",
"status": "active",
"website_url": "https://anonymous.modelcontextprotocol.io/embedded-mcp-guide",
"version": "0.1.0"
}
Deprecated Server Example
{
"name": "io.github.example/old-weather",
"description": "Legacy weather server - DEPRECATED: Use weather-v2 instead for new projects",
"status": "deprecated",
"repository": {
"url": "https://github.com/example/old-weather",
"source": "github",
"id": "legacy-abc123-def456-789012-345678-901234567890"
},
"version": "0.9.5",
"packages": [
{
"registry_type": "npm",
"registry_base_url": "https://registry.npmjs.org",
"identifier": "@legacy/old-weather-server",
"version": "0.9.5",
"transport": {
"type": "stdio"
},
"environment_variables": [
{
"name": "WEATHER_API_KEY",
"description": "Weather API key",
"is_required": true,
"is_secret": true
}
]
}
],
"_meta": {
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "legacy-publisher",
"version": "0.8.1",
"build_info": {
"timestamp": "2023-06-15T09:30:00Z",
"deprecation_notice": "This publisher is deprecated. Use npm-publisher v2.0+ for new projects.",
"maintenance_mode": true,
"final_version": true
}
}
}
}