Website guide
Help AI agents find your MCP server: server cards and /.well-known discovery
If you run or offer an MCP server, a person has to paste its address into their AI app before anything works. A server card is a public JSON document that describes the server so software can find it first. It is new, optional and still settling. This guide says what is documented, what is not and what the Onbiom scan checks.
Sources read on 30 October 2026; these pages change, so check them before you rely on this guide.
What is a server card?
MCP is a way for AI apps to connect to a service's tools. The MCP proposal SEP-2127 describes a server card as a static metadata document for pre-connection discovery: the server's identity, its remote endpoints and the protocol versions it supports. It deliberately leaves out the tool list, because tools can differ by user and session; those are still read from the live server.
Cards are public. The same page says a card must not contain credentials, internal network details or user-specific data. Cards are also optional: servers without one keep working.
What is its status?
The sources disagree in tone, so read both. The SEP page marks SEP-2127 as Final, type Extensions Track. The extension repository that holds the schema still describes itself as "Experimental" and "not an accepted or official MCP extension", and its discovery document is labelled "draft". Treat the format as young and subject to change.
Where does a client look?
Per that discovery document, clients should fetch an AI catalog at https://{domain}/.well-known/ai-catalog.json. Each catalog entry has an identifier, a type of application/mcp-server-card+json and either a url or inline data. The recommended card location is the MCP endpoint plus /server-card; for https://example.com/mcp that is https://example.com/mcp/server-card. The same document advises against /.well-known/mcp/server-card, although some publishers use it anyway.
A minimal example
An illustrative catalog at /.well-known/ai-catalog.json:
{"entries": [{"identifier": "urn:air:example.com:mcp:example", "type": "application/mcp-server-card+json", "url": "https://example.com/mcp/server-card"}]}An illustrative card served at that address, with the content type application/mcp-server-card+json:
{"name": "com.example/mcp", "version": "1.0.0", "remotes": [{"type": "streamable-http", "url": "https://example.com/mcp"}]}The field names come from the discovery document and the SEP; check the schema in the extension repository for the full list. The document also asks for HTTPS and for cache and CORS headers on public cards.
What about a DNS record?
An individual IETF Internet-Draft proposes a TXT record at _mcp.<domain> carrying the endpoint address. The page says it is not endorsed by the IETF and has no formal standing, and it expires on 19 November 2026. SEP-2127 says DNS discovery was considered and not chosen, because it would work only at domain level. We found no MCP specification that adopts it.
Which clients read it?
We found no client documentation saying it reads server cards. The SEP lists experimental reference implementations in two SDKs and in the Goose client, which are demonstrations rather than product documentation. A publisher, Resend, announced a catalog and card on 26 October 2026 and says "a client that supports these discovery methods" can add it from the domain, without naming one. Do not assume any particular assistant will find your server this way.
What does the Onbiom free check report?
The free website scan looks for an MCP endpoint and, if it finds one, reports separate discovery checks that never change the website score. Names as shown: Server card, Card matches handshake, Negotiated protocol version, OAuth protected-resource metadata, DNS _mcp TXT record and a root-document catalog link. Each is pass, fail, unknown or not applicable.
For the server card it tries, in order and stopping at the first valid card: the AI catalog, <endpoint>/server-card, /.well-known/mcp/server-card.json and /.well-known/mcp.json. The result says whether the card came from the AI catalog or only from a legacy path. A valid card is a JSON object with name, version and a non-empty remotes list. Catalog addresses on other hosts are never fetched. If a request times out, the result is unknown, not fail.
Limits: every request is HTTPS to the same host with a four-second deadline and a 256 KB body cap, and the whole scan stops at 18 seconds. The TXT lookup reads only _mcp. plus the scanned host through one public resolver. The scan does not show whether any client reads your card. See the how Onbiom checks your site.
Onbiom publishes its own catalog and card the same way, at /.well-known/ai-catalog.json and /mcp/server-card on onbiom.com.
Check yours
Run the free website scan on your domain and read the discovery checks. If you want to know when your server's tools change after you publish a card, see MCP monitoring.
Sources and further reading
Last reviewed: