Remote MCP Server Discovery: How to Publish a Server Card

You built a remote MCP server so AI agents could use your product without scraping it. Good. Now ask a harder question: how does an agent find it? Most teams put the URL in their docs and hope someone pastes it into a config file. That does nothing for a client crawling your domain.

The MCP project has an answer. SEP-2127, the MCP Server Cards proposal, now carries Final status on the Extensions Track. It gives every remote MCP server a small, public JSON file that says who it is, where to connect and which protocol versions it speaks. Here's how to ship one properly.

TL;DR

A Server Card is a static JSON document describing a remote MCP server: identity, endpoint URLs and supported protocol versions. It never lists tools.
The recommended location is <your-streamable-http-url>/server-card, and an AI Catalog at /.well-known/ai-catalog.json can point to it for domain-level discovery.
It takes about an hour to add, it's fully optional and backward compatible, and it closes the gap between "we have an MCP server" and "agents can find our MCP server."

What a remote MCP server card actually is

The SEP describes the problem bluntly: clients have "no standardized discovery mechanism," users "must manually configure transport URLs for each server," and runtime discovery only helps once a client already knows where to connect.

The new 2026-07-28 MCP specification added a server/discover method, but that's an in-protocol call. You need the endpoint first. Server Cards fill the step before that: out-of-band, cacheable metadata a client can fetch with a plain HTTP GET.

A card covers:

Identity: name, version, description, plus optional title, icons, repository and websiteUrl
Connection details: remotes, each with a transport type, URL, and optional headers or variable templates
Compatibility: supportedProtocolVersions, so a client knows whether it can even try
Extras: namespaced _meta for vendor data

What it deliberately leaves out matters just as much. Tools, resources and prompts aren't in the card, because they change per user, per session and per feature flag. Clients still get those live through tools/list once connected. A stale tool list would be worse than none.

Why discovery matters for your website

If your SaaS product, store or content site has an API, your MCP server is the clean front door for agents. Without a discoverable card, an agent that lands on your domain has two options: guess, or fall back to driving your UI like a human would. That's slower and more likely to hit bot protection.

The SEP names three use cases a card enables:

Autoconfiguration: an IDE or agent client pointed at your domain configures itself.
Automated discovery: registries and crawlers can index your server without someone filing it by hand.
Lower latency: clients can show your server's name and details without opening a live connection.

