General solution to extensions and server.json immutability

[domdomegg]

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

There's a few threads across issues like #81, #201 and #263 that I think might be possible to solve with the below proposal:

1. Make server.json Immutable (Issue #263)

• Move registry-generated fields to namespaced extension in API responses:

{
  // ...user-provided server.json content
  "x-io.modelcontextprotocol.registry": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "published_at": "2023-06-15T10:30:00Z",
    "is_latest": true,
    "created_at": "2023-06-15T10:30:00Z",
    "updated_at": "2023-06-15T10:30:00Z"
  }
}

• Model for server.json avoids any confusing registry pollution, all official registry stuff clearly separated

2. Add Vendor Extensions Support (Issues #201 & #81)

• Both server.json and Registry API responses support arbitrary x-* fields. We encourage people to use reverse DNS namespacing for these:

{
  // ...server content
  "x-com.microsoft.vscode": {
    "readme_url": "https://github.com/owner/repo/blob/main/README.md",
    "category": "development-tools"
  },
  "x-com.mycompany.internal": {
    "approval_status": "reviewed",
    "tags": ["enterprise", "security"]
  }
}

Why reverse DNS instead of forward DNS? I don't think there's a very strong case either way, but leant towards this because it's the same format we use in names and everywhere else, so figured we should be consistent even if the consistency isn't crucial here. Reverse DNS also has a few nice properties, e.g. being able to prefix match and sort things and have similar annotations appear in the same place (e.g. x-com.microsoft.azure appears next to x-com.microsoft, but this doesn't happen with forward DNS).

3. Publisher Security Validation

• Publish endpoint only accepts x-publisher (literal) extensions, meant to be 'extensions that the publisher of this extension has added':

{
  // ...clean server.json with no other extensions
  "x-publisher": {
    "git_hash": "abcdef",
    "x-com.anthropic/marketplace-icon": "https://somesite.com/icon.svg",
    "build_timestamp": "2023-06-15T10:25:00Z"
  }
}

• Reject any other x-* fields to prevent impersonation
• Examples that would be rejected:
  • "x-io.modelcontextprotocol.registry": {...} (reserved for registry)
  • "x-com.anthropic": {...} (reduces confusion for consumers of official registry for when extensions are added, and keeps us open to allowing namespaced select providers to add trusted extension annotations to the top level official registry)
• Could put other things under x-publisher that suggest extensions downstream repos, e.g. like the Anthropic marketplace icon above, which may allow other standards to emerge/repositories to be more composable.

[domdomegg]

@claude can you review the proposal above? Read in all the context about the repo including the docs and relevant issues. Be critical, fair, honest, succinct and clear. Provide examples if helpful for understanding. You can include any non crucial, but maybe relevant extra information in <details> blocks if you think it would help the maintainers decide on the above proposal, but might be verbose/spammy to post in full.

[domdomegg]

From Claude Code:

Review of Extension & Immutability Proposal

This is a well-thought-out proposal that elegantly addresses three interconnected issues. Here's my analysis:

✅ Strengths

1. Clean Separation of Concerns

• Moving registry metadata to x-io.modelcontextprotocol.registry clearly separates user-provided content from registry internals
• Publishers can upload complete, valid server.json without registry pollution
• Aligns with general principle that registries shouldn't modify source artifacts

2. Security Model

• Restricting publish endpoint to only accept x-publisher extensions prevents impersonation
• Clear namespace ownership model reduces confusion about data provenance
• Enables controlled extensibility without compromising registry integrity

3. Forward Compatibility

• Extension mechanism allows ecosystem growth without breaking changes
• Reverse DNS namespacing provides clear ownership and reduces conflicts
• Consistent with existing MCP patterns

🤔 Considerations

Schema Migration Complexity

• Current model.go and JSON schemas have no extension support
• Need careful migration strategy for existing entries
• API versioning may be needed during transition

Implementation Questions

1. Should extensions be validated against schemas, or remain completely open?
2. How should we handle unknown extensions in older registry versions?
3. What's the size limit for extensions to prevent abuse?

Per-Package Extensions (re: @rdimitrov)
Both approaches have tradeoffs - direct per-package extensions feel more natural but add schema complexity, while the JSONPath-style approach keeps the top-level schema simpler but may become unwieldy with complex nesting. The use cases for package-level extensions aren't entirely clear yet, so this could be addressed in a follow-up once we better understand the requirements.

📋 Implementation Roadmap

If moving forward:

1. Update JSON schemas to support x-* extensions at all levels
2. Modify Go models to handle extensions (probably map[string]interface{})
3. Update publish validation to only allow x-publisher
4. Migrate existing registry-generated fields to namespaced extension
5. Update API documentation with extension guidelines

🎯 Recommendation

Proceed with the proposal - it solves real problems cleanly and positions the registry for future extensibility. The security model is sound and the separation of concerns is architecturally correct.

Consider starting with server-level extensions only to minimize initial complexity, then adding per-package/remote extensions in a follow-up if compelling use cases emerge.

[rdimitrov]

Linking a comment from a discussion where I had mentioned the vendor extensions too -

Have a generic metadata extension mechanism across servers, packages, and remotes.

My point is I think the extensions are useful not only on the high-level server object, but also per package/remote, wdyt?

[domdomegg]

Hmm I'm open to it, but I worry this adds a fair bit more complexity to the model schema. I think you could still replicate this by reflecting the same structure in a top level extensions block (but appreciate this is maybe slightly clunky). E.g.:

My understanding of your proposal:

{
  "name": "io.modelcontextprotocol/filesystem",
  "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
  // ...
  "packages": [
    {
      "registry_name": "npm",
      "name": "@modelcontextprotocol/server-filesystem",
      "version": "1.0.2",
      "x-publisher": {
        "prop": "value"
      }
    },
    {
      "registry_name": "docker",
      "name": "mcp/filesystem",
      "version": "1.0.2",
      "x-publisher": {
        "prop": "other-value"
      }
    }
  ]
}

Alternative that could communicate the same thing:

{
  "name": "io.modelcontextprotocol/filesystem",
  "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
  // ...
  "packages": [
    {
      "registry_name": "npm",
      "name": "@modelcontextprotocol/server-filesystem",
      "version": "1.0.2"
    },
    {
      "registry_name": "docker",
      "name": "mcp/filesystem",
      "version": "1.0.2"
    }
  ],
  "x-publisher": {
    "packages/0/prop": "value",
    "packages/1/prop": "other-value"
  }
}

[rdimitrov]

I guess one of the concerns is having these all nested under the top-level extension puts a bit more burden on consuming/generating them, i.e. if I remove a package I have to make sure its related extensions, if any, are removed too (the other way around is valid for consuming them).

I actually like your suggestion better. Lets start with handling this via the top-level extensions and if we see enough signal in the future we can revisit and make them per-object 👍

[tadasant]

If we were to use _meta as the mechanism for extensions in server.json, and continue the MCP-wide pattern of allowing _meta on a number of objects across the schema, it would be pretty consistent to allow _meta on any level of server.json:

{
  "name": "io.modelcontextprotocol/filesystem",
  "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
  // ...
  "packages": [
    {
      "registry_name": "npm",
      "name": "@modelcontextprotocol/server-filesystem",
      "version": "1.0.2",
      "_meta": {
        "publisher": {
           "prop": "value"
        }
      }
    },
    {
      "registry_name": "docker",
      "name": "mcp/filesystem",
      "version": "1.0.2",
      "_meta": {
        "publisher": {
           "prop": "other-value"
        }
      }
    }
  ],
   "_meta": {
    "publisher": {
       "prop": "top-level-value"
    }
  }
}

Of course, if we do pursue the stated goal of Model for server.json avoids any confusing registry pollution, all official registry stuff clearly separated, then this approach encourages exactly that pollution (though I'm not sure I'm convinced yet that this "pollution" is necessarily bad).

Regardless, we might not need to harp on that: I'm not opposed to initially only introducing _meta at the top level and deferring the decision as to whether we should include it in the nested objects until later.

Edit: See #284 (comment) - I'm not particularly confident in what would be the right solution for server.json given lack of use cases If we ignore server.json for a second and just consider that un-extendable, I think I like @domdomegg's potential solution here of the form "packages/0/prop":.

[rdimitrov]

I realised I put my comment in Discord, but missed to share it here - should we agree on having the extensions under a top-level property like meta or extensions or something similar?

[domdomegg]

I don't mind much here, and could see this keeping things cleaner.

If we do this, maybe we could use the property name _meta given that would align most with other MCP stuff?

[domdomegg]

Hmm reading more into it, maybe _meta is MCP owned but just a reserved space? ("The _meta property/parameter is reserved by MCP") So not really supposed to be for 3rd party extensions? Might go ask some spec people for clarification.

Related:

• feat: Adds _meta to additional interface types. modelcontextprotocol#710 (review)
• _meta Property on CallToolResult Use is Unclear modelcontextprotocol#264
• https://discord.com/channels/1358869848138059966/1401692887627862137/1407368526699696210

In that case using meta or extensions also seems fine.

[rdimitrov]

Good catch! In that case I assume extensions is probably better so we don't risk implicitly confuse people?

[domdomegg]

I think lets assume we'll implement it under extensions for now while we wait for clarification on the points above. Should be an easy fix to change the property name as long as we do it before go-live :)

[tadasant]

Hmm reading more into it, maybe _meta is MCP owned but just a reserved space? ("The _meta property/parameter is reserved by MCP") So not really supposed to be for 3rd party extensions?

Edit: See #284 (comment) - I'm not particularly confident in what would be the right solution here given lack of use cases

Added a comment here - I don't think it is meant to be "reserved" in that sense. The fact that it goes on to declare some keys as reserved implies that the rest of the possibilities are not reserved. In the decision between extensions and _meta, I do think we should go _meta so that there is one way of doing this kind of thing in the protocol (the _meta field is already present on so many objects in the schema).

Notably, I'm not sure the x- part of the prefix is necessary for server.json's purposes. It makes sense for the OpenAPI spec, since that's in-spec for OpenAPI, but it doesn't seem necessary to carry over that syntax to JSON schemas.

I do like the reverse DNS best practice; maybe something we could introduce for all of _meta.

[tadasant]

Taking a step back for a second - do we actually need #201 right now?

I guess it might be valuable to be clear on extensions at the server.json level, but I'm not sure what the use cases look like. I'm finding it hard to reason about what the right solution there is without having some use cases in mind.

#81, on the other hand, has some pretty clear examples:

• GitHub's downstream registry wants to surface GitHub stars on the Repository field (or perhaps on the top level server.json, though that's somewhat semantically incorrect)
• PulseMCP would want to attach its "estimated downloads" metric on the top level server.json

3. Publisher Security Validation

I'm also not sure of the use case on this. I don't think we want publishers to be able to inject arbitrary data that the registry then turns around and hosts - we're already putting in a lot of effort on sanitization and minimizing the surface area for what can be stored. And I'm not sure what the use case is for a server maintainer wanting to push their own data in their DNS namespace here.

---

Commenting further on just section "1. Make server.json Immutable (Issue #263)" and the Registry API side of "Add Vendor Extensions Support (Issues #201 & #81)" --

Make server.json Immutable (Issue #263)

I think you're right on this. This response makes sense to me, exactly as written:

{
  // ...user-provided server.json content
  "x-io.modelcontextprotocol.registry": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "published_at": "2023-06-15T10:30:00Z",
    "is_latest": true,
    "created_at": "2023-06-15T10:30:00Z",
    "updated_at": "2023-06-15T10:30:00Z"
  }
}

x- aligns with being in-spec for OpenAPI, and communicates to the consumer all the data it needs.

Indeed, it dodges wrestling with server.json-pollution, hence me thinking we can actually just skip on #201 for now.

"Add Vendor Extensions Support (Issue #81)"

Agree with the approach to the Registry API (as above). I don't think using x- would be the best way to add an analogous feature to server.json, but also think we might not need to cross that bridge right now.

---

Am I missing some use cases we'd fail to cover by skipping on those concerns right now?

[tadasant]

Upstream Collaboration: Publishers can include hints in x-publisher that help us automate our enrichment process:

Got it, that's a helpful use case. We haven't discussed the idea of pushing metadata for downstream registry to the upstream MCP Registry kind of feature before, and I think it's a good idea conceptually.

I guess there could be a risk that people put weird spammy data in these fields, but I don't think there's much incentive given clients will just ignore this (unless it matches one of their own extensions, which they can decide how to process intentionally). I think this doesn't conflict with the santisation/validation efforts we're putting into the main schema fields given those will be used by all downstream clients.

That's fair. I agree that we can allow for these x- custom extensions to have less-sanitized/secure payloads than the rest of the spec. It's up to the downstream consumers to decide whether they are spam/malicious as they consume them.

You are against the official registry /publish endpoint accepting any custom extensions when people publish servers, because of the risk of increasing surface area for people to do weird things like spam/messing with the registry generally

I misunderstood what you were proposing previously. I thought you were implying the x-publisher literal would result in x-{reverse.dns.used.to.publish} (since that's the DNS we've validated) in the registry, hence my confusion.

You've convinced me there is a good use case for this functionality, so conceptually I'm now in favor of including it.

You are supportive of the x-com.example extensions spec for the registry API responses, which would include the server.json objects.

I'm supportive of this:

{
  // ...user-provided server.json content
  "x-io.modelcontextprotocol.registry": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "published_at": "2023-06-15T10:30:00Z",
    "is_latest": true,
    "created_at": "2023-06-15T10:30:00Z",
    "updated_at": "2023-06-15T10:30:00Z"
  }
}

