Allow for vendor extensions to registry API

@jonathanhefner

As per #39, official registry consumers will have long tail needs for other kinds of data with which they want to enrich their mirrors of the registry, while maintaining compatibility with the official registry API schema.

Quoting myself:

This is similar to how many discussions regarding the MCP specification go. There are many good ideas, but not all of them need to be encoded into the ecosystem-wide standard. MCP solves this by leaving objects open-ended and extensible, so anyone can go ahead and extend it to suit their use cases.

Taking the suggestion for readmeUrl from this lens:

I view readmeUrl as an opinionated denormalization of repository.url that only makes sense for IDE MCP Clients

Separately from the idea of a README, I think it would be appropriate to include a generic url field in the top level of the Server shape

As part of our meta-specification, we make it clear that the Registry API allows for arbitrary additional top level fields on the Server object

So when VS Code does ETL on the Registry API to populate its "VS Code MCP Marketplace", you can include a step to append a readmeUrl field. Your logic would probably be something like "if Server.url is a markdown file, use that. else if Repository.url is a GH URL, take the root README.md". Adding this field would not break compliance with our spec (nor compatibility with any SDK's or integrations that you may have written to be able to interface with the Registry API)

And @jonathanhefner had the good point:

I think allowing extension is a good idea, but allowing arbitrary top-level fields could make evolution of the official schema more difficult. If a popular marketplace "claims" a field using a particular format or semantics, there will be friction if we try to add that field to the official schema using a different format.

Instead, we could add something like a Server.vendor object, and restrict extensibility to that.

This issue is for tracking:

Finalize a proposal for what this extensions system should look like
Update OpenAPI schema to support optional extensions
Implement it in code

Some ideas for how this might be used:

Sorting signals (as above)
README URLs (as above)
Tags (Add a Tags (or labels) key in ServerDetail object #116)

Will this be only for metadata that consumers generate during ETL? Or will this also be for metadata that server authors add to target particular aggregators and clients?

@toby

It's a good clarifying question.. I saw it as the former. And I think @toby and @sridharavinash's proposal is aligned with that:

    "x-github": {
      "stargazer_count": 2723,
      "uses_custom_opengraph_image": false,
      "is_in_organization": true,
      "pushed_at": "2025-06-09T14:36:59Z",
      "opengraph_image_url": "https://opengraph.githubassets.com/2bfc402f087cd45c5fdc74b09bb25c9d6919fb51817d53220c1dd42395ce1d29/21st-dev/magic-mcp",
      "primary_language": "TypeScript",
      "name": "magic-mcp",
      "name_with_owner": "21st-dev/magic-mcp",
      "owner_avatar_url": "https://avatars.githubusercontent.com/u/199367026?v=4"
    }

The latter idea is interesting, but I would propose we leave it out of scope until we at least see what kind of x-* data starts getting put into place by registries (or someone comes in with a very compelling use case that'd be useful immediately).

Edit: Also adding my comment from Discord here:

It seems to me like using x-* is something you can decide to do without the official Registry getting involved or having a meaningful opinion. I don't think there's any particular need to namespace with domain names either -- whatever you choose is going to be localized to your registry mirror (and its consumers) and does not have to be globally unique across the whole MCP ecosystem

@dsp-ant

Yes, I think using the x- prefix is a good way to go, it's natively supported in OpenAPI as well. @dsp-ant had a good idea of using the domain as a prefix, so combining the two ideas into x-github.com seems reasonable and a way to avoid collisions.

I would propose we leave it out of scope until we at least see what kind of x-* data starts getting put into place by registries (or someone comes in with a very compelling use case that'd be useful immediately).

Sounds good. For the ETL case, I agree x-* makes sense. (And actually, I think it is good to split the cases — x-* for ETL and vendor for user-specified.)

combining the two ideas into x-github.com seems reasonable and a way to avoid collisions.

How would a collision actually manifest / is that a real concern in this context? Presumably, x-github would only exist on the GitHub mirror of the official registry. So GitHub would be in control of whether it wants to add some other details (though it's hard to imagine expanding just x-github), and would be very much in control of naming to avoid collisions, without a need for a verbose DNS-based name.

(nothing stopping you from using x-github.com anyway of course, just wondering if I am missing something)

How would a collision actually manifest / is that a real concern in this context?

Collisions are probably not a huge risk, but I do think there will be composition of registries. We may have downstream registries that want the GitHub star info for instance. It's probably more of a good hygiene issue than something super pressing.

It could also potentially be the start of hosting the schema for the extensions at a well known location on that domain.

There is some precedence to this on Azure side and use in generation of SDKs https://github.com/Azure/autorest/blob/main/docs/extensions/readme.md

Also started using this convention for Azure API Center that implements the MCP registry spec. https://github.com/Azure/APICenter-Portal-Starter/blob/mcp-registry-hack/mcp-registry/servers.json

EDIT: I think this is really targeting #201

Plausible that this is worse, but maybe something like a general 'annotations' map? Then people can reuse the same ones across registries and be more likely to coalesce on similar things.

For example it will be a pain if there's a x-github.com with its own shape, which has an icon in it. And then an x-anthropic.com with iconUrl and x-google.com with logoUri. If there was a general iconUrl or even com.github.iconUrl annotation then other providers could maybe depend on it more? (especially if there was a io.modelcontextprotocol.experimental.iconUrl that we could move things over to as the ecosystem developed).

Inspired by: https://github.com/open-telemetry/semantic-conventions/tree/main

(Appreciate this is fairly similar to the above, but something to me is different between objects under their own namespaces <> flat annotations that the convention is to use your reverse-ordered DNS)

To join up this and a couple other issues, I opened a discussion here with a concrete proposal for that tackles this and others: #284

@rdimitrov

Assigning to @rdimitrov as per conversation on Discord (but GitHub UI doesn't seem to allow me to do this, hence noting this as a comment)

Fixed in #298

Navigation Menu

Repository navigation

Allow for vendor extensions to registry API #81

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Allow for vendor extensions to registry API #81

Description

Activity

jonathanhefner commented on Jun 30, 2025

tadasant commented on Jul 1, 2025

toby commented on Jul 1, 2025

jonathanhefner commented on Jul 1, 2025

tadasant commented on Jul 1, 2025

toby commented on Jul 1, 2025

annaji-msft commented on Jul 4, 2025

domdomegg commented on Aug 7, 2025

domdomegg commented on Aug 19, 2025

domdomegg commented on Aug 20, 2025

domdomegg commented on Aug 26, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions