The server.json mistakes that get your MCP server rejected
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 t
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.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.