Thank you for curating the discussions from the document and creating this update. The original proposal was a strawman and I am happy for all the improvements discussed.

In general I agree with the points made, specifically:

server.json

I am okay with aligning as close as possible to server.json and might make it a strict subset. We might need to carefully consider if we want ALL fields. For example, environmentVariables or runtimeArguments, even when not containing values, might still reveal information you might not want to share publicly. Imagine having an INTERNAL_BILLING_API_KEY, this might get attention from attackers that would otherwise be harder to find. Similarly URL templates might be able to reveal to attackers something about your isolation boundaries.

supportProtocolVersions, authentication

• I am happy with changes to supportedProtocolVersions, authentication etc. If we can align with server.json, we should. Lots of it makes sense. The only change i am less sure is about handling instructions.

dynamic

Regarding dynamic: I understand the concern. I we consider the toolset to be dynamic by default, we don't allow for the scenario where a server has a static toolset, that the client wants to optimize for (e.g. never running any discovery of tools). I think the best here is to allow for a combination:

• static toolset is an array of tool/prompt/resource descriptions. E.g. [{"name": ..., "description": ... }, {"name": ..., ...}]
• partial dynamic toolset is an array of tool/prompt/resource descriptions + a singular entry of "dynamic". E.g. [{"name": ..., "description": ... }, {"name": ..., ...}, "dynamic"]
• fully dynamic: is an array with no static tool/prompt/resource descriptions, only a singular entry dyanmic. E.g. ["dynamic"].

singular server card vs multiple

This is an interesting one. You propose one server-cards.json which contains multiple servers. This is great for clients, since one requests gives you everything. But it has a few problems:

• Caching is invalidated once one of the servers changes
• File can get very large and a client that is interested in only one server must fetch everything.
• Server maintainers must coordinate updates to one file
• Individual frameworks can't just auto-generate it anymore since it needs to be coordinated.
• One malformed card blows up all the other servers

The alternative is using one file per server, similar to OAuth Metadata RFC 8414 and uses some form of postfix to distinguish when multiple servers exist. The catalog of all servers on the domain (and subdomains) would be served via ai-cards.json as a simple index.
The good part is that it allows frameworks to automatically generate the cards, allows for caching per server, and basically solves most of the problems above, with the drawback of one more indirection. If you are a crawler or browser you must then enumerate all of them at the same time.

I personally prefer the one-server-card per server variant over all in one file.

How should we proceed? Do you want to iterate on this via PRs or should we go back to a google doc?

How should we proceed? Do you want to iterate on this via PRs or should we go back to a google doc?

I think pushing this forward in PRs at this stage would be productive. A lot of folks have been referencing and trying to start discussions on top of the proposed shape on #2127 (previously #1649), so I think it would help keep feedback coming on the right topics by updating the "front page" of this SEP ASAP with the latest points on which we have alignment.

IMO it also helps ground discussions by forcing discussion and proposals in the form of "what would XYZ idea actually look like in the final SEP / as an iteration on the current draft".

Could we try to land this PR, minus anything still controversial, then continue on in follow on PRs and/or inline comments on #2127 to resolve the remaining controversies and additive points? In particular I think landing the "server.json alignment" points would help steer discussions in a helpful direction.

I am okay with aligning as close as possible to server.json and might make it a strict subset. We might need to carefully consider if we want ALL fields. For example, environmentVariables or runtimeArguments, even when not containing values, might still reveal information you might not want to share publicly. Imagine having an INTERNAL_BILLING_API_KEY, this might get attention from attackers that would otherwise be harder to find. Similarly URL templates might be able to reveal to attackers something about your isolation boundaries.

What is your view on where the responsibility of AI Cards ends and MCP Server Cards begins?

I would propose: AI Cards are for discovery, MCP Server Cards (and also server.json) are for configuration and connection.

To that end, I'm not fond of omitting environmentVariables or runtimeArguments from Server Cards, because if you don't have that data as an MCP Client, you are blocked from actually configuring and connecting to the server.

