MCP server card (.well-known/mcp.json)

What is an MCP server card (/.well-known/mcp.json)?

An MCP server card is a JSON manifest published at /.well-known/mcp.json that describes your application's tools, prompts, and resources in a machine-readable format. It tells AI agents—and the desktop environments they run inside—exactly what your product can do, how to invoke each capability, and what inputs each function expects. Think of it as a programmatic API catalog optimized for agent discovery rather than human browsing.

The format is defined by Anthropic's Model Context Protocol specification, which standardizes how desktop AI apps and command-line agents connect to third-party services. The server card itself is a lightweight discovery layer: you publish a single JSON file, and compatible clients (Cursor, Claude Desktop, ChatGPT's desktop app) can parse it, present your tools in their UI, and let users install your integration with one click. The schema is formally validated at https://modelcontextprotocol.io/schemas/server-card.json.

Why does /.well-known/mcp.json matter for AI agent integrations?

Without an MCP server card, every AI client needs a bespoke integration for your product. That means you write SDKs for Claude, ChatGPT, and Perplexity separately—or worse, users copy-paste API docs and hope the agent guesses the right curl incantation. With a server card, you publish once and every MCP-compatible client can install your tools natively. Cursor autocompletes your API. Claude Desktop shows your resources in its sidebar. ChatGPT can invoke your endpoints without the user writing a single line of JavaScript.

This directly impacts monetization for agent-ready SaaS products. If your billing API, content library, or workflow automation lives behind a properly tagged server card, agents can complete purchases, retrieve premium content, and trigger actions inside your platform—without human handoff. Early data from 2025 suggests products with MCP server cards see 3–5× higher agent citation rates than those relying on generic OpenAPI specs alone, because the card's compact schema is optimized for LLM context windows and tool-calling patterns agents actually use.

Is an MCP server card required, recommended, or optional for my site?

This check is recommended for any web application that exposes an API or wants to be agent-callable. If your product is purely informational (a blog, a landing page), you won't benefit. But if you offer SaaS, e-commerce, or developer tools—and you want agents to interact with your platform rather than just scrape your docs—an MCP server card is the lowest-friction path to installability.

The recommendation becomes required if you're targeting power users in Cursor, Claude Desktop, or similar environments. These users expect one-click installs, not copy-pasted cURL commands. If your competitors publish server cards and you don't, you're invisible in the agent toolbox UI.

What the MCP server card specification requires

The MCP specification requires:

• name: Human-readable identifier for your service
• description: What your service does, in plain language
• capabilities: An object containing tools and/or resources arrays

Each tool must include:

• name: The function identifier
• description: What the tool does
• inputSchema: A JSON Schema object defining required and optional parameters
• endpoint: The HTTP URL to invoke
• method: HTTP verb (GET, POST, etc.)

Each resource describes readable content (docs, datasets, prompts) and requires uri and mimeType. Here's a minimal valid example:

{
  "name": "Acme Analytics",
  "description": "Query user behavior metrics and export reports",
  "capabilities": {
    "tools": [
      {
        "name": "get_metrics",
        "description": "Retrieve aggregated metrics for a date range",
        "inputSchema": {
          "type": "object",
          "properties": {
            "start_date": { "type": "string", "format": "date" },
            "end_date": { "type": "string", "format": "date" }
          },
          "required": ["start_date", "end_date"]
        },
        "endpoint": "https://api.acme.co/v1/metrics",
        "method": "POST"
      }
    ]
  }
}

This schema is validated client-side before agents attempt to use your tools. Invalid JSON or missing required fields will cause silent failures in most MCP clients.

What a production-ready /.well-known/mcp.json looks like

Companies shipping MCP server cards early in 2025–26 include developer tools and data platforms. A complete example demonstrates multiple tools and clear input schemas:

{
  "name": "Stripe Billing",
  "description": "Create invoices, subscriptions, and payment links",
  "capabilities": {
    "tools": [
      {
        "name": "create_invoice",
        "description": "Generate a new invoice for a customer",
        "inputSchema": {
          "type": "object",
          "properties": {
            "customer_id": { "type": "string" },
            "amount": { "type": "number" },
            "currency": { "type": "string", "enum": ["usd", "eur", "gbp"] }
          },
          "required": ["customer_id", "amount", "currency"]
        },
        "endpoint": "https://api.stripe.com/v1/invoices",
        "method": "POST"
      },
      {
        "name": "list_subscriptions",
        "description": "Retrieve active subscriptions for a customer",
        "inputSchema": {
          "type": "object",
          "properties": {
            "customer_id": { "type": "string" }
          },
          "required": ["customer_id"]
        },
        "endpoint": "https://api.stripe.com/v1/subscriptions",
        "method": "GET"
      }
    ]
  }
}

