If you've published — or tried to publish — an MCP server to the official registry, you've met server.json, and the validation that quietly rejects it. The schema is small, but a handful of mistakes account for most of the failures. Here they are, checked against the current registry schema (2025-12-11).
The ones that actually trip people up
The description is too long. description is capped at 100 characters. A marketing paragraph is the single most common rejection — write one tight sentence.
No version at the root. The top-level version is required, and it's separate from a package's version. Easy to set the package version and forget the server one.
A package with no transport. Every entry in packages needs a transport — even a local stdio server:
{ "registryType": "npm", "identifier": "@you/server", "transport": { "type": "stdio" } } People add it for HTTP remotes and leave it off stdio packages.
version is "latest" or a range. A package version must be concrete. "latest" is explicitly rejected, and ranges like ^1.2.3 are discouraged. Pin it.
name has the wrong shape. It must contain exactly one slash, reverse-DNS style: io.github.you/my-server. Not my-server, not two slashes.
A remote without both type and url. Each entry in remotes needs a type (streamable-http or sse) and a url.
snake_case fields. The schema is camelCase now — it's registryType, not registry_type, and the same for websiteUrl, packageArguments, environmentVariables. And there's no status field any more; it was removed, so delete it if you're copying an old example.
A minimal valid server.json
Only name, description and version are required at the root:
{ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.you/weather", "description": "MCP server providing weather data and forecasts", "version": "1.0.0", "packages": [ { "registryType": "npm", "identifier": "@you/weather-mcp", "version": "1.0.0", "transport": { "type": "stdio" } } ] } One nice thing: the schema is permissive — it has no additionalProperties: false, so extra fields you add are fine and won't fail validation.
Check it before you publish
Rather than reading the schema by hand, I built a free server.json validator: paste yours and it validates against the official registry schema right in your browser (nothing is uploaded), with a plain-English list of what to fix. It's part of Serverdex, a directory of MCP servers.
Once your server.json is valid and you've published to the registry, you can also list the server on Serverdex so people can find it.

