Summary
Feedback from publishing a remote-only MCP server to the registry preview. The docs are good but the remote-only path has a few gaps that cost me time, and I suspect they will cost others the same.
Concrete case: Swarms, a hosted MCP server at https://mcp.swarms.world/mcp exposing 23 tools over streamable HTTP. Manifest is at https://github.com/kyegomez/swarms/blob/master/server.json.
1. The quickstart assumes a package, and remote-only publishers have no path to follow
quickstart.mdx is written entirely around npm, with package-types.mdx covering PyPI, NuGet, OCI and MCPB. Every one of those is about verifying ownership of a published artifact.
For a remote-only server there is no artifact. Steps 1 and 2 simply do not apply, and it is not stated anywhere that skipping them is correct rather than an error on my part. I worked it out by reading the schema and noticing that neither packages nor remotes appears in required, which is not where a newcomer will look.
A short "Publishing a remote-only server" section, even three sentences saying that packages may be omitted and that namespace ownership alone is the verification, would close this.
2. Ownership verification for remotes is undocumented
For PyPI the mechanism is explicit: an mcp-name: string in the README. For a remote server under io.github.<user>/, I assume GitHub auth on the namespace is the entire check, since there is no artifact to stamp. That seems right, but it is inferred rather than documented.
Worth stating explicitly, because the security properties differ. A package entry proves control of the package. A remote entry proves control of the GitHub namespace, which is not the same as proving control of the URL being advertised. If a domain-verified namespace is the recommended path for remotes that advertise a URL on a different domain, saying so would help.
3. The 100 character description limit is not surfaced
My first manifest failed validation on description being too long. The limit is only discoverable by reading maxLength in the schema, and every example in the docs is comfortably under it, so there is nothing to suggest a limit exists.
Worth a note next to the first server.json example, or a longer example that visibly approaches the cap.
Small thing that worked well
Validating the manifest against the published 2025-12-11 schema with a plain jsonschema call caught the problem immediately with a precise message. Publishing a stable, fetchable schema URL is genuinely useful and I would not want that to change.
Happy to open a docs PR for any of the above if that is more useful than an issue.
Summary
Feedback from publishing a remote-only MCP server to the registry preview. The docs are good but the remote-only path has a few gaps that cost me time, and I suspect they will cost others the same.
Concrete case: Swarms, a hosted MCP server at
https://mcp.swarms.world/mcpexposing 23 tools over streamable HTTP. Manifest is at https://github.com/kyegomez/swarms/blob/master/server.json.1. The quickstart assumes a package, and remote-only publishers have no path to follow
quickstart.mdxis written entirely around npm, withpackage-types.mdxcovering PyPI, NuGet, OCI and MCPB. Every one of those is about verifying ownership of a published artifact.For a remote-only server there is no artifact. Steps 1 and 2 simply do not apply, and it is not stated anywhere that skipping them is correct rather than an error on my part. I worked it out by reading the schema and noticing that neither
packagesnorremotesappears inrequired, which is not where a newcomer will look.A short "Publishing a remote-only server" section, even three sentences saying that
packagesmay be omitted and that namespace ownership alone is the verification, would close this.2. Ownership verification for remotes is undocumented
For PyPI the mechanism is explicit: an
mcp-name:string in the README. For a remote server underio.github.<user>/, I assume GitHub auth on the namespace is the entire check, since there is no artifact to stamp. That seems right, but it is inferred rather than documented.Worth stating explicitly, because the security properties differ. A package entry proves control of the package. A remote entry proves control of the GitHub namespace, which is not the same as proving control of the URL being advertised. If a domain-verified namespace is the recommended path for remotes that advertise a URL on a different domain, saying so would help.
3. The 100 character description limit is not surfaced
My first manifest failed validation on
descriptionbeing too long. The limit is only discoverable by readingmaxLengthin the schema, and every example in the docs is comfortably under it, so there is nothing to suggest a limit exists.Worth a note next to the first
server.jsonexample, or a longer example that visibly approaches the cap.Small thing that worked well
Validating the manifest against the published
2025-12-11schema with a plainjsonschemacall caught the problem immediately with a precise message. Publishing a stable, fetchable schema URL is genuinely useful and I would not want that to change.Happy to open a docs PR for any of the above if that is more useful than an issue.