MCP Registry Format: Extension Notes

[rdimitrov]

Pre-submission Checklist

• I have verified that this discussion would not be more appropriate as an issue in a specific repository
• I have searched existing discussions to avoid duplicates

Discussion Topic

Hi all,

I'm currently evaluating the MCP Registry format as part of ongoing work on ToolHive’s registry system. ToolHive already has an internal format in use today, which supports both private and public MCP-compatible registries. That setup works well for our current needs, but we’re exploring whether it makes sense to migrate to the upstream format to help reduce fragmentation and align with broader community efforts (we are pretty much all open source maintainers and/or contributors 😃)

This isn’t a proposal - just an attempt to share some observations from that evaluation and raise a few questions. The aim is to understand where ToolHive’s existing model might overlap with or diverge from the official MCP Registry schema, and whether some of the use cases we support are intentionally out of scope. I’ve been going through existing issues and discussions, and it’s encouraging to see that a few of these points have already been raised by others as well.

We’ve also been collaborating with folks at Docker on this topic and they’ve expressed interest in it too. I’ll add Jim Clark (@slimslenderslacks) to this thread so they can follow and contribute if helpful.

I've compared what ToolHive has and what's in the official registry format and actually almost all of the properties are already the same so below I've highlighted the main differences (some are generic, some are ToolHive specific, some are generic but perhaps out of the registry scope).

Properties that could be generally useful

• Transport Type for Packages
  Currently only defined for Remote, but we believe it's also relevant at the Package level. Already raised at - Support streamable HTTP via packages #143
  Possible addition: Package.TransportType

• Provenance Metadata
  Used to capture origin and signing information for packaged artifacts (e.g. containers, packages, etc). For more info see sigstore signatures and github attestations, but generally solves the package provenance problem. Related to Validate that submitted server.json's are referencing valid source code registries #96
  Possible addition: Package.Provenance (should be considered optional)

• Custom/Vendor Metadata
  Have a generic metadata extension mechanism across servers, packages, and remotes.
  Could be addressed by allowing a standardised Custom Metadata or Extensions field across all types, or by supporting x-* top-level properties consistently. Already raised at - Allow for vendor extensions to registry API #81

• Status
  Indicates whether a server is actively maintained or deprecated.
  Possibly useful for filtering or lifecycle tracking. Already raised at - Include mechanism for tagging servers as "archived" #181

• Tier
  Distinguishes between officially supported vs. community-maintained servers.
  Could help downstream consumers interpret registry entries.

• Popularity Fields
  For example download count or star count (if available from the underlying package registry).
  Could offer optional signals for consumers. Saw somewhere that this is part of the nice to have items for the future, so until then I think it's fair to be handled by the aggregator.

• Capability Lists
  Such as tools, resources, or prompts offered by a given packages/remotes entry.
  This has been well discussed topic and I see valid reasons for both sides.

Fields that are likely out of the registry scope and should be part of the aggregator/consumer side

• Tags/Categorisation Labels
  Labels for filtering and discovery.
  If it makes sense on the registry level, should be part of the Server. Otherwise probably be kept as either a custom extension or at the aggregator level.

• Permissions Profile
  ToolHive defines internal permission profiles per server.
  This is ToolHive-specific and would make more sense as a custom extension so no expectations here.

• Target Port
  The port for the container to expose, relevant for HTTP/SSE-based packages to indicate runtime-exposed ports.
  Possibly already covered by Package.RuntimeArguments, but worth confirming.

Why share this

As I've shared we’re early in the evaluation, but we see the upstream format hits many of the right goals so if the overlap ends up being strong enough it would make sense to align our efforts and converge on a shared format, rather than maintain a separate one.

No strong expectations here, just sharing this to see if it's useful context or if others are thinking through similar questions. Happy to follow up or share examples if that would be helpful.

Appreciate any thoughts or pointers 🍻

[tadasant]

Thank you so much @rdimitrov for the thoughtful analysis and comparison! Super helpful to get all this concrete feedback here.

Transport Type for Packages
Currently only defined for Remote, but we believe it's also relevant at the Package level. Already raised at - #143
Possible addition: Package.TransportType

