Skip to content

Comments

Clarify relationship between server.json and MCP Server Cards#2186

Merged
dsp merged 7 commits intomodelcontextprotocol:sep/mcp-server-cardsfrom
tadasant:sep/mcp-server-cards-v2
Feb 14, 2026
Merged

Clarify relationship between server.json and MCP Server Cards#2186
dsp merged 7 commits intomodelcontextprotocol:sep/mcp-server-cardsfrom
tadasant:sep/mcp-server-cards-v2

Conversation

@tadasant
Copy link
Member

@tadasant tadasant commented Feb 1, 2026

Incorporating feedback from #2152 regarding the topic "how do MCP Server Cards relate to server.json". Specifically the comment left open at #2152 (comment)

Builds on #2127

Per @dsp:

I think we all agree that Server Cards should be a subset of server.json. They should have the same shape. It should be trivial to point a framework to a server.json and let it expose a server card.

Left open was this thread:

I very much agree with @localden and @maiargu. The Server card should care about exposing HTTP and only that. We should aim for minimal information not maximal information. In fact, den has me believe we don't want any local package installation mechanisms at all. We might be okay to "refer" to a the registry so that clients trusting the registry can refer to that, but not more.

This PR brings the SEP into alignment with that point of view by:

  • Removing packages from the MCP Server Card
  • Renaming the MCP Registry's server.json to Extended MCP Server Card and reintroducing packages there
  • Explaining the reasoning behind this design decision

I think the naming of "Extended MCP Server Card" is a little awkward (open to other suggestions). It feels like it would be cleaner to maximally define "MCP Server Card" with all the fields, and then constrain the remote/.well-known URI variant to be a "Remote MCP Server Card" -- but I don't feel strongly on this, so I wrote this PR from the perspective that we want to minimally design the core MCP Server Card and refer to its expansions as something else ("Extended MCP Server Card" in the verbiage of this PR).

@vyshnavigadamsetti
Copy link

vyshnavigadamsetti commented Feb 2, 2026

Incorporating feedback from #2152 regarding the topic "how do MCP Server Cards relate to server.json". Specifically the comment left open at #2152 (comment)

Builds on #2127

Per @dsp:

I think we all agree that Server Cards should be a subset of server.json. They should have the same shape. It should be trivial to point a framework to a server.json and let it expose a server card.

Left open was this thread:

I very much agree with @localden and @maiargu. The Server card should care about exposing HTTP and only that. We should aim for minimal information not maximal information. In fact, den has me believe we don't want any local package installation mechanisms at all. We might be okay to "refer" to a the registry so that clients trusting the registry can refer to that, but not more.

This PR brings the SEP into alignment with that point of view by:

  • Removing packages from the MCP Server Card
  • Renaming the MCP Registry's server.json to Extended MCP Server Card and reintroducing packages there
  • Explaining the reasoning behind this design decision

I think the naming of "Extended MCP Server Card" is a little awkward (open to other suggestions). It feels like it would be cleaner to maximally define "MCP Server Card" with all the fields, and then constrain the remote/.well-known URI variant to be a "Remote MCP Server Card" -- but I don't feel strongly on this, so I wrote this PR from the perspective that we want to minimally design the core MCP Server Card and refer to its expansions as something else ("Extended MCP Server Card" in the verbiage of this PR).

@tadasant and @dsp-ant, how about we go with :
MCP Server Card ( for server.json )
MCP Server Discovery Card (for the .well-known version)

@mgoldsborough
Copy link

The separation here is right, but "Extended Server Card" is papering over a deeper issue. Discovery and local execution are fundamentally different concerns with different consumers, different security profiles, and different update cadences. This is the same problem OpenID Connect hit before they separated Discovery from Dynamic Registration. The answer wasn't "Extended Discovery Document," it was two specs.

Rather than creating tiers of the same spec, an alternative consideration might be to keep Server Cards as pure discovery documents and let the packaging layer own runtime details like command, args, and env. MCPB already defines a manifest format for exactly this. Registries can reference packages without inlining their manifests. The "Extended" variant is essentially a package manifest that doesn't know it is one.


### Extended MCP Server Card Schema

We rename the MCP Registry's `server.json` to `Extended MCP Server Card`, and define the schema as having this shape:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm i am not sure that's needed . I think can totally just call it the Registry Card, which is based on the MCP Server Card, or just plain keep server.json. I think you are right in that Extended MCP Server Card is quite awkward.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moving it back to just server.json for now: cb9da9b

