Clarify relationship between server.json and MCP Server Cards#2186
Conversation
@tadasant and @dsp-ant, how about we go with : |
|
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. |
seps/2127-mcp-server-cards.md
Outdated
|
|
||
| ### 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: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
ognis1205
left a comment
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
I have some questions:
- Is
supportedProtocolVersionsnotmandatoryto be defined here in server.json (and as a consequence in server card)? - 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.
There was a problem hiding this comment.
Does anyone know if this is a good card
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I'm on the fence on making supportedProtocolVersions required --
On one hand:
- Every
remotes/packagesof 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.
There was a problem hiding this comment.
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...".
SamMorrowDrums
left a comment
There was a problem hiding this comment.
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.
|
Hi @tadasant @dsp-ant |
|
I am just going to merge this and then we going to continue discussing in the main sep. |
e8a24f9
into
modelcontextprotocol:sep/mcp-server-cards
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:
Left open was this thread:
This PR brings the SEP into alignment with that point of view by:
packagesfrom the MCP Server Cardserver.jsontoExtended MCP Server Cardand reintroducingpackagesthereI 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).