The /.well-known directory for AI agents in 2026: what to publish and why

AI agents do not browse your site the way a human does. Before rendering a page, most of them poke at a small set of well-known URLs to figure out what kind of site they are dealing with. If those URLs return the right shape, the site gets treated as first-class. If they 404, the agent falls back to guessing from HTML, and that is where citations dry up.

The /.well-known/ directory (defined in RFC 8615) is the agreed-on place for these machine-facing metadata files. Here is the short list that actually matters for AI-agent readiness in 2026, and what to put in each.

Why /.well-known/ at all

/.well-known/ is a reserved path prefix. IANA maintains a registry of suffixes so that different protocols do not fight for the same top-level filename. It has been used for a decade for OIDC discovery, ACME challenges, and Apple app-site associations. AI protocols are latching on for the same reason: a single predictable location saves crawlers a scan.

Not every AI signal lives under /.well-known/. /llms.txt and /robots.txt sit at the root by convention. But every emerging agent-to-service protocol in 2026 is planting flags in this directory, so a site that ignores it is invisible to the newer wave of clients.

The files that actually matter in 2026

1. /.well-known/security.txt (RFC 9116) — publish this today

The oldest and most settled of the group. A plain-text file that tells security researchers and, increasingly, AI security agents where to report vulnerabilities. Minimal template:

Contact: mailto:[email protected]
Expires: 2027-01-01T00:00:00Z
Preferred-Languages: en
Canonical: https://yourbrand.com/.well-known/security.txt

Set the Expires to roughly a year out and update on your yearly review. Agents that scan for supply-chain contacts (and there are more of them every quarter) will find your team without a Google search.

2. /.well-known/openapi.json (or openapi.yaml) — publish if you have an API

Strictly speaking, OpenAPI does not require /.well-known/ placement, but tools like ChatGPT actions, LangChain toolkits, and MCP importers look here first when a site advertises an API. If your product has a public REST surface, ship a machine-readable OpenAPI 3.1 document under this path. Even a partial spec is better than none. Point to it from your homepage HTML with:

<link rel="describedby" type="application/vnd.oai.openapi+json"
      href="https://yourbrand.com/.well-known/openapi.json">

Agents that respect content negotiation will follow the link and self-configure. Everyone else still gets a working site.

3. /.well-known/ai-plugin.json — mostly historical, keep only if a client asks

This is the file the original OpenAI plugin store required in 2023-2024. That store is closed, and most modern agent runtimes have moved on to MCP-style transports. If you already ship one, no need to remove it (it costs nothing to serve), but do not spend time building one from scratch. If a specific partner still consumes it, keep it in sync with your OpenAPI file to avoid drift.

4. /.well-known/agent-card.json (A2A) — publish if you run an agent service

The Agent-to-Agent (A2A) protocol, championed by Google in 2024-2025, uses an "agent card" to advertise what an agent does, what skills it exposes, and how to invoke it. The convention that shipped with most reference implementations puts the card at /.well-known/agent-card.json (some early drafts used agent.json; both are seen in the wild).

Publish this only if your site is an agent (an API another agent can call), not a plain content site. Minimum keys most consumers expect:

{
  "name": "YourAgent",
  "description": "One-line pitch of what the agent does.",
  "url": "https://api.yourbrand.com",
  "version": "1.0.0",
  "skills": [
    {
      "id": "summarize-doc",
      "description": "Given a document URL, return a 200-word summary."
    }
  ],
  "authentication": { "schemes": ["bearer"] }
}

Expect the exact schema to shift over 2026 as the spec settles. Watch the A2A GitHub repo and revalidate the card twice a year.

5. /.well-known/mcp.json (or an equivalent discovery hint) — emerging

Model Context Protocol (MCP), the Anthropic-driven standard, does not yet mandate a discovery file at a fixed path. But agent runtimes have started probing /.well-known/mcp.json as a courtesy hint pointing to an MCP server endpoint. If you run an MCP server that clients should be able to auto-discover from a marketing site, publish a small pointer:

{
  "servers": [
    {
      "name": "yourbrand-mcp",
      "transport": "http",
      "url": "https://mcp.yourbrand.com",
      "description": "Read-only access to public knowledge base."
    }
  ]
}

Treat this as a convention, not a guarantee. Do not delete or rename it once shipped; MCP clients cache these paths aggressively.

What NOT to put in /.well-known/

• llms.txt. Convention is root, not /.well-known/. See our WordPress guide for the correct placement.
• robots.txt. Also root, never /.well-known/.
• Sitemaps. Root, linked from robots.txt.
• Anything with secrets. Everything under /.well-known/ is world-readable by design. No tokens, no internal URLs.

How to verify agents can read the files

1. curl -I https://yourbrand.com/.well-known/security.txt — expect 200, Content-Type: text/plain.
2. curl https://yourbrand.com/.well-known/openapi.json | jq .info.title — expect your product name back.
3. Ask a real agent: "What API endpoints does yourbrand.com expose?" A grounded answer means the OpenAPI file landed.
4. Run a full scan on agentfix.pro. The report checks all five paths above alongside 28 other signals and ships back the missing files, filled in.

The one rule that outlives every spec

Return the correct Content-Type. Half the agent-readiness failures we see are files that exist but come back as text/html because a router upstream wrapped them in a page shell. If a JSON file returns HTML, no agent will parse it. Test with curl -I, not a browser tab.

Related: the full 33-signal GEO checklist, JSON-LD templates for AI search, and robots.txt for GPTBot, ClaudeBot, PerplexityBot.