However I don't think we should allow this:

{
  "repository": {
    ...
    "x-com.github": {
      "key": "value"
    }
  },
  "x-io.modelcontextprotocol.registry": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "published_at": "2023-06-15T10:30:00Z",
    "is_latest": true,
    "created_at": "2023-06-15T10:30:00Z",
    "updated_at": "2023-06-15T10:30:00Z"
  }
}

You are supportive of the official registry using the above with x-io.modelcontextprotocol.registry to add registry metadata like the id, published_at, is_latest etc.

Yes.

---

(least sure about whether this accurately represents your position) You are against these extensions being baked into the server.json spec as a supported thing.

Yes. I don't think there is a need for these to be baked into the server.json spec.

Your conversation above with @rdimitrov landed on:

Lets start with handling this via the top-level extensions and if we see enough signal in the future we can revisit and make them per-object 👍

I agree with this.

And I think we could pull from your suggestion back on #263 (comment):

{
  "id": "75d362b1-0490-46e9-a3c1-f4ad2d5cb7c9",
  "serverJson": { /* the immutable server json */ },
  "registryMeta": {
    "is_latest": true,
    "published_at": ...
  }
}

I'd maybe evolve that to be:

{
  "server": { /* the immutable server json */ },
  "x-io.modelcontextprotocol.registry": {
    "is_latest": true,
    "published_at": ...
  }
}

