Replacing /v0/servers/{id} with /v0/servers/{name}/{version}

[domdomegg]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Problem

The current API uses opaque UUIDs for server retrieval (/v0/servers/{id}), but most clients actually want to fetch servers by their semantic identifiers - name and version. This creates unnecessary friction and requires additional API calls.

Additionally, the ID is technically extra metadata specific to the official registry. This means it's not super clear how subregistries should handle this for custom packages added to them - which then makes the registry spec harder to interpret.

Proposed Change

Replace /v0/servers/{id} with /v0/servers/{name}/{version} where:

• {name} is the server's semantic name (e.g., io.github.domdomegg/filesystem)
• {version} is either a specific version (e.g., 1.2.3) or the special string latest
  • we should also ban the version string being literally latest for a package, to avoid that conflict

There would still be conflicts if the name was the same between the official regsitry and a subregistry, although this is unlikely with namespacing and registries would have to more explicitly deal with this.

Benefits

1. More intuitive for clients

Current workflow for "get the latest version of filesystem server":

# 1. List all servers and find the one I want
curl /v0/servers?limit=1000 | grep filesystem | jq '.servers[] | select(.name == "io.github.domdomegg/filesystem" and .meta.io_model_context_protocol_registry.is_latest)'
# plus probably do some pagination

# 2. Extract the UUID and make another call
curl /v0/servers/550e8400-e29b-41d4-a716-446655440000

Proposed workflow:

# Single call (with URL encoded name)
curl /v0/servers/io.github.domdomegg%2Ffilesystem/latest

2. Aligns with package manager conventions

This follows established patterns:

• npm: registry.npmjs.org/package-name/1.2.3
• Maven: repo1.maven.org/maven2/group/artifact/version
• Docker: registry-1.docker.io/library/nginx:latest

Implementation Notes

URL encoding

Server names contain slashes and may contain other special characters, so proper URL encoding is required:

• io.github.user/server-name → io.github.user%2Fserver-name

This is necessary to avoid ambiguity in parsing /v0/servers/{name}/{version} - without encoding, a name like io.github.domdomegg/filesystem in the URL /v0/servers/io.github.domdomegg/filesystem/latest could be parsed as either:

• name: io.github.domdomegg/filesystem, version: latest ✓
• name: io.github.domdomegg, version: filesystem/latest ✗

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[tadasant]

I think this is a very reasonable change, I'm in favor of it. Thanks for fleshing it out!

Maybe we would still support /{id} as well, so if anyone is concerned about handling renames, they can go the extra effort to instrument their calls to do the more complex multi-step path?

I wonder if this introduces a need for handling redirects in the case of {name} renames, similar to how GitHub does. Probably worth a backlog ticket but wouldn't consider it a go-live blocker.

[domdomegg]

I think that given server.json's should be immutable, renames hopefully won't be too problematic?

Agree we can keep the /{id} route if needed - although I guess each extra endpoint is more for the registry spec, which I want to keep as small as possible.

[tadasant]

There's actually some very legitimate rename scenarios that happen regularly. For example, the original launch of the Firecrawl MCP server was under a community user's name, so would have been published as something like io.github.vrknetha/firecrawl. Since then, the official Firecawl org has taken it over, thus picking up at v1.0.0 with a rename (but is the natural "version upgrade" for the original io.github.vrknetha that ended at something like 0.0.5).

Perhaps the most common way for this to manifest is when an employee makes a server on a personal account, and when it gets traction, the org officially takes it over. Happens probably hundreds of times per month in the ecosystem at the moment.

So yes, server.json for a particular version is immutable, but as a version upgrade creates a new server.json, I expect strong demand for a rename mechanism in the course of that bump.

I think I'm in favor of keeping /{id} as an option despite the complexity, and punting on managing redirects. But I don't feel strongly that this is go-live critical.

[domdomegg]

Think this is perhaps lower priority given we're already 95% of the way there with #374

[tadasant]

The discussion on #396 with @rdimitrov convinced me that allowing renames might be a bad idea, despite the potential demand for them.

In which case, I think I'm now much more aligned with the original proposal. I think it would be clean to entirely remove the notion of UUID's from the API spec? Thinking about it from the sub-registry perspective, it is quite odd to have to funnel that piece of data from the upstream down to sub-registry consumers.

[rosmur]

regardless, its a fairly universal practice to use UUIDs no? What was the harm in keeping it? It allows a much cleaner and more resilient system IMO