I understand the potential for environment variables and runtime arguments being a security exposure vector, but wouldn't that kind of detail only be risky to non-public servers anyway? And any non-public server could choose to advertise its Server Card solely on a non-public intranet. Would love to understand examples to the contrary if I'm not grokking this properly.

supportProtocolVersions, authentication

• I am happy with changes to supportedProtocolVersions, authentication etc. If we can align with server.json, we should. Lots of it makes sense. The only change i am less sure is about handling instructions.

I don't feel strongly on instructions - happy to add it back if you want it in this PR, or otherwise let's pin it as a follow on item. I think it'll be easier to make additive changes as follow ons so am biased to leaving it out for now.

dynamic

Regarding dynamic: I understand the concern. I we consider the toolset to be dynamic by default, we don't allow for the scenario where a server has a static toolset, that the client wants to optimize for (e.g. never running any discovery of tools). I think the best here is to allow for a combination:

• static toolset is an array of tool/prompt/resource descriptions. E.g. [{"name": ..., "description": ... }, {"name": ..., ...}]
• partial dynamic toolset is an array of tool/prompt/resource descriptions + a singular entry of "dynamic". E.g. [{"name": ..., "description": ... }, {"name": ..., ...}, "dynamic"]
• fully dynamic: is an array with no static tool/prompt/resource descriptions, only a singular entry dyanmic. E.g. ["dynamic"].

I'd love to bring @connor4312 @SamMorrowDrums @Fannon all into discussing this further; though I left the possibility for dynamic unchanged in this PR, so if an immediate goal is to land this PR then I think resolving this discussion is not yet blocking.

singular server card vs multiple

This is an interesting one. You propose one server-cards.json which contains multiple servers. This is great for clients, since one requests gives you everything. But it has a few problems:

• Caching is invalidated once one of the servers changes
• File can get very large and a client that is interested in only one server must fetch everything.
• Server maintainers must coordinate updates to one file
• Individual frameworks can't just auto-generate it anymore since it needs to be coordinated.
• One malformed card blows up all the other servers

The alternative is using one file per server, similar to OAuth Metadata RFC 8414 and uses some form of postfix to distinguish when multiple servers exist. The catalog of all servers on the domain (and subdomains) would be served via ai-cards.json as a simple index. The good part is that it allows frameworks to automatically generate the cards, allows for caching per server, and basically solves most of the problems above, with the drawback of one more indirection. If you are a crawler or browser you must then enumerate all of them at the same time.

I personally prefer the one-server-card per server variant over all in one file.

These are all fair points, and revisiting this I'm realizing that if we assume ai-cards.json/ai-catalog.json exists as a thin discovery layer (@Fannon basically said the same thing here), you're right there is no reason to have multiplicity at the /mcp/server-card.json layer. I've updated this PR to go back to singular cardinality: 17c1af3

I dropped .json from the .well-known URI scheme to better align with the RFC 8414 postfix convention; I think that's a reasonable simplification?

One more follow up item I forgot to include in my original enumeration at the top --

Should primitives and capabilities live at the per-remote/package or top level per-server-card?

@ggoodman brought up here that it may make sense to allow these to vary on a per-remote (he called it per-endpoint) basis. I think the same argument could be applied to per-package.

To make it more concrete, take Postman's remote MCP server as an example. It is conceptually one MCP server (and so I pretty strongly think it should be represented by one MCP Server Card), but it has multiple remotes that live at e.g. https://mcp.postman.com/minimal vs. https://mcp.postman.com/code. They would have very different tools; so it feels off for them to present one MCP Server Cards with these URLs in separate remotes but sharing a single set of tools.

My take: at some point, we need to draw an opinionated line on "What do we define as one MCP Server that deserves one MCP Server Card", and I think requiring that one server have shared definitions of resources, tools, prompts, capabilities, requires, and icons all makes sense.

