Merge pull request #3 from modelcontextprotocol/sammorrowdrums/mcp-catalog-discovery-spec

Add MCP Catalog discovery specification
2026-05-28 19:51:20 +01:00 · 2026-05-28 19:51:20 +01:00 · ffe58b0fe3
commit ffe58b0fe3
parent c20e3b0245 b4135246f1
1 changed files with 200 additions and 0 deletions
--- a/docs/discovery.md
+++ b/docs/discovery.md
@ -0,0 +1,200 @@
+# Discovery
+
+**Protocol Revision**: draft
+
+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.
+
+## MCP Catalog
+
+An **MCP Catalog** is a JSON document published by an organization to advertise the
+[MCP Server Cards](#mcp-server-cards) relevant to its services.
+
+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.
+
+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.
+
+### 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
+```
+
+This endpoint:
+
+- MUST be accessible via HTTPS (HTTP MAY be supported for local/development use)
+- MUST include appropriate CORS headers (see [CORS Requirements](#cors-requirements))
+- SHOULD include appropriate caching headers (see [Caching](#caching))
+
+### Catalog Format
+
+An MCP Catalog document is a JSON object that MUST contain the following members:
+
+| 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. |
+
+#### Catalog Entry
+
+Each entry in the `entries` array describes a single MCP server and MUST contain:
+
+| 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             |
+
+The `identifier` MUST begin with `urn:mcp:server:` and end with the `name` value of the
+referenced Server Card, with no characters in between.
+
+### Example: 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"
+    }
+  ]
+}
+```
+
+### Example: Multiple Servers
+
+A domain hosting several MCP servers, each with its own server card:
+
+```json
+{
+  "specVersion": "draft",
+  "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"
+    }
+  ]
+}
+```
+
+## Client Discovery Flow
+
+Clients performing domain-level discovery SHOULD follow this procedure:
+
+```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]
+```
+
+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
+
+Clients SHOULD validate that each entry has `mediaType` set to `application/mcp-server+json`
+and ignore entries with unrecognized media types.
+
+## 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`.
+
+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 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.
+
+MCP Catalog entries are structurally compatible with AI Catalog entries. When the AI
+Catalog standard is finalized and adopted by the MCP steering committee:
+
+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
+
+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
+
+Discovery endpoints MUST include appropriate CORS headers to allow browser-based clients:
+
+```
+Access-Control-Allow-Origin: *
+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
+
+Servers SHOULD include caching headers to reduce unnecessary requests:
+
+```
+Cache-Control: public, max-age=3600
+```
+
+### Transport Security
+
+MCP Catalogs MUST be served over HTTPS (TLS 1.2 or later) in production. HTTP MAY be
+used for local development only.