SEP-2127: MCP Server Cards - HTTP Server Discovery via .well-known

[dsp-ant]

This SEP proposes adding a standardized discovery mechanism for HTTP-based MCP servers using a .well-known/mcp.json endpoint.

Moved from: #1649

Summary

This enables clients to automatically discover:

• Server capabilities
• Available transports
• Authentication requirements
• Protocol versions
• Descriptions of primitives

...all before establishing a connection.

Key Features

• MCP Server Cards: Structured metadata documents exposed through standardized mechanisms
• .well-known/mcp/server-card.json: HTTP endpoint for pre-connection discovery
• mcp://server-card.json: MCP resource for post-connection discovery
• Support for both static and dynamic primitive declarations

See the full specification in seps/2127-mcp-server-cards.md.

[tadasant]

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.

[mukteshkrmishra]

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

[Fannon]

@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-catalog#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.

[maiargu]

@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

[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.

[ognis1205]

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.

[tadasant]

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.

[ognis1205]

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!

[tadasant]

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.

[ognis1205]

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.

[qui-sam]

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.

[HenriChabert]

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.

[tadasant]

I've reviewed from the docs perspective, for consistency and readability. @dsp-ant please review my comments.

@a-akimov heads up, we are refactoring this SEP to be on the Extensions track instead of the Standards track, which will trample a lot of your feedback. I pulled one comment I think will remain relevant in this issue, but please feel free to file more.

[a-akimov]

@a-akimov heads up, we are refactoring this SEP to be on the Extensions track instead of the Standards track, which will trample a lot of your feedback. I pulled one comment I think will remain relevant in this issue, but please feel free to file more.

@tadasant thank you, happy to contribute.

[Wolfe-Jam]

Summary

A running, schema-validated example of carrying project context on a Server Card via a reverse-DNS _meta extension — a concrete datapoint for the _meta extension surface.

How it works

• A reverse-DNS _meta key carries a deterministic link to an external, IANA-registered context artifact (application/vnd.faf+yaml) — a _meta link, not new card fields and not a fork of server.json.
• The card stays thin; the _meta rides the card wherever it's hosted — here, on the reserved /server-card path (#22), served as application/mcp-server-card+json.
• The same _meta is returned by /mcp initialize, so the card can't contradict runtime (re #23).

Receipts

• Repo + conformance tests: https://github.com/Wolfe-Jam/faf-server-card-ref
• Validates against the experimental-ext-server-card server-card.schema.json (JSON Schema 2020-12).

It's the same minimal-card + deterministic-_meta-link shape already raised for other deferred concerns (cf. @dipankar's mcp-pay for payment) — here applied to context. Not asking to widen this SEP; glad to compare notes.

—
Assisted by Claude (Opus 4.8) · Approved by James Wolfe (@Wolfe-Jam)

[b-gutman]

Quick update from production. We tracked the #22 path move on our 810-pack multi-server host today; cards now live at <streamable-http-url>/server-card with discovery via /.well-known/mcp/catalog.json. The v1 .well-known/mcp-server-card[/…] paths 301 to their v2 equivalents so anyone (us included) who adopted the original SEP wording keeps working through the migration.

Three production datapoints worth sharing:

1. Multi-server-host catalog shape works. Ours is at https://gateway.pipeworx.io/.well-known/mcp/catalog.json — 811 entries (host + 810 packs), each pointing at its /{slug}/mcp/server-card. No guessing required, exactly as Change protocol version to a string, rev to 2024-10-07 #22's resolution intended.

2. Fix title of specification page #23's "MUST NOT contradict runtime" is free on our shape. Our cards are generated from the same MCP_PACKS array the runtime initialize handler reads from — drift is structurally impossible. If the spec ends up requiring a _meta.generated_at (or anything that makes freshness declarable), our cards already carry it on the catalog.

3. _meta extension ecosystem is forming faster than I expected. In the past week we've seen three independent prototypes ride the rider pattern: ASM (calebguo007 — value/pricing/SLA/invocability), mcp-pay (dipankarmaikap — payment), and faf (Wolfe-Jam — project context). All three deliberately stayed out of the core card. Worth noting in the wire-format doc that this is the expected adoption surface so the next wave of implementers doesn't try to widen the core.

Both ambiguities we flagged earlier are tracked now — Alex's {server-name} slash question is mostly mooted by the path move; headers[] semantics for tool-arg auth is still worth tightening in the wire-format repo.

We'll keep the v1 redirects up indefinitely. Happy to file repro issues on experimental-ext-server-card if anything else comes up.

— Bruce, Pipeworx (https://pipeworx.io)

[sep-automation-bot]

Maintainer Activity Check

Hi @dsp-ant!

You're assigned to this SEP but there hasn't been any activity from you in 14 days.

Please provide an update on:

• Current status of your review/work
• Any blockers or concerns
• Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

---

This is an automated message from the SEP lifecycle bot.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
mcp-staging	🟢 Ready	View Preview	Jun 26, 2026, 4:12 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
mcp	🟢 Ready	View Preview	Jun 26, 2026, 4:32 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.