I felt comfortable moving authentication up to being per-remote because authentication is a sort of transport-adjacent/connection detail; unlike the others that define a server's runtime functionalities. But I acknowledge this is pretty opinionated so I'd be curious to hear more feedback on this point (doesn't have to be before we land this PR).

In Discord, @dsp-ant said

Where the original proposal diverged from server.json, we should just use the server.json way, e.g. InitializeResults should not be in there, etc.

I removed the Q&A bit: a843cb4

I think the other mentions of initialization still hold? Happy to try reworking if you think any of them are misleading.

@tadasant thank you very much for creating this and moving it forward! It would be really great to get MCP Server Card and registry server.json together.

Regarding dynamic: I understand the concern. I we consider the toolset to be dynamic by default, we don't allow for the scenario where a server has a static toolset, that the client wants to optimize for (e.g. never running any discovery of tools). I think the best here is to allow for a combination:

@tadasant - my thought here was that we already have capabilitites for the server and whether tools are dynamic could be put there as a boolean. Then we don't mix the concern of expressing a capability with describing what tools are available. But we can also defer working this out as I understand that this is a more debated decision.

singular server card vs multiple

you're right there is no reason to have multiplicity at the /mcp/server-card.json layer. I've updated this PR to go back to singular cardinality:

This would already be resolved and handled by the AI Cards standard, where you could anyway get multiple agents and MCP servers per host. Agree that it should be one MCP Server Card per server. One host / domain can have any number of MCP Servers, so the .well-known has to basically provide a list of URLs, which individually can be accessed, cached etc.

That's why the MCP Server Card format itself (as JSON) should be singular (describe one MCP server per JSON file), but you can't put it under a single URL under a single host like /mcp/server-card.json.

See also

• SEP 0014 - AI Card Discovery Agent-Card/ai-card#14

I understand the potential for environment variables and runtime arguments being a security exposure vector, but wouldn't that kind of detail only be risky to non-public servers anyway?

If those fields are optional then it's always possible to publish a public and an internal metadata file (which contains more information). The latter would need to be protected.

I felt comfortable moving authentication up to being per-remote because authentication is a sort of transport-adjacent/connection detail; unlike the others that define a server's runtime functionalities.

Added some inline comment on this

I think @rreichel3 would also be interested in the dynamic conversation as OpenAI (and others) is bringing MCP Apps to less technical consumers, the reality is that they require the outer boundary of what a server can do to be pre-specified otherwise they have to reject servers that do dynamic things outright for protection of end users (such as vetting actions servers can take as part of App review), and so rather than fragment MCP where dynamic and static are not able to coexist for some clients, I really think the ability for a server to superset its maximum capabilities and reduce them at runtime when applicable would reduce the risk of needless rejection of dynamic behaviours.

This doesn't have to be addressed by server cards, but they do feel like an appropriate place. That said, perhaps servers that provide dynamic functionality that is only a subset at runtime can (and should), put the full capability of the server in the server card, and should not need dynamic? WDYT? I still have other thoughts, but I think at least for GitHub's server we could enumerate all MCP primitives that can be hidden by policy, user access or modes/headers etc.

I really appreciate the opportunity to feed into this and thank you @tadasant for your meticulous tracking of the various groups/themes of feedback!

If those fields are optional then it's always possible to publish a public and an internal metadata file (which contains more information). The latter would need to be protected.

The fields like environmentVariables and runtimeArguments are certainly optional in the schema, but my point there is that removing them defeats the purpose of publishing the Server Card in the first place -- if a client gets the Server Card, it still doesn't have the information it needs to run the packages entry that is missing those fields. And so at that point, why have it discover the Server Card at all?

Alternatively, we continue to recommend Server Cards be complete configs (environment variable names and all), and the way you protect them is by controlling access to the Server Card. Your AI Card can advertise that a sensitive server card exists on some internaldomain.com/.well-known/mcp/server-card/server-with-secret-variables, and only authorized users can actually GET that URL.

I think I replied to your other points inline @Fannon; let me know if I missed anything.

I think @rreichel3 would also be interested in the dynamic conversation as OpenAI (and others) is bringing MCP Apps to less technical consumers, the reality is that they require the outer boundary of what a server can do to be pre-specified

Thanks for the tag @SamMorrowDrums ! This is correct, we would prefer a mechanism to get the entire range of possibilities from an MCP Server. Currently we freeze the MCP Schema when an app is submitted to our ecosystem, then we only update the schema when a new version is submitted (and we review it). For our App system, we don't support dynamically exposing tools to the model. I could see the value in us migrating to cards if there was a static card we could consume instead.

Instructions as a field in the Server Card

Quick follow up in support of adding plain text information on the MCP server — not necessary for a human, more for Claude et al. to add the server.

Many MCP's come with complicated multi-step setups (e.g., BigQuery, AWS) or dynamic URLs (e.g., Hex). Providing both the user and Claude guidance on how to set up complex servers is a massive reduction in the friction of it not working for end users.

Instructions as a field in the Server Card

Quick follow up in support of adding plain text information on the MCP server — not necessary for a human, more for Claude et al. to add the server.

Many MCP's come with complicated multi-step setups (e.g., BigQuery, AWS) or dynamic URLs (e.g., Hex). Providing both the user and Claude guidance on how to set up complex servers is a massive reduction in the friction of it not working for end users.

I like this use case of "setup instructions" and think it's a worthwhile discussion to have (currently, websiteUrl has been kind of a stand in for this functionality in what I've seen across the ecosystem); though I think instructions in the context of this SEP so far is actually referring to Server.instructions, which is slightly different.

