mcp-server-card 1.0.0

MCP Server Card Check v1.0.0

Status

• version: 1.0.0
• check identifier: mcp-server-card
• input contract: [email protected]
• output contract: [email protected]
• scope: site-level MCP server-card discovery and remote transport consistency

Abstract

This check validates whether an origin publishes an MCP Server Card for agent-facing MCP discovery. It prefers the current draft path /.well-known/mcp-server-card and current server-card model based on registry-style remotes[], while still recognizing older transitional MCP metadata at /.well-known/mcp/server-card.json, /.well-known/mcp/server-cards.json, /mcp.json, and /.well-known/mcp.json.

Absence is scored as a readiness concern. Missing MCP server-card discovery returns a warning by default. If the origin explicitly claims MCP support or links to a server card but no card can be fetched, the check fails.

Motivation

MCP clients need a stable pre-connection way to discover remote server identity, transport URLs, protocol compatibility, and basic safety information. Without a public server card, agents must guess endpoints, depend on out-of-band configuration, or confuse a site's MCP endpoint with unrelated API metadata.

Normative Model

This version treats SEP-2127 MCP Server Cards as the preferred model:

• primary resource: /.well-known/mcp-server-card
• response format: JSON object
• preferred public-card fields: $schema, name, version, description, and remotes[]
• remote transport entries include a known transport type such as streamable-http and an absolute HTTP(S) URL
• production cards should be served over HTTPS
• public cards must not expose credentials, tokens, private/internal endpoints, or user/session-specific values

This version also accepts a transitional profile with serverInfo, protocolVersion, capabilities, and transport or transports. Transitional cards can pass core validation but produce a warning because the current draft direction uses remotes[].

Applicability

The check always produces a readiness signal:

• Pass when a valid current server card is discovered and validated.
• Warning when no card is found and no explicit MCP claim is detected.
• Fail when the site claims MCP support, exposes MCP metadata, or links to a server-card URL but no card can be fetched.

MCP claim signals include homepage HTML, Link headers, and known MCP/card references such as mcp, modelcontextprotocol, mcp-server-card, server-card.json, /api/mcp, and /mcp.json.

Pass Criteria

A passing current-profile result requires:

• a fetchable JSON card at /.well-known/mcp-server-card or a linked card URL
• valid JSON object body
• $schema, name, version, and description
• at least one valid remotes[] entry
• each remote has a known transport type and a valid HTTP(S) URL
• no public-card safety failures such as secrets, credential-bearing URLs, localhost, private network, or internal hostnames
• same-origin unauthenticated remotes, when present, answer MCP initialize

Older transitional cards can validate, but the shape step warns when the card uses serverInfo / protocolVersion / transport(s) rather than remotes[].

Warning Criteria

Warnings include:

• no MCP server card is found and no explicit MCP support claim is detected
• only transitional, legacy, linked, or compatibility paths expose a usable card
• the card uses a recognized legacy profile rather than the preferred server-card shape
• optional operational metadata such as cache, CORS, or protocol-version hints is incomplete
• remote URLs are cross-origin and are therefore treated as a separate trust boundary
• cross-origin remotes are not actively probed by this version
• same-origin remotes require authentication, so only metadata shape can be validated

Failure Criteria

Failures include:

• the site claims MCP support but no server card can be fetched
• a fetched card is not valid JSON or is not a JSON object
• the card is missing required fields such as name, version, description, or usable remotes
• remotes are missing transport type, URL, or endpoint information
• remote transport type is unknown or unsupported
• remote URLs are non-HTTP(S), contain credentials, use localhost, private network, or internal hostnames
• public card content exposes secrets, tokens, user/session-specific values, or credential-bearing URLs
• same-origin unauthenticated remotes fail the limited MCP initialize probe

Evidence Model

The result emits:

• all discovery paths attempted, status codes, content types, and selected path
• discovered linked card paths from HTML and Link headers
• selected profile: sep-2127-draft, legacy-server-card, or unknown-json
• missing required fields and compatibility warnings
• normalized remote transport evidence, including type, URL, same-origin status, auth hints, and protocol-version hints
• HTTP delivery evidence for content type, HTTPS, CORS, and cache headers
• public-card safety flags with secret values redacted
• limited same-origin MCP initialize probe evidence, without credentials, cookies, authorization headers, or session IDs

Validation And Scoring Steps

1. discover-card - weight 0.20

Fetch current, transitional, and linked discovery paths. Missing discovery is a warning unless MCP support is explicitly claimed, in which case it fails.

1. validate-card-shape - weight 0.25

Validate the current remotes[] profile or the accepted transitional MCP metadata profile.

1. validate-remotes - weight 0.20

Validate transport types, URLs, protocol-version hints, and same-origin classification.

1. http-delivery - weight 0.10

Validate JSON content type, HTTPS delivery, CORS headers, and cache headers.

1. security-hygiene - weight 0.15

Detect credentials, secret-like fields, private hosts, localhost, and internal-only endpoints.

1. endpoint-verification - weight 0.10

Send a limited MCP initialize request to same-origin remotes when safe. Cross-origin and auth-required remotes are recorded but not actively probed.

Standard Behavior

This check evaluates MCP server-card discovery from the supplied page-scan input and its own network fetches. It treats /mcp.json and /.well-known/mcp.json as transitional compatibility sources, and it does not consume output from WebMCP, OAuth, API catalog, or A2A checks.

Endpoint probing is intentionally narrow. This version only attempts MCP initialize against same-origin remotes that do not declare auth, headers, or variables. It does not run tools/list, resources/list, prompts/list, or tools/call.

Non-Standard And Real-World Behavior

Existing deployments and earlier drafts used transitional paths such as /.well-known/mcp/server-card.json, /mcp.json, and /.well-known/mcp.json, plus metadata shapes with serverInfo, protocolVersion, capabilities, and transport(s). This version recognizes those variants so the report can explain migration rather than marking every older implementation as broken.

Static tools, resources, or prompts fields are treated as compatibility warnings. MCP primitives are dynamic and should normally be discovered after connection and authorization.

Non-Goals And Limitations

• This check does not validate WebMCP browser APIs or WebMCP manifests.
• This check does not validate OAuth/OIDC metadata in depth.
• This check does not execute tools or prove business-level MCP workflows work.
• Cross-origin remotes are not actively probed by this version.
• Draft MCP Server Card semantics may change; future versions should capture those changes without mutating v1.0.0 behavior.

References

• modelcontextprotocol.io/community/server-card/charter
• github.com/modelcontextprotocol/modelcontextprotocol/pull/2127
• modelcontextprotocol.io/specification/2025-11-25/basic/transports
• modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
• github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md
• www.rfc-editor.org/rfc/rfc8615
• www.jsonrpc.org/specification
• www.rfc-editor.org/rfc/rfc8615.html

mcp-server-card v1.0.0 Changelog

• Added current MCP Server Card discovery at /.well-known/mcp-server-card.
• Added validation for the current remotes[] server-card model while keeping transitional serverInfo / protocolVersion / transport(s) support.
• Added /mcp.json as a transitional compatibility source for MCP server metadata.
• Changed missing-card behavior to warning by default and failure when MCP support is explicitly claimed.
• Limited endpoint verification to same-origin MCP initialize probes and removed tool execution probing from this check.