I believe this approach would address your concern:

I can see how this could technically be different to the registry API response model for servers (e.g. server.json + extensions = registry API server model), but I'd probably want to keep them same - otherwise I worry this adds complexity to clients, who in practice will get their server data from registry APIs, so probably need to really be processing the registry API response model for server anyway...

MCP clients would not need to consume that whole payload, including both server and the x- extensions: they would just consume the server part.

The x- parts remain registry-level concerns. GitHub's, Anthropic's, PulseMCP's registries would all want to parse and consider that information, but they're not MCP clients. I don't think we have a use case for custom registry extensions flowing all the way through to the MCP Client - MCP Server interactions (and if we did, I would want us to align with _meta). The custom extensions examples we've been playing with (github_stars, verified_publisher, promoted, etc) all are registry presentation concerns and don't need to be baked into the server.json; they should be able to sit alongside it.

The main thing I want to avoid is proposing to the MCP spec that we need to have both a _meta and x-{dns} as a way to attach vendor data to objects used throughout the spec. server.json is going to be used in various MCP contexts (including the Initialize handshake, for example), of which Registry is just one concern.

[domdomegg]

Okay awesome, I think I now better understand your point about where to put the x- parts now and I think that approach makes sense. So I think the changes to make this happen might be:

Currently the get server endpoint just returns a server.json. And the list servers endpoint returns a wrapper that has a list of server.jsons. Instead we should replace the server.jsons with some wrapper of server.json like { "server": { /* the immutable server json */ }, "x-io.modelcontextprotocol.registry": { "is_latest": true, "published_at": ... } }