Will think more on it but I think that's a reasonable default path forward here.

Copy link

@ognis1205 ognis1205 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest renaming the "Extended MCP Server Cards" section to "MCP Server Cards Usage Beyond Remote Discovery".

By restructuring the documentation this way, we can avoid introducing a new name. Instead, we can simply present server.json as an established specification and state that we are maintaining compatibility with it.

#### Field Descriptions

1. **packages** (array of object, optional): Metadata helpful for running and connecting to local instances of this MCP server.
1. **supportedProtocolVersions** (array of string, optional): list of MCP protocol versions actively supported by this Package.
Copy link

@maiargu maiargu Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have some questions:

  1. Is supportedProtocolVersions not mandatory to be defined here in server.json (and as a consequence in server card)?
  2. Would it be clearer to define a regex pattern for the string array items?

There have been other discussions in the community about removing the release date from the server.json and mcp protocol $schema url and replace it with major version indicators. This would have as consequence the fact that supportedProtocolVersions array items could be only something like v1, v2 etc.

With a regex pattern to mention if it's a date format or a vX format it will be clearer for consumers in which direction this will go.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does anyone know if this is a good card

Copy link
Member Author

@tadasant tadasant Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is supportedProtocolVersions not mandatory to be defined here in server.json (and as a consequence in server card)?

Correct, optional in both cases.

Would it be clearer to define a regex pattern for the string array items?

Probably reasonable to include a regex that enforces this, yes. I think we can get to that kind of detail when we properly enumerate the schema in this SEP (e.g. instead of delegating out to the Registry server.json docs) after we align on the remaining open conceptual questions.

There have been other discussions in the community about removing the release date from the server.json and mcp protocol $schema url and replace it with major version indicators.

This is accomplished by the major version (v1) in the $schema: https://static.modelcontextprotocol.io/schemas/v1/server.schema.json

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I get the $schema-based versioning, but it would probably be still better to keep supportedProtocolVersions non-optional. It makes protocol compatibility explicit and gives us a clean path to multi-version support later, rather than relying on inference.

Copy link
Member Author

@tadasant tadasant Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm on the fence on making supportedProtocolVersions required --

On one hand:

  • Every remotes/packages of course has a set of supported protocol versions, whether or not it is explicitly documented
  • So it seems reasonable to require it be documented
  • This would imply a design principle like "if the value exists implicitly, it should be required in the shape"

On the other hand:

  • We are likely to make additive changes to this shape over time
  • Doing so might put us in a position where a value that exists implicitly gets added as optional to the spec for the purpose of backwards compatibility
  • And so adopting a principle of "if the value exists implicitly, it should be required in the shape" feels inevitably short-lived

So I'm inclined to advocate for a principle more like, "Server Cards will deliberately have a minimum amount of required fields, and server maintainers are encouraged to document their servers as comprehensively as made available by the shape so as to maximize compatibility and discoverability with other systems". That I think we can keep consistent over time.

I'm partially biased here knowing that making supportedProtocolVersions required here would be a breaking change to server.json - so if there another more compelling way of thinking about this I'm keen to hear it.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought again about this and I agree with you @tadasant that supportedProtocolVersions should be optional in server.json but server maintainers are still encouraged to document it.

I am thinking about the server card and well-known discovery mechanism as well, and I tend to advocate for the fact that supportedProtocolVersions in server-card does not bring additional value for the client at all in it's discovery phase.

Even if this info of supportedProtocolVersions is there in the server-card, the client would still need to negotiate the protocol version in the mcp initialization lifecycle phase, because this is how the protocol is designed. The client cannot say "we just skip initialization phase because I found in the supportedProtocolVersions a matching value...".

Copy link
Contributor

@SamMorrowDrums SamMorrowDrums left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this clears a few things up pretty well, and the security motivation for removing the local packages makes a lot of sense to me.

@maiargu
Copy link

maiargu commented Feb 10, 2026

Hi @tadasant @dsp-ant
Is the concrete scope of this PR: "Clarify relationship between server.json and MCP Server Cards" so far clarified?
Is it possible to merge this into modelcontextprotocol:sep/mcp-server-cards ?
I want to follow-up and build on this structure here and help resolving the other open discussion points of SEP-2127.

@dsp
Copy link
Contributor

dsp commented Feb 14, 2026

I am just going to merge this and then we going to continue discussing in the main sep.

@dsp dsp merged commit e8a24f9 into modelcontextprotocol:sep/mcp-server-cards Feb 14, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants