MCP Server Cards and Discovery: Well-Known Files and Registries
MCP server cards explained: the /server-card document, /.well-known/ai-catalog.json, server/discover, server.json for the MCP Registry, and how to add one.
Questo articolo è in inglese.
TL;DR. An MCP server card is a small public JSON document that tells a client where a remote MCP server is, which transport and protocol versions it supports, and who publishes it, before the client sends a single MCP request. The Server Card extension recommends serving the card at <streamable-http-url>/server-card, and a domain lists its cards in /.well-known/ai-catalog.json. The card sits next to two other discovery mechanisms: server/discover, which a reachable server answers live, and the MCP Registry's server.json, which covers installation, including local packages. This guide covers the format, the HTTP rules, a live example (mcp.tc's own card), how a directory reads all of it, and how to publish and check a card for your server.
What is an MCP server card?
An MCP server card is a static JSON document, chartered by SEP-2127 and defined by the Server Card extension, that describes a remote MCP server's identity and connection details (name, version, description, remote endpoints and supported protocol versions) so that a client, crawler or directory can learn where to connect without opening an MCP session first.
SEP-2127, created 2026-01-21, is an Extensions Track SEP with status Final. It charters the extension and leaves the normative schema and discovery rules to the extension repository, where schema.ts is the source of truth and schema.json is generated from it. The extensions overview on modelcontextprotocol.io lists Server Cards at the Beta stage (fetched 11 November 2026), with the destination (Stable or Core) not yet stated.
The generated schema requires four fields: $schema, name, version and description. name takes the form namespace/server with exactly one slash, 3 to 200 characters. description is 1 to 100 characters. Optional fields are title, icons, repository, websiteUrl, remotes and a namespaced _meta object. Each item in remotes needs a type (streamable-http or sse) and a url, and may carry supportedProtocolVersions, headers and variables for {curly_brace} templates in the URL.
Two things are deliberately absent. The card has no tools, resources or prompts; the SEP's rationale is that a server's primitives "can vary by authenticated user, session, configuration, feature flags, deployment state, and more", so a static document cannot represent them and clients must list them at runtime. The card also carries no capabilities or extension support, which stay in live negotiation. On the security side, the SEP says servers MUST NOT include credentials, internal network topology, proprietary logic or user or session-specific data, because a card is public by design.
Where does a server card live?
A server card lives at any unreserved HTTPS URL, and the extension's discovery document reserves <streamable-http-url>/server-card as the recommended location. A server at https://mcp.example.com/mcp would therefore publish its card at https://mcp.example.com/mcp/server-card, and mcp.tc's own card is at https://mcp.tc/mcp/server-card.
The discovery document attaches the suffix to the Streamable HTTP endpoint, not to the domain root, and it does not define a .well-known path for individual cards. Domain-level lookup goes through the catalog described in the next section. If you have seen other paths in the wild, that is the reason: the extension only reserves the /server-card suffix. mcp.tc serves the same document at /.well-known/mcp/server-card.json as well, and mcp-tc check reads both paths.
The same document sets the HTTP rules for a hosted card:
- HTTPS with TLS 1.2 or later is a MUST in production; plain HTTP is for local development.
- CORS headers are a MUST so browser-based clients can read the card.
Cache-Control: public, max-age=3600and anETagare a SHOULD, with304 Not Modifiedwhen a client sendsIf-None-Match.- The media type
application/mcp-server-card+jsonis a SHOULD on both sides: servers honor it, clients send it inAccept. - Rate limiting of the card endpoint is a SHOULD.
A response that follows every rule looks like this:
HTTP/1.1 200 OK
Content-Type: application/mcp-server-card+json
Cache-Control: public, max-age=3600
ETag: "a1b2c3"
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: Content-Type, If-None-Match
Access-Control-Expose-Headers: ETagTo see a live card, fetch mcp.tc's:
curl -s -H 'Accept: application/mcp-server-card+json' https://mcp.tc/mcp/server-cardOn 11 November 2026 it returns this (icons shortened):
{
"$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
"name": "tc.mcp/mcp-tc",
"version": "1.1.0",
"description": "Search the mcp.tc directory of MCP servers: endpoints, install commands and setup steps per client.",
"title": "mcp.tc directory",
"websiteUrl": "https://mcp.tc",
"icons": [{ "src": "https://mcp.tc/icon-192.png", "mimeType": "image/png", "sizes": ["192x192"] }],
"remotes": [
{
"type": "streamable-http",
"url": "https://mcp.tc/mcp",
"supportedProtocolVersions": ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26"]
}
]
}A client that reads this knows the endpoint, the transport, and that it can send a 2026-07-28 request or fall back to an initialize handshake, all before the first MCP call. The docs for mcp.tc's MCP server add one convenience: a plain GET on https://mcp.tc/mcp answers with a Link header that points to the card.
How does /.well-known/ai-catalog.json tie cards to a domain?
The AI Catalog at /.well-known/ai-catalog.json is the domain-level index that the Server Card extension relies on: a host publishes one catalog that links to, or embeds, each server card it wants found, so a client that knows only a domain can locate every MCP server behind it without guessing paths.
The path follows RFC 8615, the May 2019 standard that reserves the /.well-known/ prefix for site-wide metadata. The SEP chose it over two alternatives it considered: DNS TXT records (which cannot express path- or port-based servers) and HTTP headers on the endpoint (which require a request to the endpoint first and so lose the point of pre-connection discovery).
The discovery document gives the lookup in four steps: fetch https://{domain}/.well-known/ai-catalog.json; select entries whose type is application/mcp-server-card+json; for an entry with url, fetch the card with Accept: application/mcp-server-card+json, or use the inline card from data; then connect with what the card says. Each MCP entry has an identifier of the form urn:air:{publisher}:{namespace}:{name}, and exactly one of url or data. The catalog itself SHOULD be served as application/ai-catalog+json.
A minimal catalog for one server:
{
"specVersion": "1.0",
"entries": [
{
"identifier": "urn:air:example.com:mcp:example-server",
"type": "application/mcp-server-card+json",
"url": "https://mcp.example.com/mcp/server-card"
}
]
}The catalog is protocol-agnostic. The AI Catalog site lists entry types for MCP server cards, A2A agent cards and nested catalogs, which is why the SEP leaves domain-level discovery to the catalog and keeps the card MCP-specific. The SEP's own example is a business that uses two hosted platforms, one for bookings and one for job listings: the business lists both cards in its catalog, and each platform publishes one card per customer it hosts.
mcp.tc publishes its catalog at https://mcp.tc/.well-known/ai-catalog.json with three entries: its server card, the OpenAPI description of its API, and one agent skill. The API docs describe each file.
Server card vs server/discover vs server.json: which does what?
A server card, the server/discover request and the MCP Registry's server.json answer three different questions: the card says where a remote server is before any MCP request, server/discover reports what a reachable server supports right now, and server.json tells a registry how to install or reach a server, including local packages.
| Server card | server/discover | server.json | |
|---|---|---|---|
| Served by | The server's host, as a plain HTTPS GET | The MCP endpoint, as a JSON-RPC method | The owner, published to the MCP Registry |
| Read when | Before connecting, or when crawling a domain | After the client knows the endpoint | When a registry or aggregator indexes servers |
| Holds | name, version, description, remotes[] with supportedProtocolVersions | supportedVersions, capabilities, serverInfo, instructions, ttlMs, cacheScope | name, version, packages[], remotes[], environment and arguments |
| Transports | Remote only (streamable-http, sse) | Any transport | Remote and local packages |
| Authority | Advisory; live values win | Live, but serverInfo is self-reported | Namespace verified by the registry; content from the owner |
The 2026-07-28 changelog added server/discover and says servers MUST implement it. The discover page makes calling it optional for clients: a client may send any request inline and handle UnsupportedProtocolVersionError, or call server/discover first to show the server's identity and capabilities in one round trip. The result carries supportedVersions, capabilities, _meta["io.modelcontextprotocol/serverInfo"] (a SHOULD), optional instructions, and the ttlMs and cacheScope fields the same revision requires on cacheable results. The page also warns that serverInfo "is self-reported by the server and is not verified by the protocol".
The SEP states the overlap rule: card and server/discover share identity, endpoint and protocol-version metadata and "SHOULD remain aligned. If they disagree, clients SHOULD prefer the live server/discover values."
server.json belongs to the Registry working group, and the SEP says the card extension "does not define a Server superset or package-installation types". Where the two formats cover the same concepts, they use compatible field names; the remotes entries look alike. The registry's remote server guide shows type, url, variables and headers, and adds one rule a card cannot enforce: "A remote server MUST be publicly accessible at its specified URL." If your server is a local stdio package, it has no card; it has a server.json with a packages entry, and a client installs it from npm, PyPI or another package registry.
How do registries and directories fit into MCP discovery?
Registries and directories sit above individual servers: the official MCP Registry stores server.json entries under verified namespaces and expects aggregators to read its API about once an hour, while a directory such as mcp.tc reads the registry, server cards, catalogs and live tool lists, and republishes the result through its own registry-compatible API.
The registry's about page is explicit about the layering. The registry is "intended to be consumed primarily by downstream aggregators" and "is not intended to be directly consumed by host applications"; host applications should read a subregistry that implements the registry's OpenAPI description. Names use reverse-DNS form, such as com.example/server, tied to a GitHub account or a domain proven through GitHub, DNS or HTTP challenges. The registry delegates security scanning to package registries and aggregators, and it is in preview on 11 November 2026.
The aggregators guide gives the read API at https://registry.modelcontextprotocol.io: GET /v0.1/servers with limit and cursor for paging and updated_since for incremental pulls, plus per-server version endpoints. A subregistry may add its own data under a namespaced _meta key such as com.example.subregistry/custom.
mcp.tc follows that pattern. Its server owner docs list what the checker reads for a suggested server: the server/discover or initialize answer with serverInfo, the tool list with annotations, the 401 and OAuth metadata for sign-in, the card at {endpoint}/server-card, the catalog at /.well-known/ai-catalog.json (or its older name /.well-known/ard.json), the official MCP Registry entry (checked hourly), and server.json, package.json, pyproject.toml, manifest.json and the README from the repository or package page. It never sends credentials and never runs the server's code. A listing then goes live at https://mcp.tc/i/{slug} with the setup steps for each client, each using the server's own URL or package.
The output side is https://mcp.tc/v0.1/servers, a read-only copy of the registry's read API (version 0.1, schema 2025-12-11) filled with mcp.tc's approved listings. It takes search, limit, cursor, updated_since and include_deleted; every entry carries _meta["tc.mcp/listing"] with the slug, category, verified flag, auth type, status and dates; and a listing that was removed or renamed stays visible as "status": "deleted" for 180 days when you pass updated_since or include_deleted. On 11 November 2026 that feed covers 1,432 approved listings, 1,108 remote and 324 local.
curl -s 'https://mcp.tc/v0.1/servers?search=weather&limit=5'One more well-known file closes the loop. RFC 9727, from June 2025, defines /.well-known/api-catalog as a linkset (application/linkset+json) that lists a publisher's APIs. mcp.tc's copy has three anchors: the registry API, the MCP endpoint (with the server card as its service-desc) and the JSON search index. A crawler that starts from any mcp.tc page can follow the Link header to that catalog and reach the card, the API and the docs without a prior configuration.
How do I publish a server card for my own server?
Publishing a server card takes four steps: write a JSON document with the four required fields and your remotes entry, serve it at <endpoint>/server-card with the CORS, cache and content-type headers from the discovery document, list it in /.well-known/ai-catalog.json, and then check it the way a client or directory would.
Generate the card. The mcp-tc command-line tool builds one from your
package.json, and aserver.jsonfor the official registry at the same time:bashnpx mcp-tc card --url https://mcp.example.com/mcp --name com.example/example-server --out server-card.json --server-json server.jsonWith
--urlthe command also reads your running server; add--offlineto use the URL without connecting. The registry name comes from--name, then frommcpNameinpackage.json, then from the repository or homepage. The tool stops instead of truncating a description longer than 100 characters, which is the schema's limit. Secrets passed with--headerfor the handshake are never written to the files.Serve it. Route
GET /mcp/server-card(for an endpoint at/mcp) to the file with the headers shown earlier. Keep the card'sname,version,title,descriptionandiconsin step with whatserver/discoverreturns, because the discovery document says the runtime values (serverInfo,supportedVersionsand the transports at each remote) SHOULD NOT contradict what the card declares.Add the catalog. Publish
/.well-known/ai-catalog.jsonon your domain with one entry per card,typeset toapplication/mcp-server-card+jsonandurlpointing at the card. If several products on one domain run separate MCP servers, each gets its own entry.Check it. Run the same read a directory would:
bashnpx mcp-tc check https://mcp.example.com/mcpchecktries both handshake styles (server/discoverfor 2026-07-28 andinitializefor 2025-11-25 and earlier), readsserverInfoandtools/listwith each tool's description andreadOnlyHintanddestructiveHint, inspects the 401 and OAuth metadata, and looks for the card at<endpoint>/server-cardand/.well-known/mcp/server-card.json. It exits with code 6 when it finds errors, and its report lists a missing card and a missingserver/discoveranswer as tips. It cannot tell you whether mcp.tc will list the server.
Two optional steps follow. To reach every aggregator, publish server.json to the official registry; the registry publishing guide on this blog walks through namespaces, ownership proof and mcp-publisher. To suggest the server to mcp.tc directly, paste its URL at mcp.tc/submit or run npx mcp-tc submit https://mcp.example.com/mcp, which waits for the check to finish. A suggestion goes live without review only when the server answered, nothing was flagged, and the name or vendor matches the server's domain; everything else waits for a moderator.
How much should a client trust a server card?
A client should treat a server card as a hint about where to connect and nothing more: the discovery document says clients "MUST NOT treat Server Card contents as authoritative for security or access-control decisions" and SHOULD verify the card's claims against the live connection, and the server/discover page adds that serverInfo is self-reported and unverified by the protocol.
In practice that means three comparisons after the first request. The card's name and version against serverInfo; the card's supportedProtocolVersions against supportedVersions; and the card's remotes[].type against the transport that answered. Where they differ, the live values win. The SEP frames the stakes plainly: because cards are advisory and verified against runtime metadata, a tampered card "primarily affects discoverability rather than security".
The card also tells you nothing about tools, by design, so the tool list only arrives from tools/list once you connect. That is where a directory's live reads add something. Each mcp.tc listing shows the tools mcp.tc could read without signing in, and its History tab records tools that were added or removed, changed descriptions, schemas, annotations and server instructions, with the date and time, from reads every 3 hours. A change is recorded only after two reads agree. On 11 November 2026, 489 listings have a watched tool list, and the history began on 2026-10-06. The changes docs spell out the limits: servers that require sign-in before listing tools have no watched list, tools shown only to some clients stay invisible, and a change undone between two reads can be missed. The history helps you notice changes; it is not a scanner and approves nothing.
The verified checkmark answers a narrower question than the card does: who runs the server. It appears when the admin has checked an official server of a well-known vendor, or when the server's domain owner added a DNS TXT record. It is not a security review either. A card says "this is the endpoint for com.example/example-server"; the checkmark says "the owner of example.com confirmed this listing".
What you can do next on mcp.tc
- Fetch
https://mcp.tc/mcp/server-cardandhttps://mcp.tc/.well-known/ai-catalog.jsonto see a card and a catalog that follow the extension's rules, then copy the shape for your own server. - Add mcp.tc's read-only MCP server to a client (setup for each client is on the docs page) and ask your assistant to search the directory; the
get_servertool returns a server's own URL or install command and the setup steps for the client you name. - Run
npx mcp-tc checkagainst your endpoint before you announce a card, andnpx mcp-tc cardto generate the card andserver.jsontogether. - Browse the directory with the no-sign-in filter to find remote servers you can read right away; on 11 November 2026 there are 366 of them.
- Suggest a server that is missing at mcp.tc/submit; the check runs automatically and no account is needed.
- Point a client that understands the registry API at
https://mcp.tc/v0.1/servers; the API docs show the parameters, and the VS Code registry post shows the one setting that uses it.
FAQ
Is a server card required for an MCP server?
No. SEP-2127 calls server cards optional and additive: a server without a card works through normal MCP connections and runtime discovery, and a client that does not read cards uses its configured endpoints as before. What the 2026-07-28 specification does require is server/discover, the in-protocol method every server MUST implement. The card is the pre-connection layer on top of it, aimed at crawlers, directories and clients that want to configure themselves from a URL.
Where should I put the server card: /.well-known or /server-card?
The extension's discovery document reserves one location, <streamable-http-url>/server-card, so a server at https://mcp.example.com/mcp serves its card at https://mcp.example.com/mcp/server-card. Any other unreserved HTTPS URL is allowed too. There is no well-known path for individual cards; the well-known file is /.well-known/ai-catalog.json, a per-domain catalog whose entries link to each card. The discovery document considered a /.well-known/mcp/server-card path and set it aside because the catalog already carries each card's URL; mcp.tc serves a second copy at /.well-known/mcp/server-card.json, and mcp-tc check reads both paths.
Does a server card list the server's tools?
No. The schema has no field for tools, resources or prompts, and the SEP explains why: those primitives can depend on the signed-in user, the session, configuration and deployment state, so a static file cannot describe them reliably. Clients list them at runtime with tools/list, resources/list and prompts/list. The card is also silent about capabilities and extension support; both come from server/discover. If you need to watch a server's tool list over time, a directory with repeated reads, such as the History tab on an mcp.tc listing, is the place to look.
Can a local stdio server have a server card?
Not under the current extension. SEP-2127 says cards "describe remote MCP connectivity only", and the schema's remotes[].type accepts only streamable-http and sse. Local packages are described by the MCP Registry's server.json, whose packages array names the npm, PyPI or other package and its stdio transport. A server that offers both a hosted endpoint and a package can have a card for the endpoint and a server.json that lists both.
What happens when a card and the live server disagree?
The live server wins. SEP-2127 says the two SHOULD stay aligned and that clients SHOULD prefer the server/discover values when they differ, and the discovery document forbids using card contents for security or access-control decisions. Clients compare the card's name, version, supported protocol versions and transport against the first response. A stale card mostly costs you discoverability: a client may pick a protocol version the server no longer offers and retry after an UnsupportedProtocolVersionError.
How does mcp.tc read my server card?
When a server is suggested, mcp.tc reads {endpoint}/server-card and the catalog at /.well-known/ai-catalog.json (or /.well-known/ard.json) on the server's domain, together with the live handshake, the tool list, the 401 and OAuth metadata, the official MCP Registry entry and the public package or repository files. It never sends credentials and never runs code. The card is one of the sources for the listing's icons, where icons from the live server take priority over the registry, the card and the website, and the live reads fill the tools. Owners can then prove the listing is theirs and edit it.
Fonti
- modelcontextprotocol.io/seps/2127-mcp-server-cards.md
- github.com/modelcontextprotocol/ext-server-card
- github.com/modelcontextprotocol/ext-server-card/blob/main/docs/discovery.md
- modelcontextprotocol.io/extensions/overview.md
- modelcontextprotocol.io/specification/2026-07-28/server/discover
- modelcontextprotocol.io/specification/2026-07-28/changelog
- modelcontextprotocol.io/registry/about
- modelcontextprotocol.io/registry/registry-aggregators
- modelcontextprotocol.io/registry/remote-servers
- www.rfc-editor.org/rfc/rfc8615.html
- www.rfc-editor.org/rfc/rfc9727.html