More concrete example

Current GET /v0/servers/{id} example response:

(effectively server.json)

{
  "description": "string",
  "id": "string",
  "name": "string",
  "packages": [...]
  // other properties from server.json here
}

Future GET /v0/servers/{id} example response:

(API wrapper)

{
  "server": {
    "description": "string",
    "id": "string",
    "name": "string",
    "packages": [...]
    // other properties from server.json here
    // 3rd party registries may NOT put extensions here
  },
  "x-io.modelcontextprotocol.registry": {
    "is_latest": true,
    "published_at": ...
  }
  // 3rd party registries may put extensions here, e.g. `"x-com.anthropic"`
}

Current GET /v0/servers example response:

{
  "metadata": {
    "count": 2,
    "next_cursor": "string",
    "total": 42
  },
  "servers": [
    {
      "description": "A server for interacting with GitHub",
      "id": "github-mcp-server",
      "name": "GitHub MCP Server",
      "repository": {
        "id": "modelcontextprotocol/servers",
        "source": "github",
        "url": "https://github.com/modelcontextprotocol/servers"
      },
      "status": "active",
      "version_detail": {
        "is_latest": true,
        "release_date": "2024-01-15T10:30:00Z",
        "version": "1.2.3"
      }
    },
    {
      "description": "Another server description",
      "id": "another-server",
      "name": "Another Server",
      "repository": {
        "id": "someorg/another-repo",
        "source": "github",
        "url": "https://github.com/someorg/another-repo"
      },
      "status": "active",
      "version_detail": {
        "is_latest": false,
        "release_date": "2024-01-10T08:00:00Z",
        "version": "0.9.5"
      }
    }
  ]
}

