From 8a686bf09aafe592f6547d399d7db5d98add1109 Mon Sep 17 00:00:00 2001 From: tadasant Date: Tue, 7 Jul 2026 00:49:18 +0000 Subject: [PATCH 1/2] docs(discovery): make catalog entry displayName optional (#14) Make the MCP Catalog entry field `displayName` optional rather than required, so an entry strictly requires only `identifier`, `mediaType`, and `url`. The referenced Server Card is the source of truth for a server's human-readable name, so an entry may omit `displayName` and let clients read the name from the card at `url`. This follows the upstream AI Catalog change (ADR 0016, Agent-Card/ai-catalog#39, merged 2026-06-26), which likewise made the catalog entry displayName optional. Matching it preserves the guarantee that MCP Catalog entries remain a drop-in subset of AI Catalog entries. Co-Authored-By: Claude Opus 4.8 --- docs/discovery.md | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 8d9a772..858a899 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -48,14 +48,28 @@ An MCP Catalog document is a JSON object that MUST contain the following members #### Catalog Entry -Each entry in the `entries` array describes a single MCP server and MUST contain: - -| Member | Type | Required | Description | -| :------------ | :----- | :------- | :------------------------------------------------------------------------------------ | -| `identifier` | string | Yes | A logical discovery URN for this server (e.g., `urn:air:example.com: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-card+json` | -| `url` | string | Yes | URL where the full [Server Card](#mcp-server-cards) can be retrieved | +Each entry in the `entries` array describes a single MCP server. An entry MUST contain +`identifier`, `mediaType`, and `url`; `displayName` is OPTIONAL: + +| Member | Type | Required | Description | +| :------------ | :----- | :------- | :------------------------------------------------------------------------------------------------------ | +| `identifier` | string | Yes | A logical discovery URN for this server (e.g., `urn:air:example.com:weather`) | +| `displayName` | string | No | A human-readable name for the server. When omitted, clients read the name from the Server Card at `url` | +| `mediaType` | string | Yes | The media type of the referenced artifact. MUST be `application/mcp-server-card+json` | +| `url` | string | Yes | URL where the full [Server Card](#mcp-server-cards) can be retrieved | + +`displayName` is OPTIONAL. The referenced [Server Card](#mcp-server-cards) is the source +of truth for a server's human-readable name, so an entry MAY omit `displayName` and let +clients read the name from the card at `url`. When present, `displayName` lets a client +render a catalog listing without fetching every card; when absent, clients SHOULD source +the name from the fetched Server Card. Requiring `displayName` would force publishers to +duplicate and re-sync a name that already lives in the referenced card. + +Making `displayName` optional keeps MCP Catalog entries a drop-in subset of +[AI Catalog](https://github.com/Agent-Card/ai-catalog) entries: the AI Catalog +specification likewise treats a catalog entry's `displayName` as optional (see +[ADR 0016](https://github.com/Agent-Card/ai-catalog/pull/39)), so the two specs agree and +an MCP Catalog entry remains valid as-is within a full AI Catalog document. The `identifier` is a **logical discovery name** that follows the [AI Catalog](https://github.com/Agent-Card/ai-catalog) domain-anchored URN convention @@ -80,7 +94,8 @@ be indexed as-is within a full AI Catalog document. ### Example: Single Server -A domain hosting a single MCP server, using only the required fields: +A domain hosting a single MCP server, using only the required fields (`displayName` is +omitted, so clients read the name from the referenced Server Card): ```json { @@ -88,7 +103,6 @@ A domain hosting a single MCP server, using only the required fields: "entries": [ { "identifier": "urn:air:example.com:weather", - "displayName": "Weather Service", "mediaType": "application/mcp-server-card+json", "url": "https://example.com/mcp/server-card" } From c7161628b982ce7e89f3eb43d26a59e8d3551644 Mon Sep 17 00:00:00 2001 From: tadasant Date: Tue, 7 Jul 2026 00:55:42 +0000 Subject: [PATCH 2/2] docs(discovery): drop displayName from MCP Catalog entries (#14) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rather than making the MCP Catalog entry field displayName optional, drop it from the MCP Catalog entirely. Every MCP Catalog entry references a Server Card, and the Server Card's `title` is the source of truth for the server's human-readable name. Documenting displayName on the entry — even as optional — only invites publishers to duplicate a name that already lives in the card and risks it drifting out of sync. An MCP Catalog entry now requires only identifier, mediaType, and url. The doc notes that AI Catalog defines an OPTIONAL displayName (ADR 0016, Agent-Card/ai-catalog#39); because it is optional upstream, an MCP entry that omits it remains a valid drop-in subset of an AI Catalog entry. Removes displayName from the field table and from all catalog examples. Co-Authored-By: Claude Opus 4.8 --- docs/discovery.md | 48 +++++++++++++++++++++-------------------------- 1 file changed, 21 insertions(+), 27 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 858a899..d46e446 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -48,28 +48,26 @@ An MCP Catalog document is a JSON object that MUST contain the following members #### Catalog Entry -Each entry in the `entries` array describes a single MCP server. An entry MUST contain -`identifier`, `mediaType`, and `url`; `displayName` is OPTIONAL: - -| Member | Type | Required | Description | -| :------------ | :----- | :------- | :------------------------------------------------------------------------------------------------------ | -| `identifier` | string | Yes | A logical discovery URN for this server (e.g., `urn:air:example.com:weather`) | -| `displayName` | string | No | A human-readable name for the server. When omitted, clients read the name from the Server Card at `url` | -| `mediaType` | string | Yes | The media type of the referenced artifact. MUST be `application/mcp-server-card+json` | -| `url` | string | Yes | URL where the full [Server Card](#mcp-server-cards) can be retrieved | - -`displayName` is OPTIONAL. The referenced [Server Card](#mcp-server-cards) is the source -of truth for a server's human-readable name, so an entry MAY omit `displayName` and let -clients read the name from the card at `url`. When present, `displayName` lets a client -render a catalog listing without fetching every card; when absent, clients SHOULD source -the name from the fetched Server Card. Requiring `displayName` would force publishers to -duplicate and re-sync a name that already lives in the referenced card. - -Making `displayName` optional keeps MCP Catalog entries a drop-in subset of -[AI Catalog](https://github.com/Agent-Card/ai-catalog) entries: the AI Catalog -specification likewise treats a catalog entry's `displayName` as optional (see -[ADR 0016](https://github.com/Agent-Card/ai-catalog/pull/39)), so the two specs agree and -an MCP Catalog entry remains valid as-is within a full AI Catalog document. +Each entry in the `entries` array describes a single MCP server and MUST contain: + +| Member | Type | Required | Description | +| :----------- | :----- | :------- | :------------------------------------------------------------------------------------ | +| `identifier` | string | Yes | A logical discovery URN for this server (e.g., `urn:air:example.com:weather`) | +| `mediaType` | string | Yes | The media type of the referenced artifact. MUST be `application/mcp-server-card+json` | +| `url` | string | Yes | URL where the full [Server Card](#mcp-server-cards) can be retrieved | + +An MCP Catalog entry carries no human-readable-name field. Every entry references a +[Server Card](#mcp-server-cards), and the Server Card's `title` is the source of truth for +a server's name — so a client reads the name from the card at `url` rather than from the +catalog entry. Carrying the name in the entry as well would only duplicate it and risk it +drifting out of sync with the card. + +The [AI Catalog](https://github.com/Agent-Card/ai-catalog) specification defines an +OPTIONAL `displayName` on its catalog entries (see +[ADR 0016](https://github.com/Agent-Card/ai-catalog/pull/39)). Because that field is +optional upstream, an MCP Catalog entry that omits it is still a valid drop-in subset of +an AI Catalog entry: MCP simply does not use `displayName`, deferring in every case to the +referenced Server Card's `title`. The `identifier` is a **logical discovery name** that follows the [AI Catalog](https://github.com/Agent-Card/ai-catalog) domain-anchored URN convention @@ -94,8 +92,7 @@ be indexed as-is within a full AI Catalog document. ### Example: Single Server -A domain hosting a single MCP server, using only the required fields (`displayName` is -omitted, so clients read the name from the referenced Server Card): +A domain hosting a single MCP server: ```json { @@ -120,19 +117,16 @@ A domain hosting several MCP servers, each with its own server card: "entries": [ { "identifier": "urn:air:acme.com:code-review", - "displayName": "Code Review Assistant", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/code-review/server-card" }, { "identifier": "urn:air:acme.com:docs-search", - "displayName": "Documentation Search", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/docs-search/server-card" }, { "identifier": "urn:air:acme.com:ci-cd", - "displayName": "CI/CD Pipeline", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/ci-cd/server-card" }