Shipping an MCP server is a distribution problem — the Registry gives you one discovery surface, but the packaging choice (npm vs PyPI vs OCI) determines who can actually install it.
Building the server is one problem; getting it in front of users is another. The MCP Registry — currently the closest thing to a package index for MCP — lets you list a server; the package type (npm, PyPI, or an OCI image) determines who can install it and how; and the 2026 roadmap adds .well-known capability discovery so hosts don't need a registry lookup to find compatible servers at runtime. This is a short essay because the topic is small; skipping it means users can't find your server.
The MCP Registry: what it is now.
The MCP Registry is a central index of published servers — name, description, transports supported, package type, license, capability tags, and a pointer at the underlying package. A host that wants to let a user "add an MCP server" queries the Registry, filters by capability, and hands the resulting command + args or HTTP endpoint to its transport layer. Publishing is a JSON manifest submitted through the Registry's CLI; the review bar today is closer to npm than to the App Store. The failure mode is the same as npm's, too — an unlisted server is invisible to any host that only looks in the Registry, and a listed server with a stale metadata block gets picked up for the wrong reasons.
The Registry is not a runtime — it does not proxy tool calls, front the transport, or sign responses. Its only jobs are discovery and metadata. Everything building an MCP server teaches — tool granularity, resource vs prompt split, annotations — is invisible to the Registry beyond what you write into the description field. That field is where selection actually happens, and treating it as a marketing slug instead of a capability sentence is the fastest way to publish a server nobody installs.
{
"name": "acme-search",
"description": "Search Acme's docs, then fetch full articles by id.",
"version": "1.4.2",
"protocolVersions": [">=2025-11-25"],
"transports": ["stdio", "streamable-http"],
"package": { "type": "npm", "name": "@acme/mcp-search" },
"capabilities": ["tools", "resources"],
"license": "MIT",
"homepage": "https://acme.dev/mcp"
}
Package types: npm, PyPI, OCI.
The three package types cover the three realistic delivery stories. An npm package (JS/TS servers) installs with npx for one-shot execution or npm i -g for persistence; the host launches it as a subprocess, which puts it on the stdio path by default. A PyPI package (Python servers) installs with pip, pipx, or uv; uvx has become the FastMCP-idiomatic one-shot launcher, playing the role npx does for Node. An OCI image is heavier but runtime-independent — the host pulls it, runs it, and talks to it over Streamable HTTP rather than stdio, because binding a container's stdio to a host's tool loop is more friction than a network endpoint. The trade-off is not subtle: npm and PyPI depend on the host having a working Node or Python runtime; OCI ships a self-contained thing that runs identically everywhere. Pick per audience — hobbyists and small teams take the npm/PyPI hit, enterprise deploys take the OCI hit.
# npm — one-shot, Node runtime npx -y @acme/mcp-search --stdio # PyPI — one-shot, Python runtime uvx acme-mcp-search --stdio # OCI — self-contained image, Streamable HTTP docker run -p 3333:3333 ghcr.io/acme/mcp-search:1.4.2
Versioning: SemVer with spec-version pinning.
Two version numbers travel together, and confusing them is where compatibility bugs come from. The server's own version is SemVer — 1.4.2 — with the usual contract: patch for bugfixes, minor for additive tool changes, major for breaking schema changes. The other number is the MCP protocolVersion, exchanged in the initialize handshake, identifying the spec revision (currently 2025-11-25). The server advertises the spec versions it supports as a range; the host picks the highest one it also supports; both sides must handle the "host newer than server" and "server newer than host" cases without crashing. A server that pins to exactly one spec version turns every spec bump into a forced upgrade for its clients — the transition from HTTP+SSE to Streamable HTTP took months precisely because servers pinned narrowly. The Registry manifest lists both numbers so a host can filter by spec compatibility before installing.
The 2026 roadmap: .well-known capability discovery.
The 2026 MCP roadmap adds a runtime discovery path that sits alongside the Registry rather than replacing it. A host that already knows a server's URL — because it's enterprise-hosted, local, or bookmarked — fetches /.well-known/mcp and gets a capability descriptor without ever talking to a central index. This is the same shape as the OAuth Protected Resource Metadata document already in the auth flow, and it solves the same class of problem: discovery that works for servers the public Registry doesn't and can't list — enterprise servers behind a VPN, local servers on a developer's laptop, one-off internal tools. The general pattern is covered in the capability discovery essay; the MCP-specific addition is that the descriptor mirrors the Registry's manifest fields — capabilities, transports, spec versions — so a host can consume both sources with one code path. The roadmap places this in the 2026 stable window; it is not yet in the current spec, so treat it as "worth designing your metadata to be reusable when it lands" rather than "ship against it today".