Future GET /v0/servers example response:

{
  "metadata": {
    "count": 2,
    "next_cursor": "string",
    "total": 42
  },
  "servers": [
    {
      "server": {
        "description": "A server for interacting with GitHub",
        "id": "github-mcp-server",
        "name": "GitHub MCP Server",
        "packages": [...]
        // immutable server.json content - no extensions allowed here
      },
      "x-io.modelcontextprotocol.registry": {
        "is_latest": true,
        "published_at": "2024-01-15T10:30:00Z",
        "repository": {
          "id": "modelcontextprotocol/servers",
          "source": "github",
          "url": "https://github.com/modelcontextprotocol/servers"
        },
        "status": "active",
        "version": "1.2.3",
        "release_date": "2024-01-15T10:30:00Z"
      }
      // 3rd party registries may add their extensions here
    },
    {
      "server": {
        "description": "Another server description",
        "id": "another-server",
        "name": "Another Server",
        "packages": [...]
      },
      "x-io.modelcontextprotocol.registry": {
        "is_latest": false,
        "published_at": "2024-01-10T08:00:00Z",
        "repository": {
          "id": "someorg/another-repo",
          "source": "github",
          "url": "https://github.com/someorg/another-repo"
        },
        "status": "active",
        "version": "0.9.5",
        "release_date": "2024-01-10T08:00:00Z"
      }
    }
  ]
}

And then I think same for the publish endpoint, where rather than sending just a raw server.json, you send a similar wrapped object. But the only x- namespace you're allowed to have is x-publisher, which is intended to be metadata that other registries will use, not MCP clients trying to connect to the server/during an init handshake.