Reference implementations exist as experimental pull requests for the Python SDK (#2951) and the Go SDK (#1024), and the SEP cites a Goose client demo that discovers and installs servers from cards. Third-party readiness checkers, such as Lumar's agentic readiness docs, already probe for cards and flag broken ones. Discovery is becoming something that gets measured.

Technical breakdown: where the card lives and what goes in it

The two discovery layers

Server Cards and the AI Catalog do different jobs. The card holds MCP-specific connection details. The catalog, published at /.well-known/ai-catalog.json, is protocol-agnostic and lists the AI artifacts a domain offers. It can link to or embed cards hosted elsewhere, which is handy if a SaaS platform runs the server on your behalf.

File	Location	Answers
Server Card	`<mcp-url>/server-card` (recommended)	Where do I connect, and with which protocol versions?
AI Catalog	`/.well-known/ai-catalog.json`	What AI endpoints does this domain offer?
Registry `server.json`	Official MCP Registry	How do I install this server, including local packages?
`server/discover`	Live MCP call	What does the server report right now?

If a card and server/discover disagree, the SEP says clients should trust the live answer.

A minimal card

Here's an illustrative card using the fields the SEP names. The authoritative schema lives in the extension repository's schema.ts, so validate against that before you ship.

{
  "name": "com.example/store-tools",
  "title": "Example Store Tools",
  "description": "Search the catalog and check order status.",
  "version": "1.4.0",
  "websiteUrl": "https://example.com/developers/mcp",
  "remotes": [
    { "type": "streamable-http", "url": "https://example.com/mcp" }
  ],
  "supportedProtocolVersions": ["2026-07-28", "2025-11-25"]
}

Serving it

Serve the card over HTTPS. The SEP says wide-open CORS is fine, since the file holds only public, read-only metadata. An nginx sketch:

location = /mcp/server-card {
  alias /var/www/mcp/server-card.json;
  default_type application/json;
  add_header Access-Control-Allow-Origin "*";
  add_header Cache-Control "public, max-age=3600";
}

Trade-offs to know

The filename has moved during drafting. Earlier guides used paths like /.well-known/mcp/server-card.json, and one implementation guide suggests redirecting old paths to the current one. That's sensible insurance. Also, a card is advisory. It helps clients find you, but it's never a substitute for real auth on the endpoint itself.

What it means for site owners

You run your own remote MCP server. Ship a card at the recommended path and add an AI Catalog entry. It's a cheap discoverability win.

A platform hosts your MCP server. Ask your vendor whether they publish per-tenant cards. If they do, link to yours from your own /.well-known/ai-catalog.json so agents landing on your domain can follow the trail.

You don't have an MCP server yet. A card won't help until there's something to describe. Start with the basics agents already read: clean JSON-LD, a public OpenAPI spec and an llms.txt file. Our explainer on WebMCP vs MCP covers which route fits which kind of site.

Cards are public by design, so the SEP says they must not include credentials, internal hostnames or user-specific data.

How to publish a server card: a checklist

Confirm your endpoint. Write down the absolute HTTPS URL of your Streamable HTTP endpoint. Relative URLs like example.com/mcp get flagged as "present but not connectable."
Write the card. Use reverse-DNS naming for name, a real version number and the protocol revisions you actually support.
Validate it against the schema in the experimental-ext-server-card repository.
Serve it at <mcp-url>/server-card with HTTPS, permissive CORS and a cache header.
Add an AI Catalog at /.well-known/ai-catalog.json that links to the card.
Strip secrets. No API keys, tokens or internal hosts. Anything header-related should be a template the client fills in.
Keep it in sync. Bump version and supportedProtocolVersions in the same deploy that changes the server.
Test it from outside. Run curl -i against the card and check the status, content type and CORS header.

Once it's live, run a free AgentReady scan on your domain. The MCP Presence pillar checks whether agents can discover an MCP server at all, and the API & Docs pillar shows if your OpenAPI spec and developer docs back it up.

Check your own site

This post maps to the MCP Presence (Server Discovery) pillar, which is 20% of the Agent Readiness Score. A low score there usually means agents can't find an MCP endpoint and have to scrape your pages instead. The score explainer breaks down all three pillars, and once you're live you can submit your site to the directory. A single-page scan is free and takes about a minute. Scan your site free.

Key takeaways

SEP-2127 is Final: Server Cards are the official, optional way to describe a remote MCP server before connecting.
Put the card at <mcp-url>/server-card and point to it from /.well-known/ai-catalog.json.
Cards carry identity, endpoints and protocol versions, never tool lists or secrets.
Live server/discover data wins if it disagrees with the card, so keep both in sync.
Use absolute HTTPS URLs and permissive CORS, or checkers will mark the card unusable.

FAQ

What is a remote MCP server?

A remote MCP server is a Model Context Protocol server you host on the web, usually over Streamable HTTP, instead of one that runs locally on a user's machine. AI clients connect to it by URL, list its tools at runtime and call them on the user's behalf. It's how a SaaS product or store exposes actions to agents without them scraping the UI.

Where should an MCP server card be hosted?

SEP-2127 reserves <streamable-http-url>/server-card as the recommended location, so if your endpoint is https://example.com/mcp, the card lives at https://example.com/mcp/server-card. Cards can sit at any unreserved URI, and an AI Catalog at /.well-known/ai-catalog.json can link to them, which lets clients discover every server a domain offers in one request.

Does a server card list my MCP tools?

No. The spec intentionally excludes tools, resources and prompts because they vary by user, session and configuration. A static file would go stale or mislead clients. Agents still discover your tools the normal way, by calling tools/list after they connect and authenticate.

Is a server card the same as the MCP Registry server.json?

No. The Registry's server.json describes registry entries, including locally installable packages and their runtime setup. A Server Card only describes remote connectivity and lives on your own domain. They share compatible field names where they overlap, so it's reasonable to publish both if you list your server in the registry.

If you already run a remote MCP server, the next step is small: write the card, serve it at /mcp/server-card and link it from an AI Catalog today. Then check that agents can actually see it. Run a free AgentReady scan.

Remote MCP Server Discovery: Publish a Server Card Agents Find