/.well-known/* capability discovery

What is the /.well-known/* capability discovery standard?

/.well-known/ is a reserved URL namespace defined by RFC 8615 for publishing site-wide metadata at predictable locations. Instead of forcing clients—human or automated—to hunt through your homepage, documentation, or HTML meta tags, you place machine-readable files at paths like /.well-known/openid-configuration or /.well-known/mcp.json. The spec reserves this prefix so any service can publish discovery endpoints without namespace collisions.

For AI agents, this matters because they can probe a known set of paths to learn what your site offers: OAuth/OIDC configuration, OpenAPI catalogs, AI-specific metadata like MCP (Model Context Protocol) servers, agent skill manifests, or even ai.txt. RFC 8615 doesn't mandate which files live there—it just reserves the namespace—but a few endpoints have become de facto standards. If an agent finds /.well-known/oauth-authorization-server, it knows how to authenticate. If it finds /.well-known/api-catalog, it knows where your APIs live. Zero guesswork.

Why does /.well-known/* matter for AI agent integration?

When ChatGPT, Claude, or a custom agent visits your site, it can either scrape your homepage (slow, fragile, often blocked by WAFs) or check a handful of .well-known paths in parallel. The latter is deterministic, cacheable, and plays nicely with CDNs. An agent that discovers /.well-known/openid-configuration can immediately initiate OAuth; one that finds /.well-known/mcp.json can connect to your MCP server and expose your tools to the LLM. This cuts the "time to first API call" from minutes (or never) to seconds.

Concretely: if you run a SaaS product and an agent can auto-discover your authentication flow and API schema, you're orders of magnitude more likely to appear in ChatGPT or Claude responses that involve "do X with service Y." You're also less likely to trigger false positives in security tools—structured discovery traffic looks nothing like a scraper hammering your homepage. Even two or three well-known endpoints can vault you ahead of competitors who force agents to reverse-engineer their docs.

Is implementing /.well-known/* endpoints required for AI agents?

This check is recommended for most sites because even minimal .well-known coverage—say, OAuth discovery if you offer login, or ai.txt if you publish content—delivers measurable agent ergonomics with near-zero implementation cost. It becomes required if you want agents to authenticate, call your APIs, or integrate your tools autonomously. It's optional only if your site is purely static content with no user accounts, no APIs, and no desire to be cited or actioned by agents. If you have a developer platform, a content library agents should cite, or any workflow you'd like agents to automate, you want at least one or two well-known endpoints live.

What RFC 8615 and the /.well-known/* standard specify

RFC 8615 itself is brief:

• Path prefix: /.well-known/ is reserved; the IANA maintains a registry of suffixes.
• Server behavior: Respond with appropriate media types (typically application/json, text/plain, or application/xml). Return 404 if the specific file doesn't exist; don't redirect away from .well-known to maintain predictability.
• Client behavior: Clients SHOULD try HTTPS first; MAY fall back to HTTP for legacy.

For AI agents, the relevant suffixes are not yet fully standardized but widely recognized:

• /.well-known/openid-configuration (OAuth/OIDC discovery, OpenID spec)
• /.well-known/oauth-authorization-server (OAuth 2.0 metadata, RFC 8414)
• /.well-known/mcp.json (Model Context Protocol, proposed by Anthropic)
• /.well-known/agents.json or /.well-known/skills.json (emerging agent skill manifests)
• /.well-known/api-catalog (API discovery, proposed in API catalog initiatives)
• /.well-known/ai.txt (AI-specific metadata and terms, informal spec)

Minimum valid example (OAuth/OIDC):

{
  "issuer": "https://example.com",
  "authorization_endpoint": "https://example.com/oauth/authorize",
  "token_endpoint": "https://example.com/oauth/token",
  "jwks_uri": "https://example.com/oauth/jwks"
}

What good /.well-known/* implementation looks like in production

Companies with mature developer platforms typically publish OAuth discovery. For instance, identity providers and SaaS platforms often expose /.well-known/openid-configuration with full OIDC metadata—issuer, endpoints, supported scopes, signing keys. While I can't paste live examples without real-time verification, organizations like Auth0, Okta, and Google Workspace are known to publish comprehensive OIDC discovery documents.

For AI-specific endpoints, early adopters are publishing /.well-known/ai.txt with licensing and usage terms, or /.well-known/mcp.json pointing to MCP server URLs. As of early 2025, these are emerging patterns rather than ubiquitous; check the MCP specification and community examples for current templates.

How do I add /.well-known/* endpoints to my site?

1. Identify which capabilities you want to advertise. Do you offer OAuth? Publish openid-configuration or oauth-authorization-server. Do you expose APIs? Consider api-catalog or an OpenAPI link. Do you run an MCP server? Add mcp.json.

2. Create static JSON (or plain text) files in your public directory at /.well-known/<suffix>. Most frameworks let you drop files into a public/ or static/ folder that gets served as-is.

   Next.js: Place files in public/.well-known/openid-configuration.json. Next serves public/ at the root.

   Cloudflare Workers: Use fetch event handler to intercept /.well-known/* requests and return JSON responses from KV or hardcoded strings.

   // Cloudflare Worker example
   addEventListener('fetch', event => {
     event.respondWith(handleRequest(event.request));
   });
   
   async function handleRequest(request) {
     const url = new URL(request.url);
     if (url.pathname === '/.well-known/mcp.json') {
       return new Response(JSON.stringify({
         "mcp_server": "https://mcp.example.com"
       }), {
         headers: { 'Content-Type': 'application/json' }
       });
     }
     return fetch(request);
   }
   

3. Set correct MIME types. JSON should be application/json, plain text text/plain. Most static servers do this automatically for .json extensions.

4. Test each endpoint with curl (see below) and confirm 200 responses, correct content, and no redirects away from .well-known.

5. Add a Cache-Control header if the data changes infrequently—agents will cache discovery documents aggressively.

How can I test my /.well-known/* endpoints for AI agent readiness?

curl -i https://yoursite.com/.well-known/openid-configuration

Look for 200 OK, Content-Type: application/json, and valid JSON in the body. Repeat for each well-known endpoint you publish.

Or just run a free scan and we'll check this for you alongside 30+ other agent-readiness signals.

Frequently asked questions

Do I need /.well-known/* files if I already have a public API documented elsewhere?

Yes. Agents discover APIs by probing /.well-known/* paths, not by scraping documentation. Without /.well-known/openid-configuration or /.well-known/api-catalog, agents must reverse-engineer your auth flow and endpoints from HTML or PDFs—slow, error-prone, and often blocked by WAFs. Publishing discovery files makes your API instantly machine-readable.

What's the difference between /.well-known/openid-configuration and /.well-known/oauth-authorization-server?

Both expose OAuth metadata, but openid-configuration is for OpenID Connect (OIDC)—OAuth plus identity layer—while oauth-authorization-server (RFC 8414) is pure OAuth 2.0 without user-info endpoints. If you support OIDC, publish openid-configuration. If only OAuth 2.0, use oauth-authorization-server. Many providers publish both for maximum compatibility.

Can I use /.well-known/* on a WordPress or Shopify site?

Yes, but methods vary. WordPress: use a plugin like "Custom Permalinks" or create a must-use plugin that intercepts requests to /.well-known/* and returns JSON. Shopify: use the Liquid {% layout none %} template to serve static files at those paths, or proxy via Cloudflare Workers to inject discovery endpoints without touching Shopify's file system.

Does every SaaS product need /.well-known/mcp.json for AI agents?

Only if you run a Model Context Protocol server. /.well-known/mcp.json tells agents where your MCP server lives so they can fetch tools and prompts. If you offer OAuth APIs but no MCP server, publish openid-configuration instead. MCP is optional; OAuth/OIDC discovery is near-universal for authenticated SaaS.

Will adding /.well-known/* files improve my site's SEO ranking?

Not directly. /.well-known/* endpoints are machine-readable metadata for agents and clients, not indexed content for traditional search engines. However, they improve Answer Engine Optimization (AEO): agents that can authenticate and call your APIs are far more likely to cite or integrate your service in ChatGPT, Claude, or Perplexity responses.

How do e-commerce platforms benefit from /.well-known/* discovery?

E-commerce sites can publish /.well-known/openid-configuration for headless commerce integrations, or /.well-known/api-catalog linking to product/order APIs. Agents building shopping workflows ("find and buy X") can auto-discover your catalog and checkout endpoints, reducing integration friction. For Shopify or BigCommerce, this means agents can programmatically browse and transact.

Can I return a 301 redirect from /.well-known/* to another domain?

RFC 8615 discourages redirects away from the /.well-known namespace—clients expect deterministic paths. If you must redirect (e.g., multi-domain setup), use 307 (temporary) and keep the redirect within /.well-known on the target domain. Agents may not follow 301s, treating them as "not found" instead.

Do B2B developer portals need different /.well-known/* files than consumer sites?

Yes. B2B portals should prioritize /.well-known/openid-configuration (for partner OAuth), /.well-known/api-catalog (for API discovery), and optionally /.well-known/mcp.json if you expose tools. Consumer sites benefit more from /.well-known/ai.txt (content licensing) and lighter auth discovery. Tailor endpoints to your agent use cases.