refactor: address review feedback on the Server Card API surface

- Replace build_server_card() with the ServerCard.from_server() classmethod,
  matching the SDK's from_* alternate-constructor idiom; the _ServerIdentity
  protocol moves to mcp.shared.experimental.server_card alongside it.
- Make DiscoveryResult iterable over its listings (__iter__/__len__), so
  'for listing in result:' works without the .listings attribute hop.
- Remove the client-side server_card_url() helper: card URLs must come from
  an AI Catalog entry per the discovery spec, never be constructed by the
  client. fetch_server_card's docstring now says so.
- Explain the RFC 6598 shared address space constant in the SSRF guard and
  rename it _CGNAT_NETWORK -> _SHARED_ADDRESS_SPACE; ipaddress reports these
  addresses as neither private nor global, so the guard names them explicitly.

All symbols are experimental (no deprecation cycle), so the removals are clean.

Author: claude

docs/advanced/server-cards.md

@@ -28,11 +28,12 @@ and domain-level discovery reads an **AI Catalog** at `/.well-known/ai-catalog.j
 --8<-- "docs_src/server_cards/tutorial001.py"
 ```
 
-`build_server_card` derives `title`, `description`, `version`, `websiteUrl` and `icons`
-from the server object, so the card stays consistent with what `serverInfo` reports at
-runtime. Explicit keyword arguments override the derived values. The namespaced card
-`name` and the public `remotes` URLs are yours to supply, since the server object cannot
-know them.
+`ServerCard.from_server` derives `title`, `description`, `version`, `websiteUrl` and
+`icons` from the server object, so the card stays consistent with what `serverInfo`
+reports at runtime. Explicit keyword arguments override the derived values. The
+namespaced card `name` and the public `remotes` URLs are yours to supply, since the
+server object cannot know them. (A card that has nothing to derive from is plain
+`ServerCard(...)` — see static publishing below.)
 
 With the app above, `GET /mcp/server-card` and `GET /.well-known/ai-catalog.json` both
 answer with the spec's required headers: the correct `Content-Type`, the CORS headers

docs_src/server_cards/tutorial001.py

@@ -1,6 +1,6 @@
 from mcp.server import MCPServer
-from mcp.server.experimental.server_card import build_server_card, mount_discovery
-from mcp.shared.experimental.server_card import Remote
+from mcp.server.experimental.server_card import mount_discovery
+from mcp.shared.experimental.server_card import Remote, ServerCard
 
 mcp = MCPServer(
     name="weather",
@@ -9,7 +9,7 @@
     website_url="https://example.com",
 )
 
