Start with the artifact users can install or the remote endpoint they can reach today. Copy its exact identity into server.json, validate schema and size, then publish from the corresponding release.
Choose the distribution first
Decide whether users install a package or connect to a remote server. Do not fill both sections “for completeness” unless both are genuinely maintained. The Registry metadata should describe an installable release, not the project you hope to have later.
Copy identity from the release
Take the package name and version from the published artifact. Compare capitalization, namespace and tag exactly. If the repository says 1.4.0 but the registry package is 1.3.2, update the release or describe 1.3.2.
Keep transport claims concrete
For a remote entry, use the public MCP endpoint and the transport it serves. Test it from outside your network. A documentation homepage or health endpoint is not a substitute for the MCP URL.
{
"name": "io.example/ticket-search",
"version": "1.3.2",
"description": "Search support tickets by status and owner"
}
Validate identity before prose
| Field | Source of truth | Failure to catch |
|---|---|---|
| Name | Verified namespace | Ownership |
| Version | Published artifact | Missing build |
| Package ID | Package registry | Wrong scope |
| Remote URL | Public MCP endpoint | Homepage used |
| Repository | Public source | No audit trail |
Use description space for selection
Say what the server lets a user do and what system it touches. Avoid “powerful,” “seamless,” and feature inventories copied from the README. The document has a size limit; spend bytes on information that helps a developer decide.
Validate before invoking the publisher
Paste the document into RegistryReady. Resolve schema errors, version inconsistencies and the size check. Then run the official publisher from the same commit or release context you just described.
If verification fails, compare the Registry identity to the published package before editing unrelated JSON fields.
Check the install path once
Install the public package or connect to the public URL in a clean environment. Run a read-only tool. A listing that validates but cannot be used is still a bad release.
What a schema validator cannot prove
A validator catches malformed JSON, unsupported fields, identity mismatches, and size problems. It cannot prove the package is safe, the endpoint belongs to the stated maintainer, or every tool behaves as described.
Pre-publish checklist
- The package or endpoint already exists.
- Name and version match the release.
- The description states the user task.
- The URL is the MCP endpoint.
- The document passes validation.
- A clean client can call one read-only tool.
Related publishing help
For authorization, use the MCP OAuth 401 guide. For client setup, use the Claude Desktop to Codex guide.
Expected result
The document validates, its identity matches the public artifact, the transport works from a clean client, and the publisher verifies the same release.
Validate server.json →