Choose the identity before generating the file
A server’s display name answers “what is this?” Its registry name answers “which publisher owns this identity?” Decide the latter before you publish a package that embeds it. Keep a single source of truth for the name in your release configuration.
GitHub-based registry authentication uses an io.github user or organization namespace. Domain authentication uses a reverse-domain namespace. The authenticated identity must match the prefix in your manifest; changing a title does not change what the credential is allowed to publish.
- GitHub example identity: io.github.example/weather-tools. Replace example with the authorized user or organization.
- Domain example identity: com.example/weather-tools. This requires control of the corresponding domain and the supported verification flow.
- Choose a name you can maintain. Avoid a personal namespace for a long-lived organization product unless that ownership choice is intentional.
Generate, then review, the manifest
Use the official publisher’s initialization workflow as a starting point. Compare the result against the current schema and your actual released artifact. A plausible JSON file is not enough: the referenced package version or remote service needs to exist.
The illustrative remote manifest below intentionally uses example.com. Replace the name, description, version, and URL before validation. The schema URL reflects the official remote-server documentation checked for this guide; check the current documentation before adopting it for a new release.
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "com.example/weather-tools",
"description": "Query weather observations from Example Weather.",
"version": "1.0.0",
"remotes": [
{ "type": "streamable-http", "url": "https://example.com/mcp" }
]
}Keep package and registry releases synchronized
For an npm package, the official quickstart requires mcpName in package.json to agree with the registry identity. Publish that package release before asking the registry to describe it. Check the published package itself, because a correct local file does not prove the released archive contains the same metadata.
Use one release checklist for package version, manifest version, installation example, and changelog. If the release job stops after package publication but before registry publication, resume from the recorded artifact. Do not bump a version solely to hide an uncertain publishing result. Inspect the destination first.
Declare connection requirements without distributing credentials
A remote URL must be reachable by its intended clients. Use the documented transport and expose the appropriate authentication discovery. A health page returning 200 is not evidence that MCP initialization works at the submitted path.
The registry’s remote metadata supports header requirements and secret-input declarations. Describe where a user supplies their own key; do not insert your key as a default or paste it into server.json. For a multi-tenant endpoint, review whether a URL variable is required and explain how a user finds the tenant identifier.
Triage publishing errors in dependency order
First check the credential and namespace pair. Next confirm the package or endpoint. Then inspect schema validation and the exact name/version already present in the registry. Fixing the description cannot repair an ownership mismatch.
After a timeout, query the registry for the exact version before attempting another write. Preserve request identifiers and sanitized error responses. A verified registry result is a useful record for subsequent directory forms, but publication does not guarantee those directories import it.
- Ownership error: compare the manifest prefix with the authenticated identity and organization access.
- Package error: inspect the published release and its ownership metadata, not only your Git checkout.
- Remote error: confirm the actual MCP route and transport with a compatible client.
- Version conflict: inspect the existing public record and follow the current registry release policy.
Connect the owner for the supported automated route
For eligible GitHub namespaces, connect the source owner privately through the service’s HTTPS connection endpoint. Later calls carry only that opaque connection ID. The worker exchanges the verified GitHub identity for a fresh short-lived registry JWT when it executes the paid, authorized launch. Do not paste an expiring registry token into chat merely to prepare a quote.
The registry protocol supports more authentication choices than every application implements. MCP Server List’s current automated coverage is determined by the free preflight; a domain namespace or another unsupported combination is blocked rather than presumed equivalent to GitHub ownership. Read the exact generated manifest and namespace checks before authorizing publication.
Sources and scope
Primary documentation checked 2026-10-29. The workflow advice is MCP Server List’s editorial guidance; each destination controls its own current requirements and review.