docs(draft): add MCP Catalog discovery specification (Plan B) by SamMorrowDrums · Pull Request #4 · SamMorrowDrums/modelcontextprotocol

SamMorrowDrums · 2026-04-20T13:03:54Z

Summary

Adds a new Discovery section to the draft specification that defines the MCP Catalog format — a minimal, MCP-scoped subset of the AI Catalog specification for domain-level server card discovery.

This is the "Plan B" catalog agreed upon in the Server Card working group meeting, providing config-free auto-discovery of MCP servers while the cross-protocol AI Catalog standard is being finalized.

What's included

docs/specification/draft/basic/discovery.mdx — New Discovery specification page covering:
- MCP Catalog format (minimal AI Catalog subset: specVersion + entries[])
- Well-known URI convention: /.well-known/mcp/catalog
- Catalog entry schema (identifier, mediaType, url, plus optional fields)
- Examples for single-server and multi-server domains
- Client discovery flow with Mermaid diagram
- Relationship to AI Catalog and migration path
- Security considerations (CORS, caching, transport security)
docs/docs.json — Navigation updated to place Discovery before Lifecycle in the draft spec

Design decisions

Minimal subset of AI Catalog: Uses the same specVersion/entries structure with identifier, displayName, mediaType, url — but omits trust manifests, publisher objects, collections, bundles, and host info. Entries are valid AI Catalog entries with no structural changes needed for migration.
Well-known URI: /.well-known/mcp/catalog (no file extension)
Not a SEP: This is a companion to the Server Card effort, not a standalone proposal
Draft status: Uses "draft" as specVersion, aligning with the draft specification convention

Add a new Discovery section to the draft specification that defines the MCP Catalog format — a minimal, MCP-scoped subset of the AI Catalog specification for domain-level server card discovery. The MCP Catalog is served at /.well-known/mcp/catalog and provides a JSON index of MCP server cards available on a domain. This enables config-free auto-discovery of MCP servers, acting as a transitional mechanism (Plan B) while the cross-protocol AI Catalog standard is being finalized. Key aspects: - Minimal subset of AI Catalog format (specVersion + entries) - Each entry references an MCP server card via mediaType and url - Designed for trivial migration to the full AI Catalog format - CORS, caching, and transport security requirements Related: modelcontextprotocol#2127 Related: modelcontextprotocol#2563 See also: https://github.com/Agent-Card/ai-catalog Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Since server cards are the source of truth for metadata, displayName and description are redundant in the catalog. Move both to optional fields, keeping only identifier, mediaType, and url as required. Update the single-server example to show a minimal entry with only required fields. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tadasant

Agree this is the right place for it, thanks for drafting!

I do think we should also document Server Cards in a subsection here (or in a second document and link to it from here). But that's a whole extra chunk of work, maybe just leave a placeholder in this PR?

Recommend this PR be merged into https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127/files instead of main so it goes in concert with that SEP.

tadasant · 2026-04-26T18:49:56Z

+
+An **MCP Catalog** is a JSON document that lists the MCP server cards available from a
+given host. Clients can fetch this document to discover all MCP servers a domain offers,
+and then retrieve individual [server cards](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)


Rather than linking the SEP, maybe we should link a subsection in this same doc that explains the Server Card shape?

tadasant · 2026-04-26T18:54:16Z

+
+## MCP Catalog
+
+An **MCP Catalog** is a JSON document that lists the MCP server cards available from a


Suggested change

An **MCP Catalog** is a JSON document that lists the MCP server cards available from a

An **MCP Catalog** is a JSON document that lists the MCP Server Cards available from a

Hyperlink MCP Server Cards?

tadasant · 2026-04-26T18:57:13Z

+An **MCP Catalog** is a JSON document that lists the MCP server cards available from a
+given host. Clients can fetch this document to discover all MCP servers a domain offers,


Suggested change

An **MCP Catalog** is a JSON document that lists the MCP server cards available from a

given host. Clients can fetch this document to discover all MCP servers a domain offers,

An **MCP Catalog** is a JSON document published by an organization to advertise the MCP Server Cards relevant to its services.

The catalog MAY reference servers hosted on different domains than the catalog itself - for example, `acme.org/.well-known/...` MAY advertise servers operated by `mcp-server-host-saas.com` on Acme's behalf.

"Host" is a loaded term in MCP-land; we'd normal use it for MCP client apps. But we mean web host here.

I also think we shouldn't constrain the scope to be "servers hosted on a domain". The intent of a catalog is to allow for cross-domain advertising. e.g. acme.org might use mcp-host-saas.com to host their MCP server, and acme.org/.well-known/*'s MCP catalog should be allowed (encouraged) to advertise that other domain.

tadasant · 2026-04-26T18:59:48Z

