MCP Server Card — how to make your site agent-ready

What it is

A Model Context Protocol Server Card is a JSON document describing an MCP server: its name, version, transport, authentication requirements, and the tools/prompts/resources it exposes. Proposed in modelcontextprotocol issue #1649. The canonical location is /.well-known/mcp/server-card.json.

Why it matters

MCP is the fastest-growing standard for agent-tool integration (Claude Desktop, Cursor, OpenCode, Windsurf, Zed, etc. all speak it).
A Server Card lets an agent connect to your server before making any request — it knows the auth story, the tools, the transport, up front.
This is one of the highest-impact, highest-leverage agent signals a site can ship.

Remediation Prompt

I want to improve my site's agent readiness. Please implement the following fix for MCP Server Card across our codebase.

Instructions:
Please fix the MCP Server Card issue on my site so it is agent-ready.

How we test it

Step	Method	URL	Accept
A	GET	`/.well-known/mcp/server-card.json`	`application/json`
B	GET	`/.well-known/mcp-server-card.json` (legacy draft path — observational, lower credit)

Body cap 256 KB. Parse JSON. Validate against the schema referenced by $schema: https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json.

Ship a bundled copy of that schema in src/scanner/checks/schemas/mcp-server-card.json and revalidate against it for offline scans.

Why This Is A Big Weight Check

Weight: 8 (highest in the Capabilities category after agent-skills). Because it is genuinely capability-defining, and its presence is very rare today — so sites that ship it meaningfully stand out.

Pass Warn Fail Matrix

Condition	Status	Score
A exists + passes schema + has ≥1 tool	pass	1.0
A exists + schema valid + tools=[]	warn	0.5
B exists but not A	warn	0.6
Exists but schema fails (required fields missing)	warn	0.3
404 on both	fail	0.0

Sub Tests

id	Weight	Pass when
`card-present`	0.3	200 on A or B
`schema-valid`	0.3	Passes JSON schema validation
`has-tools`	0.2	≥1 tool with name + inputSchema
`has-auth-info`	0.1	`authentication` block present (even if `required: false`)
`canonical-path`	0.1	Served at A (not the legacy path)

Remediation Prompt

Please publish an MCP Server Card at /.well-known/mcp/server-card.json so MCP-capable agents can connect to my server without any hand-written configuration.

Use this template and fill in real values:

    {
      "$schema": "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
      "version": "1.0",
      "protocolVersion": "2025-06-18",
      "serverInfo": {
        "name": "my-server",
        "title": "My Product MCP",
        "version": "1.0.0"
      },
      "description": "One short sentence describing what this server is for.",
      "transport": {
        "type": "streamable-http",
        "endpoint": "https://example.com/mcp"
      },
      "authentication": {
        "required": false
      },
      "tools": [
        {
          "name": "search",
          "title": "Search",
          "description": "Search my product's knowledge base.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "query": { "type": "string", "description": "What to search for." }
            },
            "required": ["query"]
          }
        }
      ]
    }

Rules:
- Serve with Content-Type: application/json.
- The transport.endpoint must actually exist and speak MCP.
- If authentication is required, set `required: true` and either include `oauth` pointing to an RFC 8414 authorization-server metadata URL, or describe the bearer scheme.
- Keep the tool list tight. Only include tools you have tested.
- Add a Link response header on the homepage:
  Link: </.well-known/mcp/server-card.json>; rel="mcp-server-card"; type="application/json"

Implementation Examples

Next.js route handler

// src/app/.well-known/mcp/server-card.json/route.ts
export function GET() {
  return Response.json({
    $schema: 'https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json',
    version: '1.0',
    protocolVersion: '2025-06-18',
    serverInfo: { name: 'aide', title: 'aide', version: '1.0.0' },
    description: 'Scan a website for AI-agent readiness.',
    transport: { type: 'streamable-http', endpoint: 'https://aide.xyz/api/mcp' },
    authentication: { required: false },
    tools: [/* ... */],
  });
}

Note: Next.js's static route path uses literal .well-known dirname — fine on Unix; on Windows you may need a dynamic route.

Common Mistakes

endpoint in transport is a placeholder URL that doesn't actually serve MCP.
Using stdio transport in the card when it's a remote server — invalid.
Listing tools that don't exist yet.
Returning the card with text/plain content-type.
Claiming authentication: { required: false } but the server actually returns 401 to unauthenticated requests.

References

Test Fixtures

pass-full.json
warn-empty-tools.json
warn-legacy-path.json (served at /.well-known/mcp-server-card.json only)
warn-schema-fail.json (missing required fields)
fail-404.json

← Previous Check

Markdown Content Negotiation

Next Check →

OAuth Authorization Server Metadata (RFC 8414)