What is an MCP Server Card (mcp.json) and How to Add One

Learn how Model Context Protocol (MCP) server cards work, what to put in your mcp.json file, and how AI agents discover your tools and services automatically.

What is MCP?

Model Context Protocol (MCP) is an open standard from Anthropic that lets AI agents (like Claude) discover and call tools on your server — searching your database, reading files, triggering actions — without custom integration work. Think of it as an API description layer designed for AI, not humans.

What is a Server Card (mcp.json)?

A Server Card is a JSON file at /.well-known/mcp.json (or /mcp.json) that advertises your MCP server's capabilities. When an AI agent visits a site, it checks for this file to learn which tools are available, their schemas, and how to authenticate.

Minimal mcp.json example

Here is the smallest valid Server Card. It declares one tool — a search capability — that an AI agent can call:

/.well-known/mcp.json

{
  "name": "Acme Search",
  "description": "Search Acme's product catalog and documentation",
  "version": "1.0.0",
  "servers": [
    {
      "url": "https://api.acme.dev/mcp",
      "transport": "http"
    }
  ],
  "tools": [
    {
      "name": "search",
      "description": "Search the Acme product catalog",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Search query" }
        },
        "required": ["query"]
      }
    }
  ]
}

Where to place the file

Place the file at /.well-known/mcp.json on your domain. In Next.js, put it at /public/.well-known/mcp.json. Verify with: curl https://yourdomain.com/.well-known/mcp.json

Authentication with OAuth

MCP servers that require authentication should implement OAuth 2.0 discovery at /.well-known/oauth-authorization-server. This lets AI agents obtain tokens automatically without hardcoded credentials. See our OAuth discovery guide for details.

Full MCP documentation

The complete MCP specification, SDKs for Python/TypeScript/Go, and example servers are at modelcontextprotocol.io. Anthropic's Claude.ai automatically discovers MCP servers for users who connect domains.