modelcontextprotocol/ext-server-card
Watch
1
0
Fork
You've already forked ext-server-card
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(discovery): address tadasant review feedback

Browse source 
- 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>
This commit is contained in:
Sam Morrow 2026-05-18 09:56:48 +02:00
commit 9e3b3d7c9d
No known key found for this signature in database
1 changed files with 87 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

107
docs/discovery.md
View file

@ -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 | Yes | Version of the MCP Catalog format. Currently `"draft"`. |
| `entries` | array | Yes | Array of [Catalog Entry](#catalog-entry) objects. MAY be empty. |
| 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. |
> **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 server card itself — the catalog entry intentionally carries no optional fields.
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:<reverse-dns-name>
```
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)