Just adding a note of context for any readers here that as of the current commit, this is the text of the original SEP proposal, but a lot of folks have contributed feedback to the specifics of reworking the shape in this Google Doc.

Pasting here for readability:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  "name": "io.modelcontextprotocol.anonymous/brave-search",
  "description": "MCP server for Brave Search API integration",
  "title": "Brave Search",
  "websiteUrl": "https://anonymous.modelcontextprotocol.io/examples",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/servers",
    "source": "github",
    "subfolder": "src/everything"
  },
  "version": "1.0.2",
  "supportedProtocolVersions": [ "2025-03-12", "2025-06-15" ],
  "icons": [ ... ],
  "remotes": [ ... ],
  "packages": [ ... ],
  "capabilities":  { ... },
  "requires": { ... },
  "resources": [ ... ],
  "tools": [ ... ],
  "prompts": [ ... ],
  "_meta": { ... }
}

Most significant sticking points so far:

• Proper integration point with server.json
• Relationship between this work and Agent Card
• Whether dynamic is an appropriate tools (and other primitives) field value

The rest is largely just details we can bikeshed.

I think it's important to design this so we introduce no breaking changes to server.json, as any breaking changes would cause major problems for a lot of production registry-related infrastructure and systems in the ecosystem. So my high level thinking would be to:

• Adopt server.json as-is exactly as a Server Card, perhaps with additive changes like tools
• Figure out the right integration point with Agent Card (probably put Server Card in their flexible services field)
• Then everything else is just a matter of placement in .well-known, initialization sequence, etc. No controversy around deduplication or breaking changes in modeling.

I also liked @yoannarz's points here that there is a use case for non-owners of MCP servers to use Server Cards. So if we're going to require Server Cards to be comprehensive descriptors of all the capabilities of a server that only a server owner can advertise, we still have a gap like "how do I as a restaurant owner advertise that Yelp's MCP server is the way to make bookings on my website; I don't actually control the details of its tools and capabilities but I know where it lives and want to put that on my website's .well-known"

So maybe there is a path where we make Server Card a strict subset of server.json to elegantly fulfill all the above (e.g. perhaps Server Cards = purely Discovery concerns; then server.json is Discovery+Capabilities); will think more on that and circle back.

Shall we also add an optional extended card for ancillary information (such as additional metadata)?

@tadasant It would be great if we can avoid getting two different formats. Instead we could extend the MCP Registry server.json to also cover the requirements that came up here. Then an MCP Server Card would basically be conventions of what has to be provided (required) for describing remote MCP Servers.

The discovery mechanism (.well-known) could be moved to the AI Card initiative, then MCP and A2A (potentially also other AI protocols) could share the discovery mechanism and providers / registries can use one instead of multiple.

For this, I just drafted a SEP in AI Cards: Agent-Card/ai-card#14

My colleagues Vyshnavi and Raluca prepared a JSON Schema of how the MCP Server Card could look like if we combine it as hinted at above. This may help to see if we can get this together.

In discussions with @dsp-ant the question came also up if we need two formats or not. As stated, we should not have two different formats to describe an MCP Server for the same protocol. But the registry itself may have additional information, so for consumers of the registry it is plausible to have a superset model of what the registry provides (like calculated properties, more context). I would keep this separate from the format for self-description and publishing to keep that as simple as possible.

@dsp-ant Hi David
as discussed, here is a PR with the JSON schema to better discuss on the code directly maiargu/registry#1

fyi @tadasant

@dsp-ant to help drive this forward, I've opened a PR against your branch here.

If you are aligned with the direction it's going, could we get it merged and then continue community discussion on the remaining open questions (more detail below)?

I'm happy to formally sign on as sponsor for this or as an author if helpful.

I've taken into account all the feedback from:

• The discussion on the original SEP Issue
• Ensuing discussion on a Google Doc bikeshedding the shape
• @maiargu and @Fannon's recent PR
• Some consideration of the direction AI Cards are going

