If you have been trying to publish an MCP server to the official registry, you have likely encountered the silent rejection of your server.json file. While the schema itself is compact, validation failures are frequent and often stem from a handful of predictable mistakes. A recent deep dive into the registry's current schema (version 2025-12-11) highlights exactly where developers are tripping up, moving beyond vague error messages to specific configuration fixes.

The Most Common Validation Failures

The single most frequent cause of rejection is an overly verbose description field. The schema enforces a strict 100-character limit, meaning marketing-heavy paragraphs are automatically flagged. Developers must condense their pitch into one tight sentence. Another critical error involves the version field. The top-level version is required and distinct from any package-specific versions. It is common for builders to set the package version correctly but forget to define the root server version, leading to immediate validation failure. Transport configuration is another area where assumptions lead to errors. Every entry within the packages array requires a transport definition, even for local stdio servers. Developers often add transports for HTTP remotes but omit them for stdio packages, which the schema rejects. Additionally, package versions must be concrete. Using "latest" is explicitly prohibited, and range specifiers like ^1.2.3 are discouraged. Pinning to a specific version is the only reliable path to acceptance.

Naming Conventions and Field Structure

The name field requires a specific reverse-DNS structure, containing exactly one slash, such as io.github.you/my-server. Simple names like my-server or those with multiple slashes fail validation. For remote servers, each entry in the remotes array must include both a type (either streamable-http or sse) and a url. Missing either component results in rejection. A significant shift in the schema involves casing and deprecated fields. The schema now strictly enforces camelCase for all fields. Using snake_case, such as registry_type instead of registryType, will cause validation errors. This applies to websiteUrl, packageArguments, and environmentVariables as well. Furthermore, the status field has been removed from the schema entirely. Developers copying older examples often retain this field, unaware that it is no longer valid, though the schema's permissive nature allows extra fields, it does not necessarily forgive incorrect casing or removed structural expectations in all contexts.

Practical Validation Strategies

To avoid the cycle of submission and rejection, manual schema reading is inefficient. The source article recommends using a dedicated validator, such as the free tool provided by Serverdex, which validates server.json against the official registry schema directly in the browser. This tool provides plain-English explanations for errors, ensuring nothing is uploaded. Once validated, developers can list their servers on Serverdex to increase visibility.

Key Takeaways

  • Keep descriptions under 100 characters.
  • Always define a top-level version separate from package versions.
  • Include transport types for all packages, including stdio.
  • Pin package versions; avoid "latest" or ranges.
  • Use reverse-DNS naming with exactly one slash.
  • Switch all fields to camelCase; remove deprecated status fields.

The Bottom Line

Registry validation is strict but predictable. Stop guessing and start pinning your versions, fixing your casing, and trimming your descriptions. The tools exist to validate before you submit; use them to keep your deployment pipeline clean.