--- title: How to publish an MCP server card at /.well-known/mcp.json description: Step-by-step guide to publishing a valid MCP server card per SEP-1649. Covers the required fields, transport options, authentication metadata, and validation against the Model Context Protocol spec. last_updated: 2026-05-11 canonical_url: https://agent-ready.dev/how-to-publish-an-mcp-server-card --- # How to publish an MCP server card at /.well-known/mcp.json > A step-by-step guide to serving a valid `/.well-known/mcp.json` per SEP-1649. Required fields, transport, and OAuth metadata. ## What is an MCP server card? An MCP server card is a JSON document published at `/.well-known/mcp.json` that advertises a Model Context Protocol server's transport, endpoint, capabilities, and authentication requirements. Clients like Claude Desktop, Cursor, and Cline fetch the card to auto-configure without users typing connection details by hand. The discovery spec is [SEP-1649](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/SEPs/SEP-1649.md), ratified 2025-11-25. See [our validator](https://agent-ready.dev/mcp-card-validator) for the full field-by-field requirements. ## Where should mcp.json live? Always at `/.well-known/mcp.json` on the domain serving your MCP endpoint. The [/.well-known/ path](https://datatracker.ietf.org/doc/html/rfc8615) is reserved by RFC 8615 for machine-readable discovery documents. If your server runs at `api.example.com/mcp`, the card belongs at `api.example.com/.well-known/mcp.json` — same origin as the server. ## Step-by-step ### Step 1 — Decide your transport and endpoint Pick the MCP transport that matches how clients will reach your server. streamable-http is the right choice for remote servers reachable over the public web. stdio is for local servers spawned by the client (Claude Desktop, Cursor). Pick the endpoint URL agents will connect to — typically https://api.yourdomain.com/mcp for HTTP transports. ### Step 2 — Create public/.well-known/mcp.json Inside your project, add a file at public/.well-known/mcp.json (Next.js) or wherever your static-file root maps to /.well-known/. The path /.well-known/ is reserved by RFC 8615 for machine-readable discovery documents; MCP clients look there by default. ### Step 3 — Add the required SEP-1649 fields The minimum valid card contains protocolVersion (currently 2025-11-25), serverInfo with name and version, transport with type and endpoint, capabilities (can be empty), and authentication.required (boolean). All other fields are optional. Validators reject cards missing any of these required fields. ### Step 4 — Declare your authentication model If your server requires auth, set authentication.required to true and publish OAuth Protected Resource metadata at /.well-known/oauth-protected-resource per RFC 9728 and SEP-985. For anonymous servers, set authentication.required to false; no companion file is needed. ### Step 5 — Verify with curl and validate Deploy your card. Run curl -I https://yoursite.com/.well-known/mcp.json to confirm it returns HTTP 200 with Content-Type: application/json. Then run the URL through agent-ready.dev/mcp-card-validator to confirm SEP-1649 compliance — protocolVersion, transport, capabilities, and authentication metadata all check out. ### Transport options MCP supports several transports. Pick one that matches how clients reach your server: - `streamable-http` — remote HTTP server (recommended for public servers). - `stdio` — local server spawned by the client (Claude Desktop, Cursor). - `websocket` — bidirectional streaming, less common. ### Minimal valid example ```json { "protocolVersion": "2025-11-25", "serverInfo": { "name": "acme-weather", "version": "1.0.0", "description": "Live weather data for AI agents" }, "transport": { "type": "streamable-http", "endpoint": "https://api.acme.dev/mcp" }, "capabilities": { "tools": true, "resources": false, "prompts": false }, "authentication": { "required": false } } ``` `capabilities` fields are booleans that advertise which MCP feature surfaces your server implements: `tools` (callable functions), `resources` (read-only data), `prompts` (prompt templates). ### Verify with curl ```bash curl -I https://api.acme.dev/.well-known/mcp.json # Expected response: # HTTP/2 200 # content-type: application/json ``` ## How do I generate mcp.json dynamically? When your server's capabilities or endpoint vary by environment, generate the card from code instead of shipping a static file. Use a Next.js route handler at `src/app/.well-known/mcp.json/route.ts`: ```typescript // src/app/.well-known/mcp.json/route.ts import { getServerInfo, getCapabilities } from "@/lib/mcp"; export async function GET() { const card = { protocolVersion: "2025-11-25", serverInfo: await getServerInfo(), transport: { type: "streamable-http", endpoint: process.env.MCP_ENDPOINT, }, capabilities: await getCapabilities(), authentication: { required: false }, }; return Response.json(card, { headers: { "Cache-Control": "public, max-age=3600", }, }); } ``` `Response.json()` sets the correct `application/json` Content-Type automatically. Add a sensible `Cache-Control` header so clients don't hammer the route on every connect. ## Common pitfalls when publishing mcp.json - **Card on a different origin than the server.** If your MCP endpoint is `api.example.com/mcp`, the card must be at `api.example.com/.well-known/mcp.json` — not on the apex domain. - **Missing OAuth metadata when auth is required.** If `authentication.required` is true but `/.well-known/oauth-protected-resource` returns 404, clients can't complete the handshake. - **Wrong Content-Type.** If your CDN serves the card as `text/plain` or `text/html`, clients may refuse to parse it. Confirm `application/json` in the response headers. - **Outdated protocolVersion.** Old drafts used different date strings. The current ratified value is `2025-11-25`. Update it when the spec version you support changes. - **Auth-gated paths under /.well-known/.** Some frameworks apply auth middleware to every route by default. Confirm `/.well-known/mcp.json` is publicly fetchable without credentials. ## Frequently asked questions ### Does my MCP server need a server card? Yes if you want auto-discovery. Without /.well-known/mcp.json, users have to type your server's URL and config by hand into their MCP client. With the card, clients like Claude Desktop or Cursor can fetch your domain, find the card, and offer a one-click install. It's the same dynamic as robots.txt — voluntary, but expected for production servers. ### What's the difference between mcp.json and server-card.json? Older drafts proposed /.well-known/mcp/server-card.json. SEP-1649 ratified the simpler /.well-known/mcp.json path. Some clients still try both — publish at /.well-known/mcp.json and you cover the canonical path; add a copy at /.well-known/mcp/server-card.json if you want belt-and-braces. ### Do I need to publish OAuth metadata too? Only if your server requires authentication. When authentication.required is true in your card, MCP clients also fetch /.well-known/oauth-protected-resource per RFC 9728. That document declares your authorization server, supported scopes, and token endpoints. Anonymous servers can skip it entirely. ### Where exactly should the file be served from? At /.well-known/mcp.json on the domain agents will use to reach your MCP server. If your server runs at api.example.com/mcp, publish the card at api.example.com/.well-known/mcp.json (not example.com/.well-known/mcp.json). The card and the server must share an origin. ### Can I version my MCP server card? Yes, but versioning is per-field, not per-document. protocolVersion declares which MCP spec version your server supports (currently 2025-11-25). serverInfo.version is your server's own version. Update either independently when the underlying thing changes — they don't have to move in lockstep. --- Read the full guide on the web: Validate your MCP server card: ## Sitemap See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.