Publish an MCP server card

Describe an MCP server in a small JSON file that agents and scanners can read before they connect, using Ora's own cards as the worked example. 19 of 7,470 probed top-10,000 domains serve an MCP discovery file at /.well-known/mcp.json. First step: Choose the address: the server URL plus /server-card, or an entry in /.well-known/ai-catalog.json.

Steps

1. Choose the address: the server URL plus /server-card, or an entry in /.well-known/ai-catalog.json.
2. Write the card: name, title, version, description, websiteUrl, icons and a remotes entry with type, url and supportedProtocolVersions.
3. Declare the kind of server, product or docs, so a scanner judges it on the right bar.
4. Serve it as JSON and link it from the docs; agents follow links.
5. Scan the server and confirm the server-card check passes.

What the sources say

• Ora serves a server card for its main MCP server at ora.ai/api/mcp/server-card; it names the server ai.ora/mcp, kind product, and lists a streamable-http remote at ora.ai/api/mcp with protocol versions 2025-11-25 and 2025-06-18. (ora.ai, read 5 November 2026)
• Ora serves a second card at ora.ai/api/docs/mcp/server-card for its read-only docs server, declaring the kind docs; both cards point their $schema at static.modelcontextprotocol.io/schemas/v1/server-card.schema.json. (ora.ai, read 5 November 2026)
• Ora's server-card check looks for a card at the server URL plus /server-card or an entry in /.well-known/ai-catalog.json. (ora.ai, read 5 November 2026)
• Ora's full documentation says its docs MCP server's card is at https://ora.ai/api/docs/mcp/server-card. (ora.ai, read 5 November 2026)
• The MCP maintainers' roadmap says server cards continue in a Working Group. (blog.modelcontextprotocol.io, read 4 November 2026)
• The 2026-07-28 core specification prescribes no .well-known discovery file; server cards are still Working Group work. (modelcontextprotocol.io, read 4 November 2026)
• Mintlify says it publishes discovery files at /.well-known/mcp, /.well-known/mcp.json, /.well-known/mcp/server-card.json and /.well-known/mcp/server-cards.json. (www.mintlify.com, read 4 November 2026)

A worked example: Ora's two cards

Ora serves a card for each of its two MCP servers. They share a schema and differ in name, kind and address; the protocol versions are the same. The main card, as served on 5 November 2026:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
  "name": "ai.ora/mcp",
  "title": "ora",
  "version": "1.38.0",
  "description": "Find products, check agent-readiness scores, run scans and checks, and read or submit feedback.",
  "websiteUrl": "https://ora.ai/mcp",
  "icons": [
    {
      "src": "https://ora.ai/icon.png"
    }
  ],
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://ora.ai/api/mcp",
      "supportedProtocolVersions": [
        "2025-11-25",
        "2025-06-18"
      ]
    }
  ],
  "url": "https://ora.ai/api/mcp",
  "transport": "streamable-http",
  "kind": "product",
  "_meta": {
    "ai.ora/kind": "product"
  }
}

Who publishes a discovery file

The Act Layer Census probed 7,470 of the top 10,000 domains for /.well-known/mcp.json and found 19 valid files (0.25%). Of the 1,336 companies in the directory, 39 serve one. A card is a different file from that manifest; Ora's check accepts a card at the server URL plus /server-card or a listing in /.well-known/ai-catalog.json. The census.

The shape of a card is still settling: the MCP maintainers keep server cards in a Working Group, and the core specification names no discovery file. Publish the card where a scanner looks and keep the fields in the schema's own names. How Ora checks it.