MCP Server Card: how agents discover your MCP server

What it is

An MCP Server Card is a JSON manifest at /.well-known/mcp/server-card.json describing your MCP server: name, version, transport, capabilities. MCP (Model Context Protocol) is an open protocol for connecting AI agents to tools and data. The card is the server’s “sign” — agents find it automatically.

Why it matters for AI agents

Without discovery, every MCP integration is manual: a developer hardcodes the URL and tools. That doesn’t scale. The Server Card enables federated tool discovery: an agent reads the card by domain and immediately sees the available tools/resources/prompts, the protocol version, and auth requirements. Especially useful for SaaS, DevTools, and corporate knowledge bases built for agents.

Minimal working example

{
  "serverInfo": { "name": "My Service MCP", "version": "1.0.0" },
  "transport": { "type": "http", "endpoint": "https://api.example.com/mcp" },
  "capabilities": { "tools": true, "resources": false, "prompts": false }
}

For an authenticated server add an authentication block (oauth2/api-key) — see the OAuth Protected Resource guide.

Right vs wrong

Right	Wrong
Served at /.well-known/mcp/server-card.json, application/json	An arbitrary path
Has serverInfo.name + serverInfo.version	Missing required fields
Has transport.type + transport.endpoint	No transport — the agent can’t connect
Has a capabilities object	No capabilities — unclear what the server does

Common mistakes

• Invalid JSON — the card is discarded.
• No transport.endpoint — discovery is useless.
• The endpoint isn’t a working MCP — the agent connects and fails.
• No CORS (Access-Control-Allow-Origin) — browser clients can’t read it.

How to verify

The scanner tries three paths in order: /.well-known/mcp/server-card.json, /.well-known/mcp/server-cards.json, /.well-known/mcp.json — and checks the JSON plus required fields (serverInfo.name/version, transport, capabilities). Manually:

curl -s https://example.com/.well-known/mcp/server-card.json | jq .