Add experimental Server Cards support (SEP-2127)

[SamMorrowDrums]

Closes modelcontextprotocol/experimental-ext-server-card#16

Summary

Experimental SDK support for MCP Server Cards (SEP-2127) and AI Catalog discovery, opt-in under mcp.{shared,server,client}.experimental. As an experimental extension, these APIs may change without notice.

Takes over #2696 (thanks @dsp-ant — the original two commits are preserved with authorship), rebased cleanly onto current main. #2696 was stacked on the Tasks (SEP-1686) work, since removed from main (#2714).

Opening as a draft for maintainer review — per the extension repo's contribution rules, AI-assisted changes are not self-merged.

What it does

A server builds a Server Card from its own identity, serves it from a Starlette app, and advertises it through an AI Catalog. A client discovers a host's catalog, then fetches and validates the cards it references. Cards describe identity and remote (HTTP) transport only — locally-runnable package metadata stays in the MCP Registry's server.json.

Conformance to the current schemas

• $schema is pinned to https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json; a card pointing at the registry's server.schema.json is rejected. A document that omits $schema is defaulted to the v1 URL rather than rejected.
• AI Catalog entries use the serialized type field, require specVersion, and accept optional displayName. server_card_entry() emits the minimal MCP shape (identifier, type, and url) so human-readable fields cannot drift from the referenced card.
• Media type — serving and catalog entries use application/mcp-server-card+json; the client recognizes only this type and skips catalog entries declaring anything else.
• Catalog identifiers are urn:air:{publisher}:mcp:{name} — the card name's reverse-DNS namespace turned back into the publisher's forward-DNS domain (com.example/weather → urn:air:example.com:mcp:weather).
• Discovery uses the AI Catalog at /.well-known/ai-catalog.json. Discovery responses carry the CORS headers the spec requires (MUST), Cache-Control (SHOULD), strong SHA-256 ETags, and If-None-Match handling for conditional requests.
• version accepts exact versions only; ranges and wildcards (^1.2.3, ~1.2.3, >=1.2.3, 1.x, 1 || 2, 1 - 2) are rejected.
• Unsettled AI Catalog metadata remains available but is documented as unstable pending the outcome of Resolve #58: Add ADR-0017 and migrate to namespace extensions map Agent-Card/ai-catalog#77.

Verification

• ./scripts/test — full coverage suite and strict-no-cover
• pre-commit run --all-files — formatting, lint, pyright, markdownlint, lock consistency, and README snippets
• Focused Server Card and AI Catalog tests cover URL and inline discovery, entry filtering, relative URLs, CORS on both 200 and 304, ETags, validation, and client/server helpers

🤖 The implementation and cleanup were AI-assisted and human-directed.

[tadasant]

Did a pass at an automated review to ensure alignment with some of the latest Server Card changes --

[cubic-dev-ai]

2 issues found and verified against the latest diff

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/mcp/client/experimental/server_card.py">

<violation number="1" location="src/mcp/client/experimental/server_card.py:49">
P2: A successfully fetched JSON document is accepted regardless of its response `Content-Type`, so this helper does not actually enforce the Server Card media-type contract. Checking the normalized media type after `raise_for_status()` (and advertising only that type in `Accept`) would prevent unrelated JSON endpoints from being treated as Server Cards.</violation>
</file>

<file name="src/mcp/shared/experimental/server_card/types.py">

<violation number="1" location="src/mcp/shared/experimental/server_card/types.py:25">
P2: Generated cards advertise a `$schema` URL that currently returns 404. Schema-aware consumers cannot retrieve the declared Server Card schema; publish it at this URL or update the constant to a served schema URL before release.</violation>
</file>

<sub>Tip: cubic used a learning from your PR history. Let your coding agent read cubic learnings directly with the cubic MCP.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Generated cards advertise a $schema URL that currently returns 404. Schema-aware consumers cannot retrieve the declared Server Card schema; publish it at this URL or update the constant to a served schema URL before release.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/mcp/shared/experimental/server_card/types.py, line 25:

<comment>Generated cards advertise a `$schema` URL that currently returns 404. Schema-aware consumers cannot retrieve the declared Server Card schema; publish it at this URL or update the constant to a served schema URL before release.</comment>

<file context>
@@ -0,0 +1,164 @@
+from pydantic import Field, field_validator
+
+#: Canonical ``$schema`` value for a Server Card document.
+SERVER_CARD_SCHEMA_URL = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json"
+
+# Pinned to the Server Card schema name: a card referencing the registry
</file context>

[SamMorrowDrums]

This is intentional and spec-correct, so leaving as-is. The SEP-2127 Server Card spec requires the $schema value to be exactly https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json; that schema document is served from modelcontextprotocol/static once the extension graduates and is simply not published yet (the extension is still pre-release). Hardcoding the spec-mandated URL now is the right thing — and the client tolerates a missing/omitted $schema rather than depending on it resolving.

[cubic-dev-ai]

P2: A successfully fetched JSON document is accepted regardless of its response Content-Type, so this helper does not actually enforce the Server Card media-type contract. Checking the normalized media type after raise_for_status() (and advertising only that type in Accept) would prevent unrelated JSON endpoints from being treated as Server Cards.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/mcp/client/experimental/server_card.py, line 49:

<comment>A successfully fetched JSON document is accepted regardless of its response `Content-Type`, so this helper does not actually enforce the Server Card media-type contract. Checking the normalized media type after `raise_for_status()` (and advertising only that type in `Accept`) would prevent unrelated JSON endpoints from being treated as Server Cards.</comment>

<file context>
@@ -0,0 +1,108 @@
+    if http_client is None:
+        async with create_mcp_http_client() as client:
+            return await fetch_server_card(url, http_client=client)
+    response = await http_client.get(url, headers={"Accept": f"{MCP_SERVER_CARD_MEDIA_TYPE}, application/json"})
+    response.raise_for_status()
+    return ServerCard.model_validate(response.json())
</file context>

[SamMorrowDrums]

Intentionally lenient, so leaving as-is. The spec treats Server Cards as advisory and explicitly allows hosting them at any URI, including static files/CDNs that serve application/json (see the static-hosting tutorial). Enforcing a Content-Type of application/mcp-server-card+json would reject that spec-endorsed static hosting. We already send Accept: application/mcp-server-card+json, application/json (the spec SHOULD) and validate the JSON body against the Server Card schema, which is the meaningful correctness check.