From ea19e168cc685f912d6bc079f15754953b0ff4c1 Mon Sep 17 00:00:00 2001 From: tadasant Date: Thu, 18 Jun 2026 20:19:22 +0000 Subject: [PATCH 1/6] docs(discovery): adopt AI Catalog `urn:air:` identifier convention (ADR 0015) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align the MCP Catalog Entry `identifier` with the domain-anchored `urn:air:{publisher}:{namespace}:{name}` naming convention standardized in Agent-Card/ai-catalog#36 (ADR 0015), replacing the repo-local `urn:mcp:server:` format. The MCP Catalog is documented as "a minimal, MCP-scoped subset of the AI Catalog specification" whose entries "can be used as-is within a full AI Catalog document" — a claim the old `urn:mcp:server:` format contradicted. Maps the Server Card reverse-DNS `name` (`{publisher}/{name}`) to `urn:air:{publisher}:mcp:{name}`, and clarifies that the discovery `identifier` is decoupled from cryptographic trust identity per ADR 0015. Doc-only change to docs/discovery.md; the Server Card schema has no identifier field and is unchanged. Co-Authored-By: Claude Opus 4.8 --- docs/discovery.md | 43 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 7faffd9..807114d 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -52,13 +52,42 @@ 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`) | +| `identifier` | string | Yes | A logical discovery URN for this server (e.g., `urn:air:com.example:mcp: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 | -The `identifier` MUST begin with `urn:mcp:server:` and end with the `name` value of the -referenced Server Card, with no characters in between. +The `identifier` is a **logical discovery name** that follows the +[AI Catalog](https://github.com/Agent-Card/ai-catalog) domain-anchored URN convention +standardized in [ADR 0015](https://github.com/Agent-Card/ai-catalog/pull/36): + +``` +urn:air:{publisher}:{namespace}:{name} +``` + +For an MCP server, these segments are derived from the referenced Server Card's +reverse-DNS `name` (which has the shape `{publisher}/{name}`): + +- **`publisher`** — the reverse-DNS namespace of the Server Card `name` (the segment + before the `/`), e.g. `com.example`. +- **`namespace`** — the artifact-type segment, which MUST be `mcp` for MCP servers. +- **`name`** — the server-name segment of the Server Card `name` (the segment after the + `/`), e.g. `weather`. + +So a Server Card named `com.example/weather` is referenced as +`urn:air:com.example:mcp:weather`. Anchoring the identifier in the publisher's namespace +keeps it globally unique and stable across infrastructure changes, and lets an MCP Catalog +entry be indexed as-is within a full AI Catalog document. + +Open or federated catalogs MUST use the `urn:air:` form. Local, development, or closed +catalog instances MAY instead use a `urn:air:local:…` or open-text identifier, mirroring +ADR 0015. + +This `identifier` is a discovery name only. Per ADR 0015 it is deliberately **decoupled +from cryptographic trust identity**: trust bindings (DIDs, SPIFFE IDs, x509, etc.) are a +separate concern carried by the full AI Catalog's trust manifests (see +[Relationship to AI Catalog](#relationship-to-ai-catalog)) and MUST NOT be conflated with +the discovery `identifier`. ### Example: Single Server @@ -69,7 +98,7 @@ A domain hosting a single MCP server, using only the required fields: "specVersion": "draft", "entries": [ { - "identifier": "urn:mcp:server:com.example/weather", + "identifier": "urn:air:com.example:mcp:weather", "displayName": "Weather Service", "mediaType": "application/mcp-server-card+json", "url": "https://example.com/mcp/server-card" @@ -87,19 +116,19 @@ A domain hosting several MCP servers, each with its own server card: "specVersion": "draft", "entries": [ { - "identifier": "urn:mcp:server:com.acme/code-review", + "identifier": "urn:air:com.acme:mcp:code-review", "displayName": "Code Review Assistant", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/code-review/server-card" }, { - "identifier": "urn:mcp:server:com.acme/docs-search", + "identifier": "urn:air:com.acme:mcp:docs-search", "displayName": "Documentation Search", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/docs-search/server-card" }, { - "identifier": "urn:mcp:server:com.acme/ci-cd", + "identifier": "urn:air:com.acme:mcp:ci-cd", "displayName": "CI/CD Pipeline", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/ci-cd/server-card" From db4dffe36de23e469a942b36e46b156d8ce53b3a Mon Sep 17 00:00:00 2001 From: tadasant Date: Thu, 18 Jun 2026 20:22:23 +0000 Subject: [PATCH 2/6] docs(discovery): correct ADR 0015 local-identifier wording and publisher note Address fresh-eyes review: ADR 0015 does not define a urn:air:local: form (it permits any open-text identifier for local/closed catalogs), and note that MCP's reverse-DNS publisher segment matches the ADR's own MCP examples. Co-Authored-By: Claude Opus 4.8 --- docs/discovery.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 807114d..53cd3ab 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -69,7 +69,9 @@ For an MCP server, these segments are derived from the referenced Server Card's reverse-DNS `name` (which has the shape `{publisher}/{name}`): - **`publisher`** — the reverse-DNS namespace of the Server Card `name` (the segment - before the `/`), e.g. `com.example`. + before the `/`), e.g. `com.example`. ADR 0015 describes `publisher` as the publisher's + domain; for MCP servers it is the reverse-DNS form already carried in the Server Card + `name`, matching the ADR's own MCP examples (e.g. `urn:air:io.github.modelcontextprotocol:mcp:filesystem`). - **`namespace`** — the artifact-type segment, which MUST be `mcp` for MCP servers. - **`name`** — the server-name segment of the Server Card `name` (the segment after the `/`), e.g. `weather`. @@ -79,9 +81,9 @@ So a Server Card named `com.example/weather` is referenced as keeps it globally unique and stable across infrastructure changes, and lets an MCP Catalog entry be indexed as-is within a full AI Catalog document. -Open or federated catalogs MUST use the `urn:air:` form. Local, development, or closed -catalog instances MAY instead use a `urn:air:local:…` or open-text identifier, mirroring -ADR 0015. +Open or federated catalogs MUST use the `urn:air:` form. Per ADR 0015 the `identifier` +remains an open string format, so local, development, or closed catalog instances MAY +instead use any custom (open-text) identifier. This `identifier` is a discovery name only. Per ADR 0015 it is deliberately **decoupled from cryptographic trust identity**: trust bindings (DIDs, SPIFFE IDs, x509, etc.) are a From abb63388f6f73647b258fcf8e1e186273a01f935 Mon Sep 17 00:00:00 2001 From: tadasant Date: Thu, 18 Jun 2026 21:18:10 +0000 Subject: [PATCH 3/6] docs(discovery): use forward-DNS publisher domain in urn:air identifier Per review feedback, anchor the identifier on the publisher's forward-DNS domain (e.g. example.com) to match ADR 0015's framing that the publisher segment is a domain, and its canonical example urn:air:example.com:mcp:weather. Co-Authored-By: Claude Opus 4.8 --- docs/discovery.md | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 53cd3ab..4d34b8a 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -52,7 +52,7 @@ 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:com.example:mcp:weather`) | +| `identifier` | string | Yes | A logical discovery URN for this server (e.g., `urn:air:example.com:mcp: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 | @@ -65,21 +65,19 @@ standardized in [ADR 0015](https://github.com/Agent-Card/ai-catalog/pull/36): urn:air:{publisher}:{namespace}:{name} ``` -For an MCP server, these segments are derived from the referenced Server Card's -reverse-DNS `name` (which has the shape `{publisher}/{name}`): +The segments are: -- **`publisher`** — the reverse-DNS namespace of the Server Card `name` (the segment - before the `/`), e.g. `com.example`. ADR 0015 describes `publisher` as the publisher's - domain; for MCP servers it is the reverse-DNS form already carried in the Server Card - `name`, matching the ADR's own MCP examples (e.g. `urn:air:io.github.modelcontextprotocol:mcp:filesystem`). +- **`publisher`** — the publisher's domain (forward DNS), e.g. `example.com`. ADR 0015 + anchors the identifier on this domain. This is the same `urn:air:{domain}:mcp:{name}` + shape as the ADR's own MCP example (`urn:air:example.com:mcp:weather`). - **`namespace`** — the artifact-type segment, which MUST be `mcp` for MCP servers. -- **`name`** — the server-name segment of the Server Card `name` (the segment after the - `/`), e.g. `weather`. +- **`name`** — the server's name, i.e. the segment after the `/` in the referenced Server + Card's reverse-DNS `name`, e.g. `weather`. -So a Server Card named `com.example/weather` is referenced as -`urn:air:com.example:mcp:weather`. Anchoring the identifier in the publisher's namespace -keeps it globally unique and stable across infrastructure changes, and lets an MCP Catalog -entry be indexed as-is within a full AI Catalog document. +So a Server Card named `com.example/weather`, published by `example.com`, is referenced as +`urn:air:example.com:mcp:weather`. Anchoring the identifier on the publisher's domain keeps +it globally unique and stable across infrastructure changes, and lets an MCP Catalog entry +be indexed as-is within a full AI Catalog document. Open or federated catalogs MUST use the `urn:air:` form. Per ADR 0015 the `identifier` remains an open string format, so local, development, or closed catalog instances MAY @@ -100,7 +98,7 @@ A domain hosting a single MCP server, using only the required fields: "specVersion": "draft", "entries": [ { - "identifier": "urn:air:com.example:mcp:weather", + "identifier": "urn:air:example.com:mcp:weather", "displayName": "Weather Service", "mediaType": "application/mcp-server-card+json", "url": "https://example.com/mcp/server-card" @@ -118,19 +116,19 @@ A domain hosting several MCP servers, each with its own server card: "specVersion": "draft", "entries": [ { - "identifier": "urn:air:com.acme:mcp:code-review", + "identifier": "urn:air:acme.com:mcp:code-review", "displayName": "Code Review Assistant", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/code-review/server-card" }, { - "identifier": "urn:air:com.acme:mcp:docs-search", + "identifier": "urn:air:acme.com:mcp:docs-search", "displayName": "Documentation Search", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/docs-search/server-card" }, { - "identifier": "urn:air:com.acme:mcp:ci-cd", + "identifier": "urn:air:acme.com:mcp:ci-cd", "displayName": "CI/CD Pipeline", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/ci-cd/server-card" From 72103ab86f655b9c457bf3465312dcc11f84a910 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Thu, 18 Jun 2026 14:21:53 -0700 Subject: [PATCH 4/6] Remove namespace --- docs/discovery.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 4d34b8a..baf403a 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -52,7 +52,7 @@ 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:mcp:weather`) | +| `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 | @@ -68,14 +68,13 @@ urn:air:{publisher}:{namespace}:{name} The segments are: - **`publisher`** — the publisher's domain (forward DNS), e.g. `example.com`. ADR 0015 - anchors the identifier on this domain. This is the same `urn:air:{domain}:mcp:{name}` - shape as the ADR's own MCP example (`urn:air:example.com:mcp:weather`). -- **`namespace`** — the artifact-type segment, which MUST be `mcp` for MCP servers. -- **`name`** — the server's name, i.e. the segment after the `/` in the referenced Server + anchors the identifier on this domain. +- **`namespace`** — optional, populate if you wish +- **`name`** — the server's name suffix, i.e. the segment after the `/` in the referenced Server Card's reverse-DNS `name`, e.g. `weather`. -So a Server Card named `com.example/weather`, published by `example.com`, is referenced as -`urn:air:example.com:mcp:weather`. Anchoring the identifier on the publisher's domain keeps +So a Server Card named `com.example/weather`, is referenced as +`urn:air:example.com:weather`. Anchoring the identifier on the publisher's domain keeps it globally unique and stable across infrastructure changes, and lets an MCP Catalog entry be indexed as-is within a full AI Catalog document. @@ -98,7 +97,7 @@ A domain hosting a single MCP server, using only the required fields: "specVersion": "draft", "entries": [ { - "identifier": "urn:air:example.com:mcp:weather", + "identifier": "urn:air:example.com:weather", "displayName": "Weather Service", "mediaType": "application/mcp-server-card+json", "url": "https://example.com/mcp/server-card" @@ -116,19 +115,19 @@ A domain hosting several MCP servers, each with its own server card: "specVersion": "draft", "entries": [ { - "identifier": "urn:air:acme.com:mcp:code-review", + "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:mcp:docs-search", + "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:mcp:ci-cd", + "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" From 1ea940ad14c343c18297f877b6c27c0cdb313be4 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Thu, 18 Jun 2026 14:24:23 -0700 Subject: [PATCH 5/6] Remove unnecessary detail --- docs/discovery.md | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index baf403a..3a7a45a 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -69,25 +69,15 @@ The segments are: - **`publisher`** — the publisher's domain (forward DNS), e.g. `example.com`. ADR 0015 anchors the identifier on this domain. -- **`namespace`** — optional, populate if you wish +- **`namespace`** — optional, populate if you wish in accordance with the AI Catalog specification - **`name`** — the server's name suffix, i.e. the segment after the `/` in the referenced Server Card's reverse-DNS `name`, e.g. `weather`. -So a Server Card named `com.example/weather`, is referenced as +So a Server Card named `com.example/weather`, can be referenced as `urn:air:example.com:weather`. Anchoring the identifier on the publisher's domain keeps it globally unique and stable across infrastructure changes, and lets an MCP Catalog entry be indexed as-is within a full AI Catalog document. -Open or federated catalogs MUST use the `urn:air:` form. Per ADR 0015 the `identifier` -remains an open string format, so local, development, or closed catalog instances MAY -instead use any custom (open-text) identifier. - -This `identifier` is a discovery name only. Per ADR 0015 it is deliberately **decoupled -from cryptographic trust identity**: trust bindings (DIDs, SPIFFE IDs, x509, etc.) are a -separate concern carried by the full AI Catalog's trust manifests (see -[Relationship to AI Catalog](#relationship-to-ai-catalog)) and MUST NOT be conflated with -the discovery `identifier`. - ### Example: Single Server A domain hosting a single MCP server, using only the required fields: From dc2ea79475a920b25bd39acc893b59c93c6fdd88 Mon Sep 17 00:00:00 2001 From: tadasant Date: Thu, 18 Jun 2026 21:27:34 +0000 Subject: [PATCH 6/6] docs(discovery): fix prettier table alignment Re-pad the Catalog Entry table after the identifier example shortened; fixes the failing format:check CI step. No content change. Co-Authored-By: Claude Opus 4.8 --- docs/discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/discovery.md b/docs/discovery.md index 3a7a45a..8838b39 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -52,7 +52,7 @@ 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`) | +| `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 |