Big thank you to @ggoodman, @PederHP, @sdatspun2, @connor4312, @SamMorrowDrums, @Fannon, @maiargu, @electrocucaracha, @ibuildthecloud, @yoannarz, @pcarleton and everyone else commenting and contributing so far; the feedback is all helping progress this forward.

I have avoided iterating on some of the more controversial topics, like dynamic as a value option for primitives, so we can hopefully land this quickly and have separate longer-running discussions on those sticky points.

Pasting the rest of the text from my PR for readability here:

Some highlights worth pulling out

Relationship to AI Card

The AI Card standard is paving a path to providing a protocol-agnostic .well-known path and file format for discovering services. They are planning to serve a list of AI Cards at .well-known/ai-catalog.json.

MCP Server Cards will provide a richer, MCP-specific definition that can be used by MCP clients to actually connect and start performing MCP operations. We will store these values at .well-known/mcp/server-cards.json.

Example:

• "Restaurant A" works with platform "Restaurant Reservations SaaS" to provide MCP-powered bookings for their restaurant
• Restaurant A also works with platform "Jobs SaaS" to provide MCP-powered job listings to prospective job seekers
• Restaurant A would advertise the two relevant AI Cards at restaurant-a.com/.well-known/ai-catalog.json
• Restaurant Reservations SaaS would have many Server Cards at restaurant-reservations-saas.com/.well-known/mcp/server-cards.json, including entries for each of Restaurant A, Restaurant B, etc.
• Jobs Saas would have many Server Cards at jobs-saas.com/.well-known/mcp/server-cards.json, including entries for each of Restaurant A, Coffee Shop B, etc.

We can develop and iterate on MCP Server Cards largely independently from the broader effort to integrate with AI Cards, as long as we maintain some integration point so it is possible to understand when an entry in an AI Card references an MCP Server Card that is hosted and maintained elsewhere.

Instructions as a field in the Server Card

@PederHP had a good point here.

I think it's reasonable to consider, but we don't have it in server.json right now and it doesn't seem particularly critical to have blocking discussions on; I think we should leave it out for now. I've removed it in this PR.

supportedProtocolVersion

I've moved this field inside the remotes field, per discussion with @ggoodman here.

I think it would be reasonable to consider removing this from the SEP to simplify, as we don't currently have it in server.json so we'd be trying to collect feedback on use cases as we try to land this higher level piece of work in Server Card.

authentication

I've also moved this field inside the remotes field. My firsthand experience is that it is very common for different remotes entries to have different valid auth methods, so I think it would be a big shift for the ecosystem to consider authentication a top level Server Card concern.

Some topics I think we should continue discussing (but out of scope for landing this PR) into the SEP --

Removing $schema from server.json and not including it in Server Card

I've removed the explicit $schema field in this PR. We were planning to do this for the MCP Registry in the next iteration of server.json (rationale here, cc @rdimitrov). Basically, hardcoding the $schema field there introduces an unnecessary breaking change across versions, when we don't have intention to make breaking changes to these shapes.

A better solution here would probably be to use something like @vyshnavigadamsetti's suggestion of mcpCard: "1.0" that wouldn't needlessly create breaks with every (non-breaking) change.

Removing dynamic as an option in tools/primitive values

There is pretty significant community opposition to including dynamic as a possible value. @connor4312, @SamMorrowDrums, @Fannon, @sdatspun2 have all expressed their reasoning against it (link, link).

Removing the spec language around serving Server Cards as a resource

I left it as-written in the SEP for now, but there is motivation to have this removed

Placement of .well-known path

I didn't flesh this out further in this PR, but we should probably incorporate the thinking from @pcarleton and @simonrussell (link, link) explicitly into our language.

Thanks for driving this forward!

Just a quick question for clarity, there was a PR previously opened for community feedback iteration.
Would you prefer that further feedback and iteration happen directly on this PR, or should we continue using separate iteration PRs as before?

Happy to align with whatever works best for you and the group.

Thanks for driving this forward!

Just a quick question for clarity, there was a PR previously opened for community feedback iteration. Would you prefer that further feedback and iteration happen directly on this PR, or should we continue using separate iteration PRs as before?