Sounds like we are close, just stuck on #2152 (comment) -- I've pinged Den and if any security-forward folks are reading, would appreciate more opinions on this.

Summary of the question --

• We currently have this server.json shape we use for statically defining servers in the Registry
• Conceptually, this is the same concept that we want to bring to the decentralized internet for discovery/connection via e.g. .well-known paths
• It's a no-brainer for remotes, where we just need a place to advertise a URL and some basic metadata
• We've agreed that we also want to advertise local implementations alongside the remotes. So an MCP client can, for example, agentically discover an MCP server but then choose to download a docker image and run it locally instead of necessarily performing all operations over an OAuth'd connection to a remote server
• Where we're stuck: is it a security concern to expose local server configuration details via a .well-known endpoint? This is details like environmentVariables names and runtimeArguments formatting.

My position is that by omitting any details, we break the ability to actually connect to these servers (the connection just won't work if we omit a required environment variable name or runtime argument). And on the security front, I would expect maintainers to guard their Server Card if it contains truly sensitive information (which is not the case for any of the thousands of servers published with these details on GitHub, nor for the many local servers documented on official docs pages of various SaaS's). But I acknowledge I would have a gap in properly understanding deeper enterprise scenarios here.

• Where we're stuck: is it a security concern to expose local server configuration details via a .well-known endpoint? This is details like environmentVariables names and runtimeArguments formatting.

In its current form the server.json provides remotes (service endpoints that an agent can connect to), and packages (instructions for an agent to install, run, and connect to an instance of a server). The latter is where this potential security concern arises.

A package entry really amounts to a description of how to install and run the MCP server software package, and many vendors have chosen to provide this option in their published registry entries. I would argue (being very familiar with that data) that in no case was the registry server.json the first disclosure of any configuration details. Because this is installable software, and almost entirely open source, those details were already exposed in their repos, generally in the README.md. The server.json has made it easier for my agent to install, configure, and run these servers, but all it really did was remove the previous step of going to the repo and reading the README (or worst case, looking at the code).

And packages are optional. If a publisher decided that they only wanted a particular ServerCard to contain information for the endpoints hosted there (or by that entity), the are free to omit packages from that ServerCard (and potentially still publish them to the registry). That doesn't require changing the shape of the server.json/ServerCard.

Leaving packages and their details (including environment var names and runtime arguments) allows ServerCard publishers to include those details if they want to (and we know from published registry entries that many publishers elect to do that). And again, I am not aware of a single case where the server.json is the first or only disclosure of that data.

I'm a big fan (as a consumer of server.json, and soon ServerCards) of keeping these shapes aligned, and as a potential publisher, of allowing expression of packages (and their configuration) in my ServerCard.

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.