Plus on top of this, adding a _meta property in serverJson where the publisher can put things in. I'm less clear on what the use cases for this would now be, but maybe there are use cases that I'm missing here?

Publish endpoint concrete examples

Current POST /v0/servers/publish request body:

(raw server.json)

{
  "description": "A server for interacting with GitHub",
  "id": "github-mcp-server",
  "name": "GitHub MCP Server",
  "packages": [...],
  "repository": {
    "id": "modelcontextprotocol/servers",
    "source": "github",
    "url": "https://github.com/modelcontextprotocol/servers"
  }
  // other server.json properties
}

Future POST /v0/servers/publish request body:

(wrapped server.json with publisher metadata)

{
  "server": {
    "description": "A server for interacting with GitHub",
    "id": "github-mcp-server",
    "name": "GitHub MCP Server",
    "packages": [...],
    "_meta": {
      // Publisher can include arbitrary metadata here
      // that MCP clients might use during server discovery/init
      // (i'm kinda not sure what actually would be the use case here)
      // Limited to 4KB
      "recommended_connection_timeout": "10s",
    }
    // other server.json properties
    // no extensions allowed here
  },
  "x-publisher": {
    // Metadata for other registries, not for MCP clients. Limited to 4KB
    "contact_email": "maintainer@example.com",
    "build_metadata": {
      "commit": "abc123",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    "x-com.anthropic/suggested": {
      "marketplace_icon": "https://example.com/icon.png",
      "category": ["software_development"],
      "documentation_url": "https://docs.example.org",
      "verified_publisher": true,
    }
  }
  // Publishers cannot add other x- namespaces here
}

Key differences:

• The server.json is wrapped in a "server" property
• Publishers can add a _meta object inside the server.json for metadata that MCP clients might use
• Publishers can only use the x-publisher namespace for registry-to-registry metadata
• The registry will add its own x-io.modelcontextprotocol.registry metadata when storing/serving

Flag: the 4KB number is arbitrary and made up, haven't thought too hard beyond 'seems probably large enough for most cases', and 'small enough to not be very expensive to serve'. I think it should be part of the official registry API, not part of the generic registry API spec. Could go with a different number. My guess is changing this number is pretty easy.

---

Sorry if we're still not aligned - happy to jump on a quick call (that we could record and share here so others can follow) if I've still missed something.

[tadasant]

@domdomegg we're aligned! I agree with everything you proposed there, examples are super helpful thanks for writing them.

Plus on top of this, adding a _meta property in serverJson where the publisher can put things in. I'm less clear on what the use cases for this would now be, but maybe there are use cases that I'm missing here?

I agree there is no obvious use case here and introducing it right now creates more problems (e.g. sanitizing it, documenting it, etc), so unless someone can come up with a compelling use case, I think we just omit the idea of vendor extensions inside server.json for now.

And then I think same for the publish endpoint, where rather than sending just a raw server.json, you send a similar wrapped object. But the only x- namespace you're allowed to have is x-publisher, which is intended to be metadata that other registries will use, not MCP clients trying to connect to the server/during an init handshake.

I'm not opposed to this approach (instead of my "extensions.json" proposal), but I do worry a bit if we call this file "server.json" and then it's actually the "registry server model that has a nested MCP server.json key" in practice. Maybe we'd call this file something else, like registry.json... not sure but I don't feel strongly on the details here.

[domdomegg]

Yeah I think people shouldn't get in the habit of calling the combined thing server.json, that would be confusing. registry.json seems reasonable. Or actually having extensions.json have the contents of x-publisher and then the publisher tool bundles them up for the API request. Haven't figured out what will be most ergonomic for MCP server developers - my hunch would be a single registry.json but 🤷). Think we can figure this out separately.

[domdomegg]

And also agree _meta is a bit confused, lets omit it for now.

[domdomegg]

EDIT: see the thread below for new thing we've aligned on

[outdated] Original content

