DEV Community

Andrei
Andrei

Posted on Originally published at serverdex.io

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 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" } }
Enter fullscreen mode Exit fullscreen mode

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" } }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (1)

Collapse
 
agentwareshq profile image
agentwares •

Good list — the description cap and the missing stdio transport are the two I see most often too. One more worth adding: a server.json can pass schema validation and still get rejected if the declared transport doesn't match what the server actually speaks. A remote declared as streamable-http that only answers SSE, or a package whose entry point doesn't exist at the pinned version, both look fine on paper and fail the registry's live checks. Worth validating twice: once against the dated schema in CI (the schema version matters — 2025-12-11 today, and it does change), and once by actually connecting a client to the declared endpoint before submitting. The 100-character description is also worth treating as your one-sentence README line rather than a trimmed marketing paragraph — if it reads like a slogan, it usually fails the cap.