From 55996b594b65648becc9d7d89c4b8182d94d179a Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Tue, 28 Apr 2026 00:31:59 +0200 Subject: [PATCH 1/3] Add MCP Catalog discovery specification Add docs/discovery.md defining the MCP Catalog format for config-free auto-discovery of MCP server cards via a well-known URI. The catalog is a minimal, MCP-scoped subset of the AI Catalog specification. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/discovery.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 docs/discovery.md diff --git a/docs/discovery.md b/docs/discovery.md new file mode 100644 index 0000000..607c031 --- /dev/null +++ b/docs/discovery.md @@ -0,0 +1,157 @@ +# MCP Catalog Discovery Specification + +**Status:** Draft + +## Overview + +The MCP Catalog is a JSON document that lists MCP server cards available from a domain, enabling config-free auto-discovery. It is a minimal, MCP-scoped subset of the [AI Catalog](https://github.com/Agent-Card/ai-catalog) specification. + +## Well-Known URI + +``` +/.well-known/mcp/catalog +``` + +The catalog endpoint: + +- MUST be accessible via HTTPS (HTTP MAY be supported for local/development use) +- MUST return `Content-Type: application/json` +- MUST include appropriate CORS headers (see [Security Considerations](#security-considerations)) +- SHOULD include appropriate caching headers (see [Security Considerations](#security-considerations)) + +## Catalog Format + +The catalog is a JSON object with two required top-level members: + +| Field | Type | Required | Description | +| ------------- | ------ | -------- | -------------------------------------------------------------- | +| `specVersion` | string | Yes | Version of the MCP Catalog format. Currently `"draft"`. | +| `entries` | array | Yes | Array of [Catalog Entry](#catalog-entry) objects. MAY be empty. | + +## Catalog Entry + +Each entry in the `entries` array is a JSON object with exactly three required fields: + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | ---------------------------------------------------------------------------- | +| `identifier` | string | Yes | A URI or URN identifying this server (e.g., `urn:mcp:server:example/weather`) | +| `mediaType` | string | Yes | MUST be `application/mcp-server+json` | +| `url` | string | Yes | URL where the full server card can be retrieved | + +All metadata (name, description, capabilities, etc.) lives in the server card itself — the catalog entry intentionally carries no optional fields. + +## Examples + +### Single Server + +```json +{ + "specVersion": "draft", + "entries": [ + { + "identifier": "urn:mcp:server:example.com/weather", + "mediaType": "application/mcp-server+json", + "url": "https://example.com/.well-known/mcp-server-card" + } + ] +} +``` + +### Multiple Servers + +```json +{ + "specVersion": "draft", + "entries": [ + { + "identifier": "urn:mcp:server:acme.com/code-review", + "mediaType": "application/mcp-server+json", + "url": "https://acme.com/.well-known/mcp-server-card/code-review" + }, + { + "identifier": "urn:mcp:server:acme.com/docs-search", + "mediaType": "application/mcp-server+json", + "url": "https://acme.com/.well-known/mcp-server-card/docs-search" + }, + { + "identifier": "urn:mcp:server:acme.com/ci-cd", + "mediaType": "application/mcp-server+json", + "url": "https://acme.com/.well-known/mcp-server-card/ci-cd" + } + ] +} +``` + +## Client Discovery Flow + +```mermaid +sequenceDiagram + participant Client + participant Domain + participant ServerCard + + Client->>Domain: GET https://{domain}/.well-known/mcp/catalog + Domain-->>Client: 200 OK (application/json) + + alt Valid catalog returned + Client->>Client: Parse entries array + loop For each entry + Client->>Client: Validate mediaType = application/mcp-server+json + alt Recognized media type + Client->>ServerCard: GET entry.url + ServerCard-->>Client: Server card (application/mcp-server+json) + Client->>Client: Use server card to configure connection + else Unrecognized media type + Client->>Client: Ignore entry + end + end + else Error or invalid response + Client->>Client: Fall back to other discovery methods + end +``` + +Clients SHOULD validate that each entry has `mediaType` set to `application/mcp-server+json` and MUST ignore entries with unrecognized media types. This ensures forward compatibility as new entry types are introduced. + +## Relationship to AI Catalog + +The MCP Catalog is a transitional mechanism designed to provide immediate value while the broader [AI Catalog](https://github.com/Agent-Card/ai-catalog) specification matures. + +- **Structural compatibility:** MCP Catalog entries are structurally compatible with AI Catalog entries. Each entry uses the same `identifier`, `mediaType`, and `url` fields. +- **Dual serving:** Domains MAY serve both `/.well-known/mcp/catalog` and the AI Catalog well-known URI during the transition period. The same entries can be used in both documents. +- **Direct inclusion:** MCP Catalog entries can be included directly in an AI Catalog document without modification. No field mapping or transformation is required. + +As the AI Catalog specification stabilizes, implementers SHOULD plan for eventual migration to the unified catalog format. + +## Security Considerations + +### Information Disclosure + +Catalog entries MUST NOT include sensitive information. The catalog is a public discovery document — all fields are intended to be world-readable. + +### CORS Requirements + +The catalog endpoint MUST include the following CORS headers to enable browser-based clients: + +``` +Access-Control-Allow-Origin: * +Access-Control-Allow-Methods: GET +Access-Control-Allow-Headers: Content-Type +``` + +### Caching + +The catalog endpoint SHOULD include caching headers to reduce unnecessary requests: + +``` +Cache-Control: public, max-age=3600 +``` + +### Transport Security + +The catalog MUST be served over HTTPS with TLS 1.2 or later in production environments. HTTP MAY be used for local development and testing only. + +## References + +- [SEP-2127: MCP Server Cards](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) +- [Server Card Working Group Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2563) +- [AI Catalog Specification](https://github.com/Agent-Card/ai-catalog) From 9e3b3d7c9d88d459dc9fc10e60fd0c2f5d53b5cb Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 18 May 2026 09:56:48 +0200 Subject: [PATCH 2/3] docs(discovery): address tadasant review feedback - Add MCP Server Card subsection defining application/mcp-server+json and link 'MCP Server Cards' references internally rather than to SEP-2127 - Reframe domain hosting language to support cross-host advertising (catalog MAY reference servers on different web hosts) - Switch well-known URI to /.well-known/mcp/catalog.json - Add SHOULD-publish recommendation for organizations offering MCP services - Make specVersion OPTIONAL with note about pushing AI Catalog to align - Tighten identifier definition: MUST begin with urn:mcp:server: and the remainder MUST exactly match the server card's name - Update all examples to use reverse-DNS identifiers - Keep Content-Type: application/json for the catalog itself - Add cross-host advertising example and trust considerations Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/discovery.md | 107 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 87 insertions(+), 20 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 607c031..355ed93 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -4,12 +4,24 @@ ## Overview -The MCP Catalog is a JSON document that lists MCP server cards available from a domain, enabling config-free auto-discovery. It is a minimal, MCP-scoped subset of the [AI Catalog](https://github.com/Agent-Card/ai-catalog) specification. +An **MCP Catalog** is a JSON document published by an organization to advertise the [MCP Server Cards](#mcp-server-card) relevant to its services, enabling config-free auto-discovery by MCP clients. It is a minimal, MCP-scoped subset of the [AI Catalog](https://github.com/Agent-Card/ai-catalog) specification. + +The catalog MAY reference servers operated on web hosts different from the one serving the catalog itself — for example, `acme.org/.well-known/mcp/catalog.json` MAY advertise servers operated by `mcp-server-host-saas.com` on Acme's behalf. The catalog represents the organization's curated set of advertised servers, regardless of which web host actually serves them. + +> **Note on terminology:** Throughout this spec, "MCP server" refers to a Model Context Protocol server (the MCP-client sense). When this document needs to refer to the operator of a web endpoint or the machine serving HTTP requests, it uses "web host" or "operator" instead, to avoid ambiguity. + +## Publishing Recommendation + +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: + +``` +/.well-known/mcp/catalog.json +``` ## Well-Known URI ``` -/.well-known/mcp/catalog +/.well-known/mcp/catalog.json ``` The catalog endpoint: @@ -21,12 +33,14 @@ The catalog endpoint: ## Catalog Format -The catalog is a JSON object with two required top-level members: +The catalog is a JSON object with the following top-level members: + +| Field | Type | Required | Description | +| ------------- | ------ | -------- | ----------------------------------------------------------------------------------- | +| `specVersion` | string | No | Version of the MCP Catalog format. Currently `"draft"` when present. See note below. | +| `entries` | array | Yes | Array of [Catalog Entry](#catalog-entry) objects. MAY be empty. | -| Field | Type | Required | Description | -| ------------- | ------ | -------- | -------------------------------------------------------------- | -| `specVersion` | string | Yes | Version of the MCP Catalog format. Currently `"draft"`. | -| `entries` | array | Yes | Array of [Catalog Entry](#catalog-entry) objects. MAY be empty. | +> **Note on `specVersion`:** The upstream [AI Catalog](https://github.com/Agent-Card/ai-catalog) currently requires `specVersion`. This spec deliberately makes it OPTIONAL so that a minimal catalog can simply be `{"entries": [...]}`. We intend to push the AI Catalog to align by making `specVersion` optional there as well. ## Catalog Entry @@ -34,11 +48,42 @@ Each entry in the `entries` array is a JSON object with exactly three required f | Field | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------------------------------------------------- | -| `identifier` | string | Yes | A URI or URN identifying this server (e.g., `urn:mcp:server:example/weather`) | -| `mediaType` | string | Yes | MUST be `application/mcp-server+json` | -| `url` | string | Yes | URL where the full server card can be retrieved | +| `identifier` | string | Yes | A URN identifying this server. See [Identifier](#identifier) below. | +| `mediaType` | string | Yes | MUST be `application/mcp-server+json`. See [MCP Server Card](#mcp-server-card). | +| `url` | string | Yes | URL where the full [MCP Server Card](#mcp-server-card) can be retrieved. | + +All metadata (name, description, capabilities, etc.) lives in the [MCP Server Card](#mcp-server-card) itself — the catalog entry intentionally carries no optional fields. + +### Identifier + +The `identifier` field MUST begin with the prefix `urn:mcp:server:`. The portion of the identifier after this prefix MUST exactly match the `name` value of the referenced [MCP Server Card](#mcp-server-card) (i.e., the `name` field in the server's `server.json`). -All metadata (name, description, capabilities, etc.) lives in the server card itself — the catalog entry intentionally carries no optional fields. +Server `name` values SHOULD use reverse-DNS notation to ensure global uniqueness (e.g., `com.example/weather`). The full identifier then takes the form: + +``` +urn:mcp:server: +``` + +For example, a server whose `server.json` declares `"name": "com.example/weather"` MUST be referenced as `urn:mcp:server:com.example/weather`. + +## MCP Server Card + +An **MCP Server Card** is a JSON document describing a single MCP server: its name, capabilities, transport, authentication requirements, and other metadata needed for a client to connect. The detailed schema for MCP Server Cards is defined by [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127); the rest of this section captures only what the MCP Catalog spec needs. + +### Media Type + +MCP Server Cards are identified by the media type: + +``` +application/mcp-server+json +``` + +A web host serving an MCP Server Card: + +- MUST return `Content-Type: application/mcp-server+json` +- MUST include a `name` field whose value globally identifies the server (the same value referenced by the catalog's `identifier`, minus the `urn:mcp:server:` prefix — see [Identifier](#identifier)) + +Clients fetching a URL from a catalog entry SHOULD validate that the returned `Content-Type` is `application/mcp-server+json` and that the document's `name` matches the catalog entry's `identifier`. ## Examples @@ -46,10 +91,9 @@ All metadata (name, description, capabilities, etc.) lives in the server card it ```json { - "specVersion": "draft", "entries": [ { - "identifier": "urn:mcp:server:example.com/weather", + "identifier": "urn:mcp:server:com.example/weather", "mediaType": "application/mcp-server+json", "url": "https://example.com/.well-known/mcp-server-card" } @@ -64,17 +108,17 @@ All metadata (name, description, capabilities, etc.) lives in the server card it "specVersion": "draft", "entries": [ { - "identifier": "urn:mcp:server:acme.com/code-review", + "identifier": "urn:mcp:server:com.acme/code-review", "mediaType": "application/mcp-server+json", "url": "https://acme.com/.well-known/mcp-server-card/code-review" }, { - "identifier": "urn:mcp:server:acme.com/docs-search", + "identifier": "urn:mcp:server:com.acme/docs-search", "mediaType": "application/mcp-server+json", "url": "https://acme.com/.well-known/mcp-server-card/docs-search" }, { - "identifier": "urn:mcp:server:acme.com/ci-cd", + "identifier": "urn:mcp:server:com.acme/ci-cd", "mediaType": "application/mcp-server+json", "url": "https://acme.com/.well-known/mcp-server-card/ci-cd" } @@ -82,6 +126,24 @@ All metadata (name, description, capabilities, etc.) lives in the server card it } ``` +### Cross-Host Advertising + +An organization MAY advertise servers operated by a third party on its behalf: + +```json +{ + "entries": [ + { + "identifier": "urn:mcp:server:org.acme/support", + "mediaType": "application/mcp-server+json", + "url": "https://mcp-server-host-saas.com/acme/support/.well-known/mcp-server-card" + } + ] +} +``` + +Here, `acme.org/.well-known/mcp/catalog.json` advertises a server whose card is served by `mcp-server-host-saas.com`. The `identifier` remains scoped to Acme because Acme is the organization advertising the server. + ## Client Discovery Flow ```mermaid @@ -90,7 +152,7 @@ sequenceDiagram participant Domain participant ServerCard - Client->>Domain: GET https://{domain}/.well-known/mcp/catalog + Client->>Domain: GET https://{domain}/.well-known/mcp/catalog.json Domain-->>Client: 200 OK (application/json) alt Valid catalog returned @@ -99,7 +161,8 @@ sequenceDiagram Client->>Client: Validate mediaType = application/mcp-server+json alt Recognized media type Client->>ServerCard: GET entry.url - ServerCard-->>Client: Server card (application/mcp-server+json) + ServerCard-->>Client: MCP Server Card (application/mcp-server+json) + Client->>Client: Validate card.name matches identifier Client->>Client: Use server card to configure connection else Unrecognized media type Client->>Client: Ignore entry @@ -117,7 +180,7 @@ Clients SHOULD validate that each entry has `mediaType` set to `application/mcp- The MCP Catalog is a transitional mechanism designed to provide immediate value while the broader [AI Catalog](https://github.com/Agent-Card/ai-catalog) specification matures. - **Structural compatibility:** MCP Catalog entries are structurally compatible with AI Catalog entries. Each entry uses the same `identifier`, `mediaType`, and `url` fields. -- **Dual serving:** Domains MAY serve both `/.well-known/mcp/catalog` and the AI Catalog well-known URI during the transition period. The same entries can be used in both documents. +- **Dual serving:** Organizations MAY serve both `/.well-known/mcp/catalog.json` and the AI Catalog well-known URI during the transition period. The same entries can be used in both documents. - **Direct inclusion:** MCP Catalog entries can be included directly in an AI Catalog document without modification. No field mapping or transformation is required. As the AI Catalog specification stabilizes, implementers SHOULD plan for eventual migration to the unified catalog format. @@ -150,8 +213,12 @@ Cache-Control: public, max-age=3600 The catalog MUST be served over HTTPS with TLS 1.2 or later in production environments. HTTP MAY be used for local development and testing only. +### Cross-Host Trust + +Because a catalog MAY reference [MCP Server Cards](#mcp-server-card) hosted on a different web host than the catalog itself, clients SHOULD treat the publishing domain of the catalog as the authority for which servers an organization endorses. Clients SHOULD surface the catalog's origin to users when presenting the advertised servers. + ## References -- [SEP-2127: MCP Server Cards](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) +- [SEP-2127: MCP Server Cards](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) — full schema for the [MCP Server Card](#mcp-server-card) document referenced by catalog entries. - [Server Card Working Group Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2563) - [AI Catalog Specification](https://github.com/Agent-Card/ai-catalog) From b4135246f1e5270bc02cfac322b15b789d43f02f Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Mon, 18 May 2026 09:57:48 +0200 Subject: [PATCH 3/3] docs(discovery): port authoritative fix from upstream PR Replaces the prior reconstruction with the canonical content from commit bb3bd697 on SamMorrowDrums/modelcontextprotocol@sammorrowdrums/mcp-catalog-specification, adapted from .mdx to plain .md (frontmatter and Mintlify components stripped, content preserved verbatim). Covers all of tadasant's review feedback: internal MCP Server Cards subsection, .json well-known path, reverse-DNS identifiers, identifier MUST constraint, cross-domain advertising language, SHOULD-publish recommendation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/discovery.md | 230 +++++++++++++++++++++------------------------- 1 file changed, 103 insertions(+), 127 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 355ed93..78db7cd 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -1,99 +1,76 @@ -# MCP Catalog Discovery Specification +# Discovery -**Status:** Draft +**Protocol Revision**: draft -## Overview +MCP defines a discovery mechanism that enables clients to find available MCP servers on a +domain without prior configuration. This mechanism complements the lifecycle handshake by +answering _where_ to connect, before the protocol establishes _how_ to communicate. -An **MCP Catalog** is a JSON document published by an organization to advertise the [MCP Server Cards](#mcp-server-card) relevant to its services, enabling config-free auto-discovery by MCP clients. It is a minimal, MCP-scoped subset of the [AI Catalog](https://github.com/Agent-Card/ai-catalog) specification. +## MCP Catalog -The catalog MAY reference servers operated on web hosts different from the one serving the catalog itself — for example, `acme.org/.well-known/mcp/catalog.json` MAY advertise servers operated by `mcp-server-host-saas.com` on Acme's behalf. The catalog represents the organization's curated set of advertised servers, regardless of which web host actually serves them. +An **MCP Catalog** is a JSON document published by an organization to advertise the +[MCP Server Cards](#mcp-server-cards) relevant to its services. -> **Note on terminology:** Throughout this spec, "MCP server" refers to a Model Context Protocol server (the MCP-client sense). When this document needs to refer to the operator of a web endpoint or the machine serving HTTP requests, it uses "web host" or "operator" instead, to avoid ambiguity. +The catalog MAY reference servers 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. Clients can fetch this document to discover +servers and then retrieve individual [Server Cards](#mcp-server-cards) for connection +details. -## Publishing Recommendation +The MCP Catalog format is a minimal, MCP-scoped subset of the +[AI Catalog](https://github.com/Agent-Card/ai-catalog) specification. This alignment +ensures that MCP Catalog entries can be used as-is within a full AI Catalog document, +enabling a smooth migration path when the cross-protocol AI Catalog standard is finalized. -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: +### Well-Known URI -``` -/.well-known/mcp/catalog.json -``` - -## Well-Known URI +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: ``` /.well-known/mcp/catalog.json ``` -The catalog endpoint: +This endpoint: - MUST be accessible via HTTPS (HTTP MAY be supported for local/development use) -- MUST return `Content-Type: application/json` -- MUST include appropriate CORS headers (see [Security Considerations](#security-considerations)) -- SHOULD include appropriate caching headers (see [Security Considerations](#security-considerations)) - -## Catalog Format - -The catalog is a JSON object with the following top-level members: +- MUST include appropriate CORS headers (see [CORS Requirements](#cors-requirements)) +- SHOULD include appropriate caching headers (see [Caching](#caching)) -| Field | Type | Required | Description | -| ------------- | ------ | -------- | ----------------------------------------------------------------------------------- | -| `specVersion` | string | No | Version of the MCP Catalog format. Currently `"draft"` when present. See note below. | -| `entries` | array | Yes | Array of [Catalog Entry](#catalog-entry) objects. MAY be empty. | +### Catalog Format -> **Note on `specVersion`:** The upstream [AI Catalog](https://github.com/Agent-Card/ai-catalog) currently requires `specVersion`. This spec deliberately makes it OPTIONAL so that a minimal catalog can simply be `{"entries": [...]}`. We intend to push the AI Catalog to align by making `specVersion` optional there as well. +An MCP Catalog document is a JSON object that MUST contain the following members: -## Catalog Entry +| Member | Type | Required | Description | +| :------------ | :----- | :------- | :---------------------------------------------------------- | +| `specVersion` | string | Yes | The version of the MCP Catalog format (currently `"draft"`) | +| `entries` | array | Yes | An array of Catalog Entry objects. This array MAY be empty. | -Each entry in the `entries` array is a JSON object with exactly three required fields: +#### Catalog Entry -| Field | Type | Required | Description | -| ------------ | ------ | -------- | ---------------------------------------------------------------------------- | -| `identifier` | string | Yes | A URN identifying this server. See [Identifier](#identifier) below. | -| `mediaType` | string | Yes | MUST be `application/mcp-server+json`. See [MCP Server Card](#mcp-server-card). | -| `url` | string | Yes | URL where the full [MCP Server Card](#mcp-server-card) can be retrieved. | +Each entry in the `entries` array describes a single MCP server and MUST contain: -All metadata (name, description, capabilities, etc.) lives in the [MCP Server Card](#mcp-server-card) itself — the catalog entry intentionally carries no optional fields. - -### Identifier - -The `identifier` field MUST begin with the prefix `urn:mcp:server:`. The portion of the identifier after this prefix MUST exactly match the `name` value of the referenced [MCP Server Card](#mcp-server-card) (i.e., the `name` field in the server's `server.json`). - -Server `name` values SHOULD use reverse-DNS notation to ensure global uniqueness (e.g., `com.example/weather`). The full identifier then takes the form: - -``` -urn:mcp:server: -``` +| Member | Type | Required | Description | +| :------------ | :----- | :------- | :------------------------------------------------------------------------------- | +| `identifier` | string | Yes | A URN identifying this server (e.g., `urn:mcp:server:com.example/weather`) | +| `displayName` | string | Yes | A human-readable name for the server | +| `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](#mcp-server-cards) can be retrieved | -For example, a server whose `server.json` declares `"name": "com.example/weather"` MUST be referenced as `urn:mcp:server:com.example/weather`. +The `identifier` MUST begin with `urn:mcp:server:` and end with the `name` value of the +referenced Server Card, with no characters in between. -## MCP Server Card +### Example: Single Server -An **MCP Server Card** is a JSON document describing a single MCP server: its name, capabilities, transport, authentication requirements, and other metadata needed for a client to connect. The detailed schema for MCP Server Cards is defined by [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127); the rest of this section captures only what the MCP Catalog spec needs. - -### Media Type - -MCP Server Cards are identified by the media type: - -``` -application/mcp-server+json -``` - -A web host serving an MCP Server Card: - -- MUST return `Content-Type: application/mcp-server+json` -- MUST include a `name` field whose value globally identifies the server (the same value referenced by the catalog's `identifier`, minus the `urn:mcp:server:` prefix — see [Identifier](#identifier)) - -Clients fetching a URL from a catalog entry SHOULD validate that the returned `Content-Type` is `application/mcp-server+json` and that the document's `name` matches the catalog entry's `identifier`. - -## Examples - -### Single Server +A domain hosting a single MCP server, using only the required fields: ```json { + "specVersion": "draft", "entries": [ { "identifier": "urn:mcp:server:com.example/weather", + "displayName": "Weather Service", "mediaType": "application/mcp-server+json", "url": "https://example.com/.well-known/mcp-server-card" } @@ -101,7 +78,9 @@ Clients fetching a URL from a catalog entry SHOULD validate that the returned `C } ``` -### Multiple Servers +### Example: Multiple Servers + +A domain hosting several MCP servers, each with its own server card: ```json { @@ -109,16 +88,19 @@ Clients fetching a URL from a catalog entry SHOULD validate that the returned `C "entries": [ { "identifier": "urn:mcp:server:com.acme/code-review", + "displayName": "Code Review Assistant", "mediaType": "application/mcp-server+json", "url": "https://acme.com/.well-known/mcp-server-card/code-review" }, { "identifier": "urn:mcp:server:com.acme/docs-search", + "displayName": "Documentation Search", "mediaType": "application/mcp-server+json", "url": "https://acme.com/.well-known/mcp-server-card/docs-search" }, { "identifier": "urn:mcp:server:com.acme/ci-cd", + "displayName": "CI/CD Pipeline", "mediaType": "application/mcp-server+json", "url": "https://acme.com/.well-known/mcp-server-card/ci-cd" } @@ -126,74 +108,75 @@ Clients fetching a URL from a catalog entry SHOULD validate that the returned `C } ``` -### Cross-Host Advertising +## Client Discovery Flow -An organization MAY advertise servers operated by a third party on its behalf: +Clients performing domain-level discovery SHOULD follow this procedure: -```json -{ - "entries": [ - { - "identifier": "urn:mcp:server:org.acme/support", - "mediaType": "application/mcp-server+json", - "url": "https://mcp-server-host-saas.com/acme/support/.well-known/mcp-server-card" - } - ] -} +```mermaid +flowchart TD + A[Client wants to discover MCP servers on example.com] --> B[Fetch /.well-known/mcp/catalog.json] + B --> C{Valid catalog returned?} + C -->|Yes| D[Parse entries array] + C -->|No| E[Discovery unavailable for this domain] + D --> F[For each entry, fetch server card from url] + F --> G[Use server card to configure connection] ``` -Here, `acme.org/.well-known/mcp/catalog.json` advertises a server whose card is served by `mcp-server-host-saas.com`. The `identifier` remains scoped to Acme because Acme is the organization advertising the server. +1. Fetch `https://{domain}/.well-known/mcp/catalog.json` +2. If a valid MCP Catalog is returned, iterate over the `entries` array +3. For each entry, retrieve the server card from the entry's `url` +4. Use the server card metadata to configure and establish an MCP connection -## Client Discovery Flow +Clients SHOULD validate that each entry has `mediaType` set to `application/mcp-server+json` +and ignore entries with unrecognized media types. -```mermaid -sequenceDiagram - participant Client - participant Domain - participant ServerCard - - Client->>Domain: GET https://{domain}/.well-known/mcp/catalog.json - Domain-->>Client: 200 OK (application/json) - - alt Valid catalog returned - Client->>Client: Parse entries array - loop For each entry - Client->>Client: Validate mediaType = application/mcp-server+json - alt Recognized media type - Client->>ServerCard: GET entry.url - ServerCard-->>Client: MCP Server Card (application/mcp-server+json) - Client->>Client: Validate card.name matches identifier - Client->>Client: Use server card to configure connection - else Unrecognized media type - Client->>Client: Ignore entry - end - end - else Error or invalid response - Client->>Client: Fall back to other discovery methods - end -``` +## MCP Server Cards + +An **MCP Server Card** is a JSON document that describes a single MCP server — its +identity, capabilities, and connection details. Server Cards use the media type +`application/mcp-server+json`. -Clients SHOULD validate that each entry has `mediaType` set to `application/mcp-server+json` and MUST ignore entries with unrecognized media types. This ensures forward compatibility as new entry types are introduced. +A Server Card includes: + +- **`name`** — A unique identifier for the server in reverse DNS format (e.g., `com.example/weather`) +- **Connection details** — Transport type and endpoint URL +- **Capabilities** — Tools, resources, and prompts the server offers +- **Metadata** — Human-readable name, description, and version + +For the full Server Card specification, see +[SEP-2127: MCP Server Cards](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127). ## Relationship to AI Catalog -The MCP Catalog is a transitional mechanism designed to provide immediate value while the broader [AI Catalog](https://github.com/Agent-Card/ai-catalog) specification matures. +The MCP Catalog is designed as a transitional mechanism. The +[AI Catalog](https://github.com/Agent-Card/ai-catalog) specification defines a +cross-protocol discovery standard (`/.well-known/ai-catalog.json`) capable of indexing +MCP servers, A2A agents, and other AI artifacts. -- **Structural compatibility:** MCP Catalog entries are structurally compatible with AI Catalog entries. Each entry uses the same `identifier`, `mediaType`, and `url` fields. -- **Dual serving:** Organizations MAY serve both `/.well-known/mcp/catalog.json` and the AI Catalog well-known URI during the transition period. The same entries can be used in both documents. -- **Direct inclusion:** MCP Catalog entries can be included directly in an AI Catalog document without modification. No field mapping or transformation is required. +MCP Catalog entries are structurally compatible with AI Catalog entries. When the AI +Catalog standard is finalized and adopted by the MCP steering committee: -As the AI Catalog specification stabilizes, implementers SHOULD plan for eventual migration to the unified catalog format. +1. Domains MAY serve both `/.well-known/mcp/catalog.json` and `/.well-known/ai-catalog.json` + during a transition period +2. MCP Catalog entries can be included directly in an AI Catalog document without + modification +3. Domains that want richer metadata (trust manifests, publisher identity, collections) + can adopt the full AI Catalog format ## Security Considerations ### Information Disclosure -Catalog entries MUST NOT include sensitive information. The catalog is a public discovery document — all fields are intended to be world-readable. +MCP Catalogs are publicly accessible by design. Catalog entries MUST NOT include sensitive +information such as: + +- Authentication credentials or tokens +- Internal network topology or private endpoints +- Proprietary business logic ### CORS Requirements -The catalog endpoint MUST include the following CORS headers to enable browser-based clients: +Discovery endpoints MUST include appropriate CORS headers to allow browser-based clients: ``` Access-Control-Allow-Origin: * @@ -201,9 +184,11 @@ Access-Control-Allow-Methods: GET Access-Control-Allow-Headers: Content-Type ``` +This is safe because MCP Catalogs contain only public metadata and are read-only. + ### Caching -The catalog endpoint SHOULD include caching headers to reduce unnecessary requests: +Servers SHOULD include caching headers to reduce unnecessary requests: ``` Cache-Control: public, max-age=3600 @@ -211,14 +196,5 @@ Cache-Control: public, max-age=3600 ### Transport Security -The catalog MUST be served over HTTPS with TLS 1.2 or later in production environments. HTTP MAY be used for local development and testing only. - -### Cross-Host Trust - -Because a catalog MAY reference [MCP Server Cards](#mcp-server-card) hosted on a different web host than the catalog itself, clients SHOULD treat the publishing domain of the catalog as the authority for which servers an organization endorses. Clients SHOULD surface the catalog's origin to users when presenting the advertised servers. - -## References - -- [SEP-2127: MCP Server Cards](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) — full schema for the [MCP Server Card](#mcp-server-card) document referenced by catalog entries. -- [Server Card Working Group Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2563) -- [AI Catalog Specification](https://github.com/Agent-Card/ai-catalog) +MCP Catalogs MUST be served over HTTPS (TLS 1.2 or later) in production. HTTP MAY be +used for local development only.