Agree we could take a PR on this. Add to all four spec files (server.json in free form text - any transport allowed; registry's server.json scoped down to just the officially endorsed transports; equivalent for OpenAPI specs). Not sure if @connor4312 is still planning to take that?

Provenance Metadata
Used to capture origin and signing information for packaged artifacts (e.g. containers, packages, etc). For more info see sigstore signatures and github attestations, but generally solves the package provenance problem. Related to #96
Possible addition: Package.Provenance (should be considered optional)

An elegant solution to #96 is not yet obvious to me. In my mind, the candidates were either (1) include server.json within the package bundle and the registry would go look for it at publish time, or (2) build auth integration with every supported third party registry (npm, pypi, nuget, etc) we allow to reference

I guess that is slightly different than Provenance -- if we do one of the above, there is still no guarantee that e.g. someone who owns two packages isn't representing one vs. the other. I don't have a final answer to this, would love someone to propose a thoughtful solution that hits all the concerns raised. The GitHub eng team starting to work on the codebase is probably a week or two out from applying dev time to this.

Custom/Vendor Metadata
Have a generic metadata extension mechanism across servers, packages, and remotes.
Could be addressed by allowing a standardised Custom Metadata or Extensions field across all types, or by supporting x-* top-level properties consistently. Already raised at - #81

Besides #81, we should have the same conversation for the server.json itself; good call: #201

Status
Indicates whether a server is actively maintained or deprecated.
Possibly useful for filtering or lifecycle tracking. Already raised at - #181

Added a comment there with an insight from this, thanks!

Tier
Distinguishes between officially supported vs. community-maintained servers.
Could help downstream consumers interpret registry entries.

I think this is a little fraught. I would bucket it into the aggregator section. For example, if Tailwind builds an official MCP server that combines Figma functions with Tailwind; is that an official one? It's official for Tailwind, but Figma might have objections. So I would keep this out of the upstream registry.

Popularity Fields
For example download count or star count (if available from the underlying package registry).
Could offer optional signals for consumers. Saw somewhere that this is part of the nice to have items for the future, so until then I think it's fair to be handled by the aggregator.

Agree we are planning this: #95

Capability Lists
Such as tools, resources, or prompts offered by a given packages/remotes entry.
This has been well discussed topic and I see valid reasons for both sides.

I think this is reasonable, just a lot of thoughtful speccing work to be done. Would start with Tools and see how that goes I think: #82

---

And I agree with your section on out of scope concerns.

[rdimitrov]

Provenance Metadata

An elegant solution to #96 is not yet obvious to me. In my mind, the candidates were either (1) include server.json within the package bundle and the registry would go look for it at publish time, or (2) build auth integration with every supported third party registry (npm, pypi, nuget, etc) we allow to reference

I guess that is slightly different than Provenance -- if we do one of the above, there is still no guarantee that e.g. someone who owns two packages isn't representing one vs. the other. I don't have a final answer to this, would love someone to propose a thoughtful solution that hits all the concerns raised. The GitHub eng team starting to work on the codebase is probably a week or two out from applying dev time to this.

I'll think about it more and get back to you 👍 In any case I think both me and @slimslenderslacks would be more than happy to chat about it once the GitHub folks are available too 👍

Tier

I think this is a little fraught. I would bucket it into the aggregator section. For example, if Tailwind builds an official MCP server that combines Figma functions with Tailwind; is that an official one? It's official for Tailwind, but Figma might have objections. So I would keep this out of the upstream registry.

I was hoping this can help registry consumers distinguish between experimental/hobby projects and more officially-backed projects, but what you raised is a good point 👍 That got me thinking if there's a way to deduce that implicitly on the consumer side, i.e. if I'm pulling a github-related MCP server authored by the io.github.github domain (instead of io.github.<random-user> for example) than it's probably safe to say it's official for GitHub.

Transport Type for Packages

Agree we could take a PR on this. Add to all four spec files (server.json in free form text - any transport allowed; registry's server.json scoped down to just the officially endorsed transports; equivalent for OpenAPI specs). Not sure if @connor4312 is still planning to take that?

Custom/Vendor Metadata

Besides #81, we should have the same conversation for the server.json itself; good call: #201

Thanks! I'll start with #181 and see if I can help with these too afterwards if they are still available 👍

[tadasant]

That got me thinking if there's a way to deduce that implicitly on the consumer side, i.e. if I'm pulling a github-related MCP server authored by the io.github.github domain (instead of io.github. for example) than it's probably safe to say it's official for GitHub.

Yeah, I think downstream registries could manage this pretty well on their end. And opens up to the (valid, IMO) notion that "official" can be different in different contexts. For example, if Claude Code were to release a Claude Code Filesystem MCP server, then within the context of Claude Code users, that's the "official" filesystem MCP server. But Amp users would certainly not consider the "Claude Code Filesystem" MCP server to be the official filesystem MCP server while using Amp.

[rdimitrov]

Some may wonder if it would make sense to have that on the domain level then (differentiate between orgs vs regular users), but again it doesn't really solve that problem (just putting it here for future reference in case someone reads this and thinks of the same).

I think you're right. This should be a responsibility of the aggregators/consumers and not the registry itself 👍