+Hosts that serve MCP servers SHOULD publish an MCP Catalog at:
+
+```
+/.well-known/mcp/catalog


Suggested change

/.well-known/mcp/catalog

/.well-known/mcp/catalog.json

For parity with ai-catalog.json? We don't have .json in the mcp/server-card case, but that's because we want to support Server Cards living at postfix-powered paths.

I guess there's the possibility that we want postfix-powered paths for catalogs too... but it feels messier, since the whole point of discoverability is to make it easy to find the catalog, which is much more ambiguous if it might be at acme.org/.well-known/mcp/catalog OR acme.org/.well-known/mcp/catalog/servers.

... but maybe some big domains could convince me that there's a use case for this, like a specific product line at acme.org/product-line-1 -> acme.org/.well-known/mcp/catalog/product-line-1

If we feel strongly that we should drop .json and allow postfix paths, I think we should try to also convince the AI Card folks to bring us into alignemnt.

Ah I think AI Catalog wants to use Collections and Bundles for this purpose.

So I think we should just add .json here and drop the idea I'm describing of a postfix convention for multiple .well-known AI catalogs on a single domain.

tadasant · 2026-04-26T19:05:53Z

+
+### Well-Known URI
+
+Hosts that serve MCP servers SHOULD publish an MCP Catalog at:


Suggested change

Hosts that serve MCP servers SHOULD publish an MCP Catalog at:

Organizations offering services accessible via MCP SHOULD publish an MCP Catalog at the domain users associate with the service. The MCP Catalog should live at:

tadasant · 2026-04-26T19:10:48Z

+| `mediaType`  | string | Yes      | The media type of the referenced artifact. MUST be `application/mcp-server+json` |
+| `url`        | string | Yes      | URL where the full server card can be retrieved                                  |
+
+The following members are OPTIONAL. Because the server card itself is the source of truth


I think we should just leave these out of the minimal (hopefully temporary) "MCP Catalog" spec here. They are purely AI Catalog concerns for folks who wish to adopt AI Catalog, and in an effort to keep our surface here simple without having to answer questions like "so how do I keep description in sync across my Server Card", I think we can just cut.

tadasant · 2026-04-26T19:14:29Z

+
+| Member       | Type   | Required | Description                                                                      |
+| :----------- | :----- | :------- | :------------------------------------------------------------------------------- |
+| `identifier` | string | Yes      | A URI or URN identifying this server (e.g., `urn:mcp:server:example/weather`)    |


Suggested change

| `identifier` | string | Yes | A URI or URN identifying this server (e.g., `urn:mcp:server:example/weather`) |

| `identifier` | string | Yes | A URI or URN identifying this server (e.g., `urn:mcp:server:com.example/weather`) |

I think everything after urn:mcp:server: should directly map to the server.json notion of name.

I would probably additionally add a line like:

The `identifier` MUST begin with `urn:mcp:server:` and end with the `name` value of the referenced Server Card, with no characters in between.

We should probably also take an action to get these examples updated on the AI Catalog docs. FWIW: I like your addition of server; I think we need that extra namespace within MCP.

tadasant · 2026-04-26T19:28:36Z

+  "specVersion": "draft",
+  "entries": [
+    {
+      "identifier": "urn:mcp:server:example.com/weather",


Suggested change

"identifier": "urn:mcp:server:example.com/weather",

"identifier": "urn:mcp:server:com.example/weather",

This and other examples sould use reverse DNS

tadasant · 2026-04-26T19:29:30Z

+This endpoint:
+
+- MUST be accessible via HTTPS (HTTP MAY be supported for local/development use)
+- MUST return `Content-Type: application/json`


Suggested change

- MUST return `Content-Type: application/json`

Later this becomes application/ai-catalog+json; I think easier to just leave it unspecified

tadasant · 2026-04-26T19:31:07Z

+| Member       | Type   | Required | Description                                                                      |
+| :----------- | :----- | :------- | :------------------------------------------------------------------------------- |
+| `identifier` | string | Yes      | A URI or URN identifying this server (e.g., `urn:mcp:server:example/weather`)    |
+| `mediaType`  | string | Yes      | The media type of the referenced artifact. MUST be `application/mcp-server+json` |


We should probably define application/mcp-server+json in the aforementioned new subsection about Server Cards

SamMorrowDrums and others added 2 commits April 20, 2026 15:03

tadasant suggested changes Apr 26, 2026

View reviewed changes


		## MCP Catalog

		An MCP Catalog is a JSON document that lists the MCP server cards available from a

		An MCP Catalog is a JSON document that lists the MCP server cards available from a
		given host. Clients can fetch this document to discover all MCP servers a domain offers,


		### Well-Known URI

		Hosts that serve MCP servers SHOULD publish an MCP Catalog at:

	Hosts that serve MCP servers SHOULD publish an MCP Catalog at:
	Organizations offering services accessible via MCP SHOULD publish an MCP Catalog at the domain users associate with the service. The MCP Catalog should live at:

	\| `identifier` \| string \| Yes \| A URI or URN identifying this server (e.g., `urn:mcp:server:example/weather`) \|
	\| `identifier` \| string \| Yes \| A URI or URN identifying this server (e.g., `urn:mcp:server:com.example/weather`) \|

	"identifier": "urn:mcp:server:example.com/weather",
	"identifier": "urn:mcp:server:com.example/weather",

Conversation

SamMorrowDrums commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's included

Design decisions

Related

Uh oh!

tadasant left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SamMorrowDrums commented Apr 20, 2026 •

edited

Loading