Make Catalog Entry displayName optional — conditional on AI Catalog making the same change upstream

[tadasant]

🤖 Drafted by Claude Code (an AI coding agent) on behalf of @tadasant. The substance was reviewed by a human before filing.

Summary

Make displayName optional (rather than required) for MCP Catalog entries in docs/discovery.md — but only if we can get the AI Catalog spec to make the same change upstream first. This is explicitly gated on upstream alignment: we should not diverge from AI Catalog unilaterally (see "Why this is conditional" below).

The rationale: the Server Card is the source of truth for a server's name and metadata. Requiring displayName in every catalog entry forces publishers to duplicate that field and keep it in sync with the card, for no functional gain — a client that needs a display name can read it from the card it's about to fetch anyway. Catalog entries should be able to carry just identifier + mediaType + url and let the card supply the rest.

Current state

Today displayName is a required field in an MCP Catalog entry (discovery.md#L52-L59):

| 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 can be retrieved                                  |

History

This was raised during review of the original draft (SamMorrowDrums/modelcontextprotocol#4, where displayName was an optional field at the time):

@tadasant (comment): "Currently required in AI Card; I think we should try to convince them to make that optional."

@SamMorrowDrums (reply): "Yes, I was conflicted on this, I felt like we would make it optional if we did go it alone, I suppose I should try to maintain alignment and consider pushing this point at the AI Card level."

In the rewrite that became this repo's docs/discovery.md, displayName was promoted from optional to required — the pro-alignment choice. This issue is the "push this point at the AI Card level" follow-through Sam flagged.

Why this is conditional on AI Catalog

discovery.md's core promise is that MCP Catalog entries are a drop-in subset of AI Catalog — "can be included directly in an AI Catalog document without modification." The AI Catalog spec currently makes displayName mandatory on every entry:

Catalog Entry definition (ai-catalog.md#L186-L199):

## Catalog Entry

A Catalog Entry object describes a single AI artifact in the catalog.
It MUST contain the following members:

`identifier`
: ...
`displayName`
: A string containing a human-readable name for the artifact.

…reinforced by the Minimal Catalog conformance definition (ai-catalog.md#L893-L899):

- `entries` — an array of Catalog Entry objects, each containing at
  minimum `identifier`, `displayName`, `mediaType`, and exactly one of `url` or
  `data`

So if we made displayName optional only on the MCP side, an MCP Catalog entry that omits it would be a non-conformant AI Catalog entry — directly breaking the "include directly without modification" guarantee. That's the same subset-compatibility invariant tracked in #9. The two fields (this and the mediaType string) are the parts of the entry the compatibility story depends on most, so they must move together with AI Catalog, not ahead of it.

Proposed resolution

1. Raise it upstream first: propose to the AI Catalog maintainers that displayName become OPTIONAL on a Catalog Entry, with the artifact (Server Card / Agent Card) treated as the source of truth for the human-readable name. Rationale to carry upstream: avoids forcing every catalog publisher to duplicate and re-sync a name that already lives in the referenced artifact; clients that need it can read it from the artifact they're about to fetch.
2. If AI Catalog accepts the change, update discovery.md to mark displayName as OPTIONAL (Required → No) and adjust the entry-table wording accordingly.
3. If AI Catalog declines, keep displayName required here to preserve drop-in compatibility, and close this as "won't fix — alignment retained."

This issue should not be actioned in discovery.md until step 1 resolves. Tracking it here so the follow-through Sam committed to doesn't get lost.

Related: #9 (the broader subset-compatibility / field-alignment concern with AI Catalog).

[tadasant]

@SamMorrowDrums and I think it would be simpler to have this field not exist altogether (but worst case, just make it optional)

[tadasant]

After poking around further, I landed on suggesting it to be optional (not removed), for the reason that some non-A2A, non-MCP artifacts don't have baked-in titles like we do for our case. But adjust normative language to be conditional accordingly.

PR: Agent-Card/ai-catalog#39

If this lands, we will want to update our spec to match accordingly before closing this ticket.