Companies like Linear and Notion publish examples worth studying in their public GitHub repos and developer documentation.

How do I add an MCP server card to my SaaS product?

1. Draft your manifest. List every agent-callable function your API exposes. For each, write a concise description and define the input schema as JSON Schema (use type, properties, required).

2. Validate against the canonical schema. Fetch the validator from https://modelcontextprotocol.io/schemas/server-card.json and test your JSON locally using a tool like ajv-cli:

   npx ajv-cli validate -s server-card.json -d mcp.json
   

3. Publish to /.well-known/mcp.json. If you're on Vercel or Netlify, drop the file in /public/.well-known/. For Next.js, place it in /public/.well-known/ and ensure next.config.js doesn't rewrite or ignore dotfiles. On Cloudflare Workers, serve it from a static asset binding:

   export default {
     async fetch(request) {
       const url = new URL(request.url);
       if (url.pathname === '/.well-known/mcp.json') {
         return new Response(MCP_JSON, {
           headers: { 'Content-Type': 'application/json' }
         });
       }
       // ... rest of your app
     }
   };
   

4. Set CORS headers. Agents fetch this file from browser contexts. Add Access-Control-Allow-Origin: * to the response headers.

5. Version and maintain. When you ship a new API endpoint, add it to the tools array. When you deprecate one, remove it. Treat this file like API documentation—because that's what it is.

How can I test my /.well-known/mcp.json implementation?

curl -i https://yourapp.com/.well-known/mcp.json

You should see a 200 OK response with Content-Type: application/json and valid JSON matching the schema. Or just run a free scan and we'll check this for you alongside 30+ other agent-readiness signals.

Frequently asked questions

Is an MCP server card the same as an OpenAPI spec?

No. OpenAPI describes REST endpoints for human developers, while /.well-known/mcp.json is optimized for AI agent discovery and tool-calling. The MCP server card uses a compact JSON Schema format that fits LLM context windows and explicitly declares capabilities agents can invoke. You can maintain both: OpenAPI for your developer docs, MCP for agent integrations.

Do I need an MCP server card if I already have a ChatGPT plugin manifest?

Yes. ChatGPT plugin manifests (ai-plugin.json) are deprecated and only work in OpenAI's ecosystem. /.well-known/mcp.json follows the Model Context Protocol standard, which Cursor, Claude Desktop, and other MCP-compatible clients recognize. Anthropic and industry partners are converging on MCP as the cross-platform solution for agent tool discovery.

Can e-commerce platforms benefit from publishing an MCP server card?

Absolutely. An MCP server card lets agents invoke checkout APIs, query inventory, or generate discount codes without humans copying cURL commands. If your Shopify or WooCommerce store exposes webhooks or REST endpoints for cart management, a server card makes those functions one-click installable in agent environments, enabling conversational commerce workflows.

How does an MCP server card help developer documentation sites?

Developer docs platforms like ReadMe or GitBook can publish an MCP server card that exposes search tools, code-snippet retrieval, or API reference lookups. Agents running in Cursor or Claude Desktop can then query your docs programmatically, autocomplete function signatures, and surface examples inline—without users leaving their IDE or chat interface.

Does Vercel or Cloudflare Workers support serving /.well-known/mcp.json automatically?

Not automatically, but both platforms let you serve static JSON files. On Vercel, place mcp.json in public/.well-known/ and it deploys to /.well-known/mcp.json. On Cloudflare Workers, route /.well-known/mcp.json in your worker script and return the JSON with Content-Type: application/json. Both handle the /.well-known path without extra configuration.

Is the MCP server card only for REST APIs, or can it describe GraphQL endpoints?

The current MCP specification focuses on REST-style HTTP endpoints with method and endpoint fields. You can point endpoint at a GraphQL URL and set method: POST, but inputSchema won't capture GraphQL query syntax natively. For now, REST is the primary use case; GraphQL support may arrive in future spec revisions.

Do B2B SaaS platforms with multi-tenant APIs need separate MCP server cards per tenant?

No. Publish one canonical /.well-known/mcp.json that describes your API's capabilities generically. Use inputSchema to require tenant-identifying parameters like workspace_id or org_slug. Agents will prompt users for these values at runtime. Multi-tenancy is handled via authentication and input parameters, not separate manifests.

Will adding an MCP server card expose my internal APIs to unauthorized agents?

No. The server card only describes what endpoints exist and what inputs they accept—it's a discovery document, not an authentication bypass. You still enforce API keys, OAuth, or other auth in your actual endpoints. The /.well-known/mcp.json file is public metadata; security is enforced server-side when agents invoke the endpoint URLs.