MCP Server Card

What is MCP Server Card?

MCP Server Card is a JSON manifest at /.well-known/mcp/server-card.json that describes your MCP server: name, version, transport, and capabilities. It lets AI agents automatically discover an MCP server by domain without any manual setup.

MCP (Model Context Protocol) is Anthropic’s open protocol for standardizing how AI agents interact with tools and data. An agent “connects” to a server and receives a set of tools, resources, and prompts.

Analogy: if your API is a shop, the MCP Server Card is the sign showing opening hours and what’s on offer.

Why do you need MCP Server Card?

Before MCP discovery was standardized, every integration required manual setup: a developer would hand-configure the URL and describe the tools. At scale, with many agents and servers, this doesn’t work.

MCP Server Card solves the federated tool discovery problem:

• Automatic configuration — an agent checks /.well-known/mcp/server-card.json and immediately sees available tools
• Versioning — the client verifies protocol version and compatibility
• Security — the card describes authentication requirements (OAuth, API key)

Especially useful for: SaaS with an API, DevTools, enterprise knowledge bases, and any service designed for AI agents.

How do you implement MCP Server Card?

Minimal card:

{
  "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
  }
}

Extended variant with authentication:

{
  "serverInfo": {
    "name": "Example CRM MCP Server",
    "version": "1.2.0",
    "description": "CRM data and workflow automation via MCP",
    "contact": {
      "email": "mcp@example.com",
      "url": "https://example.com/mcp-docs"
    }
  },
  "transport": {
    "type": "http",
    "endpoint": "https://api.example.com/mcp/v1",
    "protocol": "MCP/1.0"
  },
  "capabilities": {
    "tools": true,
    "resources": true,
    "prompts": true
  },
  "authentication": {
    "required": true,
    "methods": ["oauth2", "api-key"],
    "oauthEndpoint": "https://auth.example.com/.well-known/openid-configuration"
  },
  "rateLimit": {
    "requestsPerMinute": 60,
    "headerName": "RateLimit-Remaining"
  }
}

Publishing in Astro:

// src/pages/.well-known/mcp/server-card.json.ts
export async function GET() {
  const card = {
    serverInfo: { name: 'My MCP', version: '1.0.0' },
    transport: { type: 'http', endpoint: 'https://example.com/api/mcp' },
    capabilities: { tools: true }
  };
  return new Response(JSON.stringify(card), {
    headers: { 'Content-Type': 'application/json' }
  });
}

For Nginx (static file):

location = /.well-known/mcp/server-card.json {
    alias /var/www/well-known/mcp-server-card.json;
    add_header Content-Type application/json;
    add_header Access-Control-Allow-Origin *;
}

How do we check MCP Server Card?

The scanner checks three paths in order of priority:

1. /.well-known/mcp/server-card.json
2. /.well-known/mcp/server-cards.json
3. /.well-known/mcp.json

For each path the scanner verifies:

1. HTTP status — if none returned 200 → fail
2. Valid JSON — body parses without errors
3. Required fields — serverInfo.name and serverInfo.version are present
4. Transport — transport.type and transport.endpoint are present
5. Capabilities — the capabilities object is present

pass — at least one path returned HTTP 200 with valid JSON and all required fields. fail — all paths are unreachable or the JSON is invalid.