Just to help unblock us and ensure @rdimitrov can get on with implementing this, I think I'm going to declare that we can go ahead and implement this, as we seem largely aligned on these points:

• Adding the x-com.example extensions spec for the registry API responses and the server.json objects from the API.
• The official registry using the above with x-io.modelcontextprotocol.registry to add registry metadata like the id, published_at, is_latest etc.
• The official registry /publish endpoint rejecting any custom extensions when people publish servers (but ideally implemented in a way that we could allowlist just x-publisher, should we want to do that in future)

Please shout if you think this is very wrong (i.e. you think implementing the above would be harmful/mostly unused - noting that we can fiddle with the smaller stuff e.g. if we should or shouldn't accept extensions into /publish later)!

[tadasant]

Adding the x-com.example extensions spec for the registry API responses

I'm aligned on this.

and the server.json objects from the API.

At the moment I still feel pretty strongly we should not do this, pending a response to #284 (reply in thread). My objection is that it creates a second way of expressing extensions in the MCP spec when the _meta approach already exists, and x- is an OpenAPI convention (so I think _meta, besides being the existing standard, is also the more appropriate modeling for a JSON schema).

The official registry using the above with x-io.modelcontextprotocol.registry to add registry metadata like the id, published_at, is_latest etc.

Aligned

The official registry /publish endpoint rejecting any custom extensions when people publish servers (but ideally implemented in a way that we could allowlist just x-publisher, should we want to do that in future)

Pending resolution to above. If we decide to not allow x- in server.json, then we still need a way for publishers to add those suggestions (without putting them inside server.json). We could either:

• Document / facilitate how they can put them into a top level _meta field
• Introduce a second file that is for "registry vendor data submissions". e.g. extensions.json to get submitted alongside server.json, mirroring the suggestion above where the server data is in a separate key from the extension data:

{
  "server": { /* the immutable server json */ },
  "x-io.modelcontextprotocol.registry": {
    "is_latest": true,
    "published_at": ...
  }
}

i.e. server comes from server.json, the rest comes from extensions.json.

[domdomegg]

Okay, I think after the discussion above we're more properly aligned! Gonna declare this as what we've aligned on and good to implement now:

---

Currently the get server endpoint just returns a server.json. And the list servers endpoint returns a wrapper that has a list of server.jsons. Instead we should replace the server.jsons with some wrapper of server.json like { "server": { /* the immutable server json */ }, "x-io.modelcontextprotocol.registry": { "is_latest": true, "published_at": ... } }

More concrete example

Current GET /v0/servers/{id} example response:

(effectively server.json)

{
  "description": "string",
  "id": "string",
  "name": "string",
  "packages": [...]
  // other properties from server.json here
}

Future GET /v0/servers/{id} example response:

(API wrapper)

{
  "server": {
    "description": "string",
    "id": "string",
    "name": "string",
    "packages": [...]
    // other properties from server.json here
    // 3rd party registries may NOT put extensions here
  },
  "x-io.modelcontextprotocol.registry": {
    "is_latest": true,
    "published_at": ...
  }
  // 3rd party registries may put extensions here, e.g. `"x-com.anthropic"`
}

Current GET /v0/servers example response:

{
  "metadata": {
    "count": 2,
    "next_cursor": "string",
    "total": 42
  },
  "servers": [
    {
      "description": "A server for interacting with GitHub",
      "id": "github-mcp-server",
      "name": "GitHub MCP Server",
      "repository": {
        "id": "modelcontextprotocol/servers",
        "source": "github",
        "url": "https://github.com/modelcontextprotocol/servers"
      },
      "status": "active",
      "version_detail": {
        "is_latest": true,
        "release_date": "2024-01-15T10:30:00Z",
        "version": "1.2.3"
      }
    },
    {
      "description": "Another server description",
      "id": "another-server",
      "name": "Another Server",
      "repository": {
        "id": "someorg/another-repo",
        "source": "github",
        "url": "https://github.com/someorg/another-repo"
      },
      "status": "active",
      "version_detail": {
        "is_latest": false,
        "release_date": "2024-01-10T08:00:00Z",
        "version": "0.9.5"
      }
    }
  ]
}

Future GET /v0/servers example response:

{
  "metadata": {
    "count": 2,
    "next_cursor": "string",
    "total": 42
  },
  "servers": [
    {
      "server": {
        "description": "A server for interacting with GitHub",
        "id": "github-mcp-server",
        "name": "GitHub MCP Server",
        "packages": [...]
        // immutable server.json content - no extensions allowed here
      },
      "x-io.modelcontextprotocol.registry": {
        "is_latest": true,
        "published_at": "2024-01-15T10:30:00Z",
        "repository": {
          "id": "modelcontextprotocol/servers",
          "source": "github",
          "url": "https://github.com/modelcontextprotocol/servers"
        },
        "status": "active",
        "version": "1.2.3",
        "release_date": "2024-01-15T10:30:00Z"
      }
      // 3rd party registries may add their extensions here
    },
    {
      "server": {
        "description": "Another server description",
        "id": "another-server",
        "name": "Another Server",
        "packages": [...]
      },
      "x-io.modelcontextprotocol.registry": {
        "is_latest": false,
        "published_at": "2024-01-10T08:00:00Z",
        "repository": {
          "id": "someorg/another-repo",
          "source": "github",
          "url": "https://github.com/someorg/another-repo"
        },
        "status": "active",
        "version": "0.9.5",
        "release_date": "2024-01-10T08:00:00Z"
      }
    }
  ]
}

And then I think same for the publish endpoint, where rather than sending just a raw server.json, you send a similar wrapped object. But the only x- namespace you're allowed to have is x-publisher, which is intended to be metadata that other registries will use, not MCP clients trying to connect to the server/during an init handshake.

Publish endpoint concrete examples

Current POST /v0/servers/publish request body:

(raw server.json)

{
  "description": "A server for interacting with GitHub",
  "id": "github-mcp-server",
  "name": "GitHub MCP Server",
  "packages": [...],
  "repository": {
    "id": "modelcontextprotocol/servers",
    "source": "github",
    "url": "https://github.com/modelcontextprotocol/servers"
  }
  // other server.json properties
}

Future POST /v0/servers/publish request body:

(wrapped server.json with publisher metadata)

{
  "server": {
    "description": "A server for interacting with GitHub",
    "id": "github-mcp-server",
    "name": "GitHub MCP Server",
    "packages": [...],
    // other server.json properties
    // no extensions allowed here, and no _meta
  },
  "x-publisher": { // literally "x-publisher", and NOT "x-<domain>"
    // Metadata for other registries, not for MCP clients. Limited to 4KB
    "contact_email": "maintainer@example.com",
    "build_metadata": {
      "commit": "abc123",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    "x-com.anthropic/suggested": {
      "marketplace_icon": "https://example.com/icon.png",
      "category": ["software_development"],
      "documentation_url": "https://docs.example.org",
      "verified_publisher": true,
    }
  }
  // Publishers cannot add other x- namespaces here
}

Key differences:

• The server.json is wrapped in a "server" property
• Publishers can only use the x-publisher namespace for registry-to-registry metadata
• The registry will add its own x-io.modelcontextprotocol.registry metadata when storing/serving

Flag: the 4KB number is arbitrary and made up, haven't thought too hard beyond 'seems probably large enough for most cases', and 'small enough to not be very expensive to serve'. I think it should be part of the official registry API, not part of the generic registry API spec. Could go with a different number. My guess is changing this number is pretty easy.

For now, we won't change the publisher CLI as we haven't quite figured out what this looks like. The two ideas floating around (I think all the names of these files are also very much subject to change):

• registry.json, which contains the registry server API model (i.e. {"server":{"name": "..."}, "x-publisher": {"stuff":"..."}}). Then publisher CLI takes this file to send to the publish API.
• extensions.json, which contains just the x-publisher content (i.e. {"stuff":"..."}). Then publisher CLI takes server.json and extensions.json as two args to send to the publish API.