# 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.

Published 2026-11-12 by mcp.tc. Canonical: https://mcp.tc/blog/mcp-server-cards-discovery

**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](https://modelcontextprotocol.io/seps/2127-mcp-server-cards.md), 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](https://github.com/modelcontextprotocol/ext-server-card), where `schema.ts` is the source of truth and `schema.json` is generated from it. The [extensions overview](https://modelcontextprotocol.io/extensions/overview.md) 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](https://github.com/modelcontextprotocol/ext-server-card/blob/main/docs/discovery.md) 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=3600` and an `ETag` are a SHOULD, with `304 Not Modified` when a client sends `If-None-Match`.
- The media type `application/mcp-server-card+json` is a SHOULD on both sides: servers honor it, clients send it in `Accept`.
- Rate limiting of the card endpoint is a SHOULD.

A response that follows every rule looks like this:

```http
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: ETag
```

To see a live card, fetch mcp.tc's:

```bash
curl -s -H 'Accept: application/mcp-server-card+json' https://mcp.tc/mcp/server-card
```

On 11 November 2026 it returns this (icons shortened):

```json
{
  "$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](https://mcp.tc/docs/mcp) 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](https://www.rfc-editor.org/rfc/rfc8615.html), 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:

```json
{
  "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](https://mcp.tc/docs/api) 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](https://modelcontextprotocol.io/specification/2026-07-28/changelog) added `server/discover` and says servers MUST implement it. The [discover page](https://modelcontextprotocol.io/specification/2026-07-28/server/discover) 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](https://modelcontextprotocol.io/registry/remote-servers) 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](https://modelcontextprotocol.io/registry/about) 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](https://modelcontextprotocol.io/registry/registry-aggregators) 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](https://mcp.tc/docs/server-owners) 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.

```bash
curl -s 'https://mcp.tc/v0.1/servers?search=weather&limit=5'
```

One more well-known file closes the loop. [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727.html), 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.

1. Generate the card. The [mcp-tc command-line tool](https://mcp.tc/cli) builds one from your `package.json`, and a `server.json` for the official registry at the same time:

   ```bash
   npx mcp-tc card --url https://mcp.example.com/mcp --name com.example/example-server --out server-card.json --server-json server.json
   ```

   With `--url` the command also reads your running server; add `--offline` to use the URL without connecting. The registry name comes from `--name`, then from `mcpName` in `package.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 `--header` for the handshake are never written to the files.

2. Serve it. Route `GET /mcp/server-card` (for an endpoint at `/mcp`) to the file with the headers shown earlier. Keep the card's `name`, `version`, `title`, `description` and `icons` in step with what `server/discover` returns, because the discovery document says the runtime values (`serverInfo`, `supportedVersions` and the transports at each remote) SHOULD NOT contradict what the card declares.

3. Add the catalog. Publish `/.well-known/ai-catalog.json` on your domain with one entry per card, `type` set to `application/mcp-server-card+json` and `url` pointing at the card. If several products on one domain run separate MCP servers, each gets its own entry.

4. Check it. Run the same read a directory would:

   ```bash
   npx mcp-tc check https://mcp.example.com/mcp
   ```

   `check` tries both handshake styles (`server/discover` for 2026-07-28 and `initialize` for 2025-11-25 and earlier), reads `serverInfo` and `tools/list` with each tool's description and `readOnlyHint` and `destructiveHint`, inspects the 401 and OAuth metadata, and looks for the card at `<endpoint>/server-card` and `/.well-known/mcp/server-card.json`. It exits with code 6 when it finds errors, and its report lists a missing card and a missing `server/discover` answer 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](https://mcp.tc/blog/publish-mcp-server-mcp-registry) walks through namespaces, ownership proof and `mcp-publisher`. To suggest the server to mcp.tc directly, paste its URL at [mcp.tc/submit](https://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](https://mcp.tc/docs/changes) 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](https://mcp.tc/verify) 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-card` and `https://mcp.tc/.well-known/ai-catalog.json` to 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](https://mcp.tc/docs/mcp)) and ask your assistant to search the directory; the `get_server` tool returns a server's own URL or install command and the setup steps for the client you name.
- Run `npx mcp-tc check` against your endpoint before you announce a card, and `npx mcp-tc card` to generate the card and `server.json` together.
- Browse the [directory](https://mcp.tc/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](https://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](https://mcp.tc/docs/api) show the parameters, and the [VS Code registry post](https://mcp.tc/blog/mcp-registry-vs-code) 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.

## Sources

- <https://modelcontextprotocol.io/seps/2127-mcp-server-cards.md>
- <https://github.com/modelcontextprotocol/ext-server-card>
- <https://github.com/modelcontextprotocol/ext-server-card/blob/main/docs/discovery.md>
- <https://modelcontextprotocol.io/extensions/overview.md>
- <https://modelcontextprotocol.io/specification/2026-07-28/server/discover>
- <https://modelcontextprotocol.io/specification/2026-07-28/changelog>
- <https://modelcontextprotocol.io/registry/about>
- <https://modelcontextprotocol.io/registry/registry-aggregators>
- <https://modelcontextprotocol.io/registry/remote-servers>
- <https://www.rfc-editor.org/rfc/rfc8615.html>
- <https://www.rfc-editor.org/rfc/rfc9727.html>
