- Status: Accepted
- Accepted: 2026-09-25
- Type: Extensions Track
- Created: 2026-01-21
- Author(s): David Soria Parra (@dsp-ant), Sam Morrow (@SamMorrowDrums), Tadas Antanavicius (@tadasant); on behalf of the Server Card Working Group
- Extension Identifier:
io.modelcontextprotocol/server-card - PR: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127
Abstract
This SEP proposes adding a standardized, self-contained format to describe MCP servers for pre-connection discovery. This enables clients to automatically discover available transports, protocol versions, and connection guidance before establishing a connection.
As an Extensions Track SEP (per SEP-2133), this document charters the Server Card extension and names its Working Group and maintainers. The detailed, normative wire format — the Server Card schema, field definitions, the discovery mechanics, and the full security analysis — is maintained in the experimental-ext-server-card repository rather than inline here, following the precedent set by SEP-1865 (MCP Apps).
Motivation
MCP clients need an out-of-band way to discover remote servers before choosing or opening a transport. Runtime mechanisms such as server/discover become available only after a client already knows where to connect. This creates friction for discovery, integration, and optimization scenarios.
Current Pain Points
- Manual Endpoint Configuration: Users must manually configure transport URLs for each server, with no standardized discovery mechanism.
- No Domain-Level Discovery: Clients cannot automatically discover available MCP servers on a domain. This prevents automated integration scenarios, such as registry crawling or service auto-detection.
- No Out-of-Band Metadata: Runtime discovery still requires a configured transport and a live connection, so it cannot support domain crawling, indexing, or pre-connection configuration.
Imported from upstream. Proposed as modelcontextprotocol#2127 by @dsp-ant on 2026-01-21, where it was still open on 2026-09-25. Accepted into omcp on its technical merit. The text is the author's; only the status, the sponsor field, and documentation links were changed on import.
Reviewed 2026-09-25 — accepted. The document carries every required section, and a prototype a reviewer can run is cited at https://github.com/modelcontextprotocol/experimental-ext-server-card. Conformance tests and the reference documentation chapter are still required before Final.
Proposed Solution
This SEP introduces MCP Server Cards – structured metadata documents that servers expose through standardized mechanisms. For domain-level discovery, an AI Catalog can link to or embed the relevant Server Cards. Cards themselves can be hosted at any unreserved URI, with <streamable-http-url>/server-card reserved as the recommended location. These documents provide static server information without requiring connection establishment.
Enabled Use Cases
- Autoconfiguration: IDE extensions can automatically configure themselves when pointed at a domain, eliminating manual setup.
- Automated Discovery: Clients and registries can crawl domains to discover available MCP servers, enabling ecosystem-wide server indexes.
- Reduced Latency: Display server information and metadata without opening each advertised endpoint.
Relationship to server/discover
Server Cards provide out-of-band, HTTP-oriented discovery: public, cacheable, and indexable metadata that can tell a client where to connect. The server/discover RPC provides live, in-protocol discovery consistently across transports once an endpoint is known and reachable. The mechanisms overlap in identity, endpoint, and protocol-version metadata and SHOULD remain aligned. If they disagree, clients SHOULD prefer the live server/discover values.
Discovery
Relationship to AI Catalog
The AI Catalog provides a decentralized, protocol-agnostic mechanism for identifying AI artifacts. An AI Catalog entry can link to or embed an MCP Server Card, leaving the catalog responsible for domain-level discovery and the Server Card responsible for MCP-specific identity and connection details.
MCP Connection Details
MCP Server Cards provide a richer, MCP-specific definition that can be used by MCP clients to actually connect and start performing MCP operations. The canonical discovery path and the relationship to the broader AI Catalog are specified in the extension repository's docs/discovery.md.
Example:
- "Restaurant A" works with platform "Restaurant Reservations SaaS" to provide MCP-powered bookings for their restaurant
- Restaurant A also works with platform "Jobs SaaS" to provide MCP-powered job listings to prospective job seekers
- Restaurant A would advertise the two relevant Server Cards in an AI Catalog at
restaurant-a.com/.well-known/ai-catalog.json - Restaurant Reservations SaaS would expose a Server Card per restaurant it hosts (one for Restaurant A, one for Restaurant B, etc.)
- Jobs SaaS would expose a Server Card per entity it hosts (one for Restaurant A, one for Coffee Shop B, etc.)
We can develop and iterate on MCP Server Cards independently from AI Catalog, as long as catalog entries can identify Server Cards hosted and maintained elsewhere.
Relationship to the MCP Registry's server.json
MCP Server Cards describe remote MCP connectivity only. The MCP Registry's server.json separately describes registry entries, including locally installable packages and their runtime configuration. The Registry owns that schema; the Server Card extension does not define a Server superset or package-installation types.
Where the formats cover the same concepts, such as identity, documentation, and remote endpoints, they use compatible metadata where practical. A Registry entry can reference or embed a card's remote information, while vendors that need to attach installation hints directly to a card can use namespaced _meta.
Specification
The full specification is maintained in the
experimental-ext-server-card
repository. The TypeScript file schema.ts
is the single source of truth; the generated schema.json
and the discovery mechanics in docs/discovery.md
are derived from it.
For purposes of SEP review, extension repository snapshot 526201bb captures the contract considered by this proposal. After acceptance, implementers should follow the current, versioned extension specification rather than this historical snapshot. As defined by SEP-2133, extension maintainers may evolve the specification independently while preserving backward compatibility; breaking changes require a new extension identifier.
At a high level, the Server Card extension introduces:
- Server Card document: A static metadata document describing a remote MCP server — its identity (
name,version,description, optionaltitle/icons/repository/websiteUrl), its remote transport endpoints (URLs, headers, variable templates, supported protocol versions), and optional namespaced_metadata._metais not used to advertise MCP capabilities or negotiated extension support. The precise field set is defined in the extension repository'sschema.ts. - Discovery: An AI Catalog can link to or embed multiple cards. Cards can be hosted at any unreserved URI, with
<streamable-http-url>/server-cardreserved as the recommended location. The media types, catalog format, and browser-oriented CORS and caching guidance are specified indocs/discovery.md.
As an extension, MCP Server Cards are optional and additive: servers that do not publish a card continue to work normally through standard MCP connections and runtime discovery (see Backward Compatibility).
Rationale
Why Use .well-known for AI Catalog?
For automated domain-level discovery, an AI Catalog can be published at /.well-known/ai-catalog.json. The .well-known URI pattern is an established IETF standard (RFC 8615) used by many protocols for service discovery, including OAuth 2.0 Authorization Server Metadata (RFC 8414). This approach:
- Provides a predictable, standardized location for discovery
- Requires no prior knowledge of server configuration
- Works with standard HTTP infrastructure (caches, CDNs, load balancers)
- Is already familiar to developers working with web services
Why Align with Registry Metadata?
MCP Server Cards aim to provide a static representation of server identity and connection details so that clients can discover and connect to them without prior knowledge of their existence.
The MCP Registry and Server Cards serve different consumers but share concepts such as server identity and remote endpoints. Reusing compatible field names where those concepts overlap reduces needless translation while allowing each owner to evolve its schema independently.
Why Exclude Primitives?
This specification intentionally omits primitive definitions (tools, resources, and prompts) from server cards. MCP servers are inherently dynamic: the primitives a server exposes can vary by authenticated user, session, configuration, feature flags, deployment state, and more. A static document cannot reliably represent this surface, and there is currently no viable substitute for runtime listing via the protocol's standard operations (tools/list, resources/list, prompts/list) with the logged-in user's identity. Including primitives prematurely risks disadvantaging dynamic servers and encouraging clients to rely on information that may be incorrect. A follow-on SEP should address the prerequisites, such as variant enumeration and clear consumer contracts, before primitive advertisement is added.
For the same reason, the initial Server Card format does not advertise MCP capabilities or extension support. supportedProtocolVersions lets a client determine whether it can attempt a connection; capabilities and extensions describe negotiated runtime behavior and can depend on the client, identity, configuration, and deployment state. They remain available through live protocol negotiation. Namespaced _meta is for non-standard metadata and is not a substitute for standardized capability or extension fields. A future revision can add those fields once it defines how static claims relate to runtime variants.
Why Not Wait for Primitives?
The debate around primitives should not delay server card adoption. Discovery (knowing that a server exists, where to connect, and what transports and protocol versions it supports) is enormously valuable on its own. It is the information an end user or IDE needs to install and configure a server, and it is the information a registry needs to index one. None of this depends on knowing the server's tool list in advance.
Server cards without primitives already enable the core use cases that motivate this SEP: autoconfiguration, domain-level discovery, reduced-latency metadata retrieval, and registry integration. Primitives can be added in a future revision once the ecosystem has the right mechanisms to advertise them safely. Shipping discovery now, and shipping it correctly, is more important than shipping a larger surface that risks being wrong.
Other Considered Discovery Mechanisms
DNS-based discovery: We considered using DNS TXT records for discovery, similar to DKIM or SPF. However, this approach would be limited to domain-level discovery and wouldn't work for path-based or port-based MCP servers, making it too restrictive.
Header-based discovery: We considered using HTTP headers (similar to Link headers) to advertise server card locations. While this could work, it requires an HTTP request to the main endpoint first, eliminating many of the benefits of pre-connection discovery.
Backward Compatibility
This SEP is fully backward compatible with existing MCP implementations:
- Server cards are optional. Servers that don't implement them continue to work normally through standard MCP connections and runtime discovery.
- Clients that don't support server cards can ignore them and connect using configured endpoints.
- No changes to core MCP protocol messages or connection flows are required.
Migration Path
- Phase 1 (Optional): Servers can begin exposing server cards without requiring client support
- Phase 2 (Recommended): Clients can implement server card fetching for enhanced discovery and pre-connection validation
- Phase 3 (Future): The ecosystem can develop tooling around server cards for registries, security scanning, and automated discovery
Security Implications
Server Cards are publicly accessible, read-only metadata documents served over HTTP, and the extension's security posture follows from that:
- Information disclosure: Cards are public by design; servers MUST NOT include credentials, internal network topology, proprietary logic, or user/session-specific data.
- Primitive exclusion as a safety property: Cards deliberately exclude primitive definitions (tools, resources, prompts) so clients cannot trust a static manifest for access-control or safety decisions; primitives are always validated at runtime via standard list operations.
- CORS: Wide-open CORS (
Access-Control-Allow-Origin: *) is acceptable because cards carry only public, read-only metadata. - Transport security and MITM: Cards SHOULD be served over HTTPS with certificate validation; because cards are advisory and clients verify their claims against live runtime metadata, a compromised card primarily affects discoverability rather than security.
- Denial of service: Servers SHOULD rate-limit discovery endpoints and clients SHOULD respect cache headers.
The full threat model and the normative CORS/caching/transport requirements are maintained in the extension repository's docs/discovery.md.
Reference Implementation
The Server Card extension is incubated in the experimental-ext-server-card repository, which holds the TypeScript schema source of truth, the generated JSON Schema, discovery documentation, and valid/invalid example documents exercised by a validation script.
python-sdk#2951 is an experimental
Server Cards implementation for the Python SDK by @dsp-ant: server-side card construction and
serving, client-side fetch and validation, and Pydantic models for the ServerCard shape, with tests
that round-trip the conformance examples.
go-sdk#1024 provides an experimental Go SDK server-side reference implementation for constructing and serving Server Cards.
tadasant/goose#1 demonstrates Server Card discovery and installation in the Goose CLI and Desktop client.
Working Group and Maintainers
- Working Group: Server Card Working Group (see the Server Card WG discussion #2563).
- Extension Maintainers: David Soria Parra (@dsp-ant), Sam Morrow (@SamMorrowDrums), Tadas Antanavicius (@tadasant).
- Extension repository: modelcontextprotocol/experimental-ext-server-card (graduating to
ext-server-cardon acceptance).