Happy to align with whatever works best for you and the group.

My suggestion (feel free to direct us otherwise @dsp) would be that going forward, now that we have solid high level alignment, folks should open PRs for discrete sub-topics. For example, one PR proposing dynamic value changes, another PR expanding on the relationship between server.json and Server Cards, another PR perhaps workshopping instructions, and so on.

Then David can choose what he wants to pull it on a topic by topic basis and/or make changes to the SEP directly himself.

Open threads worth iterating on:

1. Registry server.json vs. Server Card expansion (we aligned on strict subset here but didn't add that conclusion directly to the SEP wording yet), document differences / reasoning [Edit: https://github.com/Clarify relationship between server.json and MCP Server Cards #2186]
2. Whether to have dynamic as a value in tools/primitives
3. Server instructions
4. Should primitives and capabilities live at the per-remote/package or top level per-server-card?
5. Is allowing for any headers in remotes too permissive? Probably same question for templating in the URL.
6. Drop .json suffix from the Resource distribution / do we still want Resource distribution?
7. Clarity around the structure of name (it's fairly clear in server.json spec but important enough I think it should be more prominent in this SEP with guidance on conventions) [Edit: WIP]
8. Clarity around .well-known placement, especially with respect to suffixing for multiplicity [Edit: WIP]

I think each of these could be separate PRs. I'll definitely work on (1) very soon, and can draft more if other folks don't jump on them first.

Edit: and maybe some of the smaller changes that are pretty constrained to modifying just one section of the SEP could be made directly as comments and discussed as threads, PR might be overkill for all of them.

Thanks for the suggestion, @tadasant .

This makes sense to me. Breaking things down into discrete PRs per sub-topic feels like the right next step now that there's high-level alignment.

I'd also be interested to see a bit more community feedback on this approach, and then I'd be happy to help review or contribute where it's most useful.

Looking forward to the follow-up PRs!

I opened #2186 as a follow up to @dsp's comment

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.

In the meantime I'll start working on a PR for:

• Clarity around the structure of name (it's fairly clear in server.json spec but important enough I think it should be more prominent in this SEP with guidance on Community feedback iteration (rev 1) on SEP-1649 (MCP Server Cards) #2152 (comment))
• Clarity around .well-known placement, especially with respect to suffixing for multiplicity

Edit: that PR^ is somewhat intertwined with AI Card discussions, so will likely see where those land before putting something up here.

I tried to clarify the reverse-DNS namespacing for name field and _meta keys in the registry docs.

Some ambiguity around reverse-DNS namespacing surfaced during discussions about the name field and .well-known path suffixes, so this PR aims to make the intended conventions explicit without changing behavior:

modelcontextprotocol/registry#926

Please let me know if this matches the intended interpretation.

Thanks for the thoughtful work on this proposal! (let me know if this feedback/comment is better suited for a different PR)

Wanted to raise a scenario we're seeing frequently in practice. We’re working with many small services businesses (gyms, home services, restaurants, spas..etc) to stand up MCP servers or MCP Apps for their business. A large number of these businesses run their websites on hosted platforms like Wix, or Squarespace, and similar builders. They own their custom domains, but many don't have the ability to place arbitrary files at .well-known paths, that's controlled by their hosting platform.

Some more advanced hosting setups for WordPress sites could likely serve files from .well-known paths. But fully managed platforms like Squarespace and Wix don't expose filesystem level control to their users. And I don't believe this is something a plugin or app on those platforms could solve either with .well-known path routing being below what third-party apps would have access to in most website hosting platforms.

These businesses are building capabilities like bookings, availability, quotes..etc and will want to adopt server cards to enable better discoverability of their tools, but likely won’t be able to without support from their website hosting platform (which could prioritize platform specific features versus the range of saas products that the small business might be using to enable their tools).

I might be misunderstanding how the .well-known mechanism would work in practice for these platforms or businesses, if so would appreciate any guidance!

Just wanted to raise this scenario and consideration to small services businesses building MCP capabilities and looking to evolve with new standards for discoverability.

Excited to see this specification moving forward!

On our end, we have a strong need to support localized titles and descriptions for MCP servers. The goal is to dynamically display server metadata (e.g., title/description) in the user’s preferred language, which would significantly improve UX by making the interface more accessible and user-friendly.

Would it make sense to extend the current schema to accommodate localized fields? For example, we could modify the description field (and similarly for title) to support either:

• A plain string
• A dictionary of localized strings, where keys are RFC 5646 language tags (e.g., en-US, fr-FR) and values are the localized strings.

"description": {
  "oneOf": [
    { "type": "string" },
    {
      "type": "object",
      "additionalProperties": { "type": "string" },
      "description": "Keys must be valid RFC 5646 language tags (e.g., 'en-US', 'fr-FR')."
    }
  ]
}

To ensure consistency, we should also apply this localization pattern to tool metadata (title and description). This would allow MCP hosts to display tool information in the user’s language, aligning with the broader goal of a localized UX.

Happy to discuss about it and see if others feel the need of localization.

Excited to see this specification moving forward!

On our end, we have a strong need to support localized titles and descriptions for MCP servers. The goal is to dynamically display server metadata (e.g., title/description) in the user’s preferred language, which would significantly improve UX by making the interface more accessible and user-friendly.

Would it make sense to extend the current schema to accommodate localized fields? For example, we could modify the description field (and similarly for title) to support either:

• A plain string
• A dictionary of localized strings, where keys are RFC 5646 language tags (e.g., en-US, fr-FR) and values are the localized strings.

"description": {
  "oneOf": [
    { "type": "string" },
    {
      "type": "object",
      "additionalProperties": { "type": "string" },
      "description": "Keys must be valid RFC 5646 language tags (e.g., 'en-US', 'fr-FR')."
    }
  ]
}

To ensure consistency, we should also apply this localization pattern to tool metadata (title and description). This would allow MCP hosts to display tool information in the user’s language, aligning with the broader goal of a localized UX.

Happy to discuss about it and see if others feel the need of localization.

Hi @HenriChabert I think a minor update to the streamable HTTP spec that simply proposes servers CAN respond dynamically to the Accept-Language header (most MCP clients support setting custom headers and actually host applications could send system languages here), and server cards could of course also be served based on standard HTTP content negotiation using the same process. STDIO servers I think can handle it via direct configuration or language packs. GitHub MCP for example enables ability to export and override descriptions for STDIO.

I have written a PR #2355 that simply adds a reference to using existing http i18n standards to produce locale friendly MCP content. It's one of the features that is both implicit in the spec as it just extends HTTP, but is also under-utilized so I think an explicit mention is a good idea.

WebMCP Support in Server Cards

WebMCP tools are registered client-side after navigation, acting as an MCP server. We should support WebMCP in Server Cards.

Proposal

Add "webmcp" as a remotes[].type

• url is a navigation entrypoint (page/path), not a transport endpoint. Activation is post-navigation.
• Each remote entry should include name, title, and description, mirroring MCP's Implementation type. This is important for WebMCP because tools can't be enumerated pre-connection (available at runtime, often behind auth). The description is the signal agents have to understand what tools are available and to understand multiple entry points on one domain. The addition of description benefits all types, although it is necessary for WebMCP.

iframe isolation

• Tools from an embedded iframe must not be treated as tools of the embedding origin in Server Cards.
• An iframe origin exposing tools must have its own Server Card.

Discovery

• /.well-known/mcp/server-card serves as the discovery mechanism for WebMCP alongside standard remotes.
• A single card may include multiple webmcp entries (different paths).

Note: While WebMCP lists discoverability as a non-goal, Server Cards fill could fill gap from the MCP side.

Example

{
  "name": "com.example.site",
  "version": "1.0.0",
  "title": "Example Site",
  "description": "WebMCP page tools at example.com.",
  "websiteUrl": "https://example.com",
  "remotes": [
    {
      "type": "webmcp",
      "url": "https://example.com/mail",
      "name": "com.example.mail",
      "title": "Example Mail",
      "description": "Email client. Tools for composing, searching, and managing messages.",
      "supportedProtocolVersions": ["2025-06-15"]
    },
    {
      "type": "webmcp",
      "url": "https://example.com/sheets",
      "name": "com.example.sheets",
      "title": "Example Sheets",
      "description": "Spreadsheet editor. Tools for creating and analyzing spreadsheet data.",
      "supportedProtocolVersions": ["2025-06-15"]
    }
  ]
}

Happy to iterate on the details.

Follow-on SEP: Payment Awareness Extension

Following the discussion here about keeping Server Cards minimal and deferring specialized concerns to follow-on SEPs, we've been prototyping a payment awareness extension at neul-labs/mcp-pay.

The Gap

Agent-to-service payments are fragmenting across incompatible discovery layers:

• x402 Bazaar — discovers services only after a payment occurs, x402-only
• Tempo MPP — closed network discovery
• MCP Registry — no payment awareness

There's no rail-agnostic way for agents to discover pricing before connecting.

Proposal: /.well-known/mcp/pay.json

Since you're registering .well-known/mcp as an umbrella with IANA, we'd propose payment metadata live alongside the server card:

/.well-known/mcp/server-card.json ← identity, remotes, capabilities
/.well-known/mcp/pay.json ← pricing, payment rails, SLA

Minimal schema:

{
  "mcp_pay": "0.1",
  "pricing": {
    "default": { "model": "free" },
    "tools": {
      "expensive_tool": { "model": "per_call", "amount": "0.01", "currency": "USD" }
    }
  },
  "accepts": [
    { "rail": "x402", "network": "eip155:8453", "asset": "USDC" },
    { "rail": "lightning", "lnurl": "lnurl1..." }
  ],
  "payment_sla": {
    "settlement_time_seconds": { "x402": 2, "lightning": 5 },
    "refund_policy": "full_refund_on_failure"
  }
}

Why Separate?

Respecting the design principle that led to removing primitives:

1. Not every server needs it — free servers simply don't serve pay.json
2. Different dynamics — pricing may update independently of identity
3. Specialized concern — avoids bloating the core spec

We have a https://github.com/neul-labs/mcp-pay with HTTP 402 flow working against x402. Happy to draft a formal follow-on SEP once Server Cards stabilizes, or iterate on the schema based on feedback here.

I opened a PR with a few cleanups from our WG discussion last week and an attempt to fully align server.json with Server Card: #2443

From the PR:

• description → required: Matches the existing server.json schema where description is in the required array. Avoids an unnecessary divergence.
• capabilities → optional: Since server.json is being redefined in terms of the Server Card shape, making capabilities required would break all existing server.json files that don't have it. Optional keeps the superset relationship clean.
• Remove MCP Resource endpoint: The mcp://server-card.json resource requires an established MCP connection, which defeats the purpose of pre-connection discovery. Removed in favor of focusing on .well-known for remote servers.
• Remove Registry endpoint section: The registry already serves server.json — no need to spec a separate mechanism here.
• Clarify local server path: Added note that local/stdio servers should use server.json + the MCP Registry rather than Server Cards.

Besides the PR, list of open threads I think we need to resolve to get this SEP into Core Maintainer review-ready state:

• There are a few additive fields on top of server.json that I'm conceptually on board with (we'd add them to server.json to maintain compatibility), but by including them we are adding a whole lot in one swoop, so my suggestion would actually be to remove these and not add them unless there are clear use cases / demand / more folks have inputted as to whether we've designed them right: authentication, supportedProtocolVersions, capabilities, requires
• Implement the schema as a draft in line with how all MCP schemas are defined, final checks on whether that will be fully compatible with the schema as-defined for server.json
• name relationship to placement of .well-known: is it fair to include some verbiage that says e.g. a server named com.github/github-mcp-server should have its .well-known URI at github.com/.well-known/mcp/server-json/github-mcp-server?

And the TODO items we enumerated in our last call:

• Reference implementation in TS SDK (server & client)
• Coordinate with AI card and/or have a fallback approach to the cardinality/discovery layer