-card = build_server_card(
+card = ServerCard.from_server(
     mcp,
     name="com.example/weather",
     remotes=[Remote(type="streamable-http", url="https://mcp.example.com/mcp")],

docs_src/server_cards/tutorial002.py

@@ -8,7 +8,7 @@
 
 async def main() -> None:
     result = await discover_server_cards("https://example.com/docs")
-    for listing in result.listings:
+    for listing in result:
         print(listing.entry.identifier, "listed on", listing.listing_domain, "hosted at", listing.hosting_domain)
 
     chosen = result.listings[0]  # your host app: consent UI, dedup on chosen.card.endpoint_urls()

src/mcp/client/experimental/_discovery_http.py

@@ -31,7 +31,9 @@
 ]
 
 _REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
-_CGNAT_NETWORK = ipaddress.ip_network("100.64.0.0/10")
+# RFC 6598 shared address space (carrier-grade NAT). `ipaddress` reports these
+# addresses as neither private nor global, so the SSRF guard must name them explicitly.
+_SHARED_ADDRESS_SPACE = ipaddress.ip_network("100.64.0.0/10")
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
@@ -136,7 +138,7 @@ def _is_blocked_address(address: ipaddress.IPv4Address | ipaddress.IPv6Address)
         # properties would miss CGNAT everywhere and, before the gh-113171
         # ipaddress fix, the private v4 ranges too.
         address = address.ipv4_mapped
-    if address.version == 4 and address in _CGNAT_NETWORK:
+    if address.version == 4 and address in _SHARED_ADDRESS_SPACE:
         return True
     # is_private covers loopback, RFC 1918, ULA and the unspecified address.
     return address.is_private or address.is_link_local or address.is_multicast or address.is_reserved

src/mcp/client/experimental/server_card.py

@@ -11,6 +11,7 @@
 """
 
 import os
+from collections.abc import Iterator
 from dataclasses import dataclass
 from pathlib import Path
 from urllib.parse import urlsplit
@@ -35,7 +36,7 @@
     AICatalog,
     CatalogEntry,
 )
-from mcp.shared.experimental.server_card import RESERVED_SERVER_CARD_SUFFIX, SERVER_CARD_MEDIA_TYPE, ServerCard
+from mcp.shared.experimental.server_card import SERVER_CARD_MEDIA_TYPE, ServerCard
 
 __all__ = [
     "DiscoveryPolicy",
@@ -50,7 +51,6 @@
     "discover_server_cards",
     "load_server_card",
     "well_known_ai_catalog_url",
-    "server_card_url",
     "create_server_card_request",
     "parse_server_card_response",
     "create_ai_catalog_request",
@@ -113,12 +113,20 @@ class DiscoveryResult:
     """Everything one discovery probe produced.
 
     A bad entry never kills the probe. It lands in `failures` while the
-    other entries still produce `listings`.
+    other entries still produce `listings`. Iterating the result iterates
+    the listings, so `for listing in result:` reads naturally; check
+    `failures` explicitly for what went wrong along the way.
     """
 
     listings: list[CardListing]
     failures: list[DiscoveryFailure]
 
+    def __iter__(self) -> Iterator[CardListing]:
+        return iter(self.listings)
+
+    def __len__(self) -> int:
+        return len(self.listings)
+
 
 @dataclass(frozen=True, slots=True)
 class CardMismatch:
@@ -141,21 +149,6 @@ def well_known_ai_catalog_url(url: str) -> str:
     return f"{parts.scheme}://{parts.netloc}{AI_CATALOG_WELL_KNOWN_PATH}"
 
 
-def server_card_url(streamable_http_url: str) -> str:
-    """The spec-reserved card URL for a streamable HTTP transport URL.
-
-    The suffix is appended to the transport URL, not the domain root:
-    `https://host/mcp` becomes `https://host/mcp/server-card`.
-
-    Raises:
-        ValueError: If `streamable_http_url` is not absolute http(s).
-    """
-    parts = urlsplit(streamable_http_url)
-    if parts.scheme not in ("http", "https") or not parts.netloc:
-        raise ValueError(f"expected an absolute http(s) URL, got {streamable_http_url!r}")
-    return f"{parts.scheme}://{parts.netloc}{parts.path.rstrip('/')}{RESERVED_SERVER_CARD_SUFFIX}"
-
-
 def load_server_card(path: str | os.PathLike[str]) -> ServerCard:
     """Parse a Server Card from a local file. No network is involved.
 
@@ -174,6 +167,8 @@ async def fetch_server_card(
 ) -> ServerCard:
     """Fetch and parse a Server Card from `url` under `policy`.
 
+    `url` should come from an AI Catalog entry (`CatalogEntry.url`, as
+    `discover_server_cards` follows them), never be constructed client-side.
     A missing `$schema` is defaulted on ingestion. A wrong one is rejected.
     Avoid passing an `http_client` that carries cookies or ambient
     credentials. Discovery requests must never send any.

src/mcp/server/experimental/server_card.py

@@ -12,11 +12,9 @@
 
 import hashlib
 import re
-from collections.abc import Awaitable, Callable, Sequence
-from typing import Any, Protocol
+from collections.abc import Awaitable, Callable
 from urllib.parse import urlsplit
 
-from mcp_types import Icon
 from starlette.applications import Starlette
 from starlette.middleware.cors import CORSMiddleware
 from starlette.requests import Request
@@ -34,13 +32,10 @@
 from mcp.shared.experimental.server_card import (
     RESERVED_SERVER_CARD_SUFFIX,
     SERVER_CARD_MEDIA_TYPE,
-    Remote,
-    Repository,
     ServerCard,
 )
 
 __all__ = [
-    "build_server_card",
     "create_server_card_routes",
     "mount_server_card",
     "create_ai_catalog_routes",
@@ -58,68 +53,6 @@
 }
 
 
-class _ServerIdentity(Protocol):
-    """The identity surface `build_server_card` reads.
-
-    Both `MCPServer` (properties) and the lowlevel `Server` (plain attributes)
-    satisfy this structurally.
-    """
-
-    @property
-    def name(self) -> str: ...
-    @property
-    def title(self) -> str | None: ...
-    @property
-    def version(self) -> str | None: ...
-    @property
-    def description(self) -> str | None: ...
-    @property
-    def website_url(self) -> str | None: ...
-    @property
-    def icons(self) -> list[Icon] | None: ...
-
-
-def build_server_card(
-    server: _ServerIdentity,
-    *,
-    name: str,
-    remotes: Sequence[Remote] | None = None,
-    repository: Repository | None = None,
-    description: str | None = None,
-    title: str | None = None,
-    version: str | None = None,
-    website_url: str | None = None,
-    icons: Sequence[Icon] | None = None,
-    meta: dict[str, Any] | None = None,
-) -> ServerCard:
-    """Build a `ServerCard` from a server's identity fields.
-
-    Title, description, version, website URL and icons come from the server
-    object. Explicit keyword arguments override the derived values, which
-    keeps the card consistent with what `serverInfo` reports at runtime. The
-    namespaced `name` and the public `remotes` URLs are never derivable, so
-    the caller supplies them.
-
-    Raises:
-        pydantic.ValidationError: If the result violates a card constraint,
-            for example a server description over 100 characters or a version
-            that is unset and not overridden.
-    """
-    resolved_icons = list(icons) if icons is not None else server.icons
-    fields: dict[str, Any] = {
-        "name": name,
-        "version": version if version is not None else server.version,
-        "description": description if description is not None else server.description,
-        "title": title if title is not None else server.title,
-        "website_url": website_url if website_url is not None else server.website_url,
-        "icons": resolved_icons,
-        "repository": repository,
-        "remotes": list(remotes) if remotes is not None else None,
-        "meta": meta,
-    }
-    return ServerCard.model_validate(fields)
-
-
 def discovery_response(
     request: Request,
     body: bytes,

src/mcp/shared/experimental/server_card.py

@@ -12,9 +12,9 @@
 """
 
 import re
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
-from typing import Any, Final, Literal
+from typing import Any, Final, Literal, Protocol
 
 from mcp_types import Icon
 from pydantic import Field, field_validator
@@ -109,6 +109,27 @@ def required_variables(self) -> frozenset[str]:
         return frozenset(names)
 
 
+class _ServerIdentity(Protocol):
+    """The identity surface `ServerCard.from_server` reads.
+
+    Both `MCPServer` (properties) and the lowlevel `Server` (plain attributes)
+    satisfy this structurally.
+    """
+
+    @property
+    def name(self) -> str: ...
+    @property
+    def title(self) -> str | None: ...
+    @property
+    def version(self) -> str | None: ...
+    @property
+    def description(self) -> str | None: ...
+    @property
+    def website_url(self) -> str | None: ...
+    @property
+    def icons(self) -> list[Icon] | None: ...
+
+
 class ServerCard(_CardModel):
     """A Server Card document (`application/mcp-server-card+json`).
 
@@ -127,6 +148,48 @@ class ServerCard(_CardModel):
     remotes: list[Remote] | None = None
     meta: dict[str, Any] | None = Field(default=None, alias="_meta")
 
+    @classmethod
+    def from_server(
+        cls,
+        server: _ServerIdentity,
+        *,
+        name: str,
+        remotes: Sequence[Remote] | None = None,
+        repository: Repository | None = None,
+        description: str | None = None,
+        title: str | None = None,
+        version: str | None = None,
+        website_url: str | None = None,
+        icons: Sequence[Icon] | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> "ServerCard":
+        """Build a card from a server's identity fields.
+
+        Title, description, version, website URL and icons come from the
+        server object. Explicit keyword arguments override the derived
+        values, which keeps the card consistent with what `serverInfo`
+        reports at runtime. The namespaced `name` and the public `remotes`
+        URLs are never derivable, so the caller supplies them.
+
+        Raises:
+            pydantic.ValidationError: If the result violates a card
+                constraint, for example a server description over 100
+                characters or a version that is unset and not overridden.
+        """
+        resolved_icons = list(icons) if icons is not None else server.icons
+        fields: dict[str, Any] = {
+            "name": name,
+            "version": version if version is not None else server.version,
+            "description": description if description is not None else server.description,
+            "title": title if title is not None else server.title,
+            "website_url": website_url if website_url is not None else server.website_url,
+            "icons": resolved_icons,
+            "repository": repository,
+            "remotes": list(remotes) if remotes is not None else None,
+            "meta": meta,
+        }
+        return cls.model_validate(fields)
+
     @field_validator("schema_")
     @classmethod
     def _schema_url_is_the_v1_url(cls, value: str) -> str: