What Is /.well-known/mcp.json? Model Context Protocol Domain Autodiscovery Guide
How websites and developer platforms publish machine-readable MCP server capabilities and structured JSON endpoints under RFC 8615 well-known URIs.
1. Overview: The Three-Layer Agentic Web Stack
RFC 8615 Well-Known URIModern AI-ready domains expose three complementary root discovery files, each solving a distinct layer of autonomous agent interaction:
- Layer 1 — Governance (
/robots.txt): Declares which AI search and training user-agents are permitted to crawl public routes. - Layer 2 — Unstructured Context (
/llms.txt&/llms-full.txt): Provides low-token Markdown documentation and canonical links for reading and RAG grounding. - Layer 3 — Structured Tool & API Execution (
/.well-known/mcp.json): Advertises deterministic JSON endpoints or remote Model Context Protocol (MCP) transports that agents can invoke directly instead of scraping HTML tables.
2. Live Production Example (sitecube.com)
3. HTTP Header, Security & Validation Checklist
Deployment Spec| Canonical Path | https://yourdomain.com/.well-known/mcp.json over TLS 1.2/1.3 (Port 443). |
| Content-Type | application/json; charset=utf-8 (must parse as valid UTF-8 JSON object, never HTML). |
| CORS Policy | Include Access-Control-Allow-Origin: * on public discovery manifests so browser-based agent sandboxes can inspect capabilities. |
| Auth & Rate Limiting | Keep unauthenticated endpoints strictly read-only, idempotent, and rate-limited; require OAuth 2.1 / Bearer tokens for any state-mutating MCP tool calls. |
| Cross-Reference | Include llms_txt and llms_full_txt fields inside mcp.json so agents discovering either endpoint locate your full documentation suite. |
Sitecube’s domain scanner automatically probes GET /.well-known/mcp.json alongside /llms.txt on every live host audit.