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

Summary

The "MCP Server Cards" section of docs/discovery.md lists "Capabilities — Tools, resources, and prompts the server offers" as part of a Server Card. SEP-2127 deliberately excludes primitive listings from Server Cards, and this repo's own schema.ts says so explicitly. The newly merged discovery doc therefore contradicts the schema it documents.

Evidence

discovery.md says a Server Card includes tools/resources/prompts (discovery.md#L139-L144):

A Server Card includes:

- **`name`** — A unique identifier for the server in reverse DNS format (e.g., `com.example/weather`)
- **Connection details** — Transport type and endpoint URL
- **Capabilities** — Tools, resources, and prompts the server offers
- **Metadata** — Human-readable name, description, and version

schema.ts says the opposite — primitives are intentionally NOT enumerated (schema.ts#L12-L26):

/**
 * A static metadata document describing a remote MCP server, suitable for
 * publishing at a `.well-known/mcp-server-card` URI for pre-connection discovery.
 *
 * Server Cards intentionally describe only what is needed to discover and
 * connect to a remote server: identity, transport, and protocol versions.
 * They do not enumerate primitives (tools, resources, prompts) — those remain
 * subject to runtime listing via the protocol's standard list operations.
 *
 * The companion {@link Server} shape is a strict superset that adds local
 * package metadata for use cases like the MCP Registry's `server.json`.
 * ...
 */
export interface ServerCard {

SEP-2127 excludes primitives for a documented security reason — "Primitive Information" under Security Considerations (seps/2127-mcp-server-cards.md#L365-L367, PR #2127):

### Primitive Information

Server cards intentionally exclude primitive definitions (tools, resources, prompts).
This avoids a class of security concerns where clients might trust a static manifest's
tool descriptions for access-control or safety decisions, when the actual primitives at
runtime may differ due to auth scoping, feature flags, configuration, or other dynamic
factors. Primitives SHOULD always be discovered and validated through the protocol's
standard list operations after connection establishment.

Why it matters

The discovery doc states, as settled fact, the presence of a capabilities block that the schema does not define and that the SEP deliberately removed for a documented security reason. A reader following docs/discovery.md would expect tool/resource/prompt arrays that don't exist in the current shape.

This is also a contested area, not just an editorial slip: there is active discussion (e.g. in PR #2127) about optionally re-adding tools/resources/prompts for discovery use cases. Stating their presence as fact in discovery.md pre-empts that open question in the wrong direction. The doc should reflect the current shape (primitives excluded; runtime-discoverable), and any future re-introduction should go through the SEP.

Proposed resolution

Edit the Server Card description in docs/discovery.md (#L139-L144) to remove the "Tools, resources, and prompts" capabilities bullet and align with schema.ts / SEP-2127: a Server Card carries identity, connection/transport details, and supported protocol versions; primitives are discovered at runtime via standard list operations.