/.well-known/ for agents: the 2026 reference

/.well-known/ was introduced by RFC 8615 as the standard place for discoverable metadata. In 2026 it has become the reception desk of the agentic web. If a piece of metadata is meant to be machine-readable and discoverable, it lives here.

This is the practical reference: which paths matter, which content types they need, and how to ship them.

The mental model

Agents and tooling fetch /.well-known/<thing> directly when they need a piece of metadata. No HTML parsing, no link traversal. The path is the contract.

The expectation: HTTP 200, the right content type, no redirects, no auth wall.

Core agent-readiness URIs

/.well-known/api-catalog (RFC 9727)

A single linkset+json document listing every public API the publisher exposes. The agent equivalent of a sitemap for APIs.

Content type: application/linkset+json

{
  "linkset": [
    {
      "anchor": "https://example.com/api/v1",
      "service-desc": [
        {
          "href": "https://example.com/api/v1/openapi.json",
          "type": "application/json"
        }
      ],
      "service-doc": [
        { "href": "https://example.com/docs/api/v1", "type": "text/html" }
      ]
    }
  ]
}

Build one with the API Catalog Builder.

/.well-known/agent-card.json (A2A)

A JSON document describing an agent so other agents can discover and call it. Used by the A2A (Agent-to-Agent) protocol.

Content type: application/json

Includes name, description, provider, capabilities (streaming, push notifications, state transitions), authentication scheme, and a list of skills.

Build one with the Agent Card Builder.

Authentication and security URIs

/.well-known/openid-configuration

The OpenID Connect discovery document. If your site has user accounts or APIs with OAuth, this should exist. Many AI agents and SDKs auto-discover OAuth flows from it.

Content type: application/json

/.well-known/oauth-authorization-server (RFC 8414)

OAuth 2.0 authorization server metadata. Sister to OpenID Connect but covers OAuth-only setups.

/.well-known/oauth-protected-resource (RFC 9728)

Newer in 2024-2025: lets an OAuth resource server advertise which authorization servers issue tokens for it. Increasingly important as MCP and A2A protocols mature.

/.well-known/security.txt (RFC 9116)

The original /.well-known/ resource that became famous. Contact info for security researchers.

Contact: mailto:security@example.com
Expires: 2027-01-01T00:00:00.000Z
Preferred-Languages: en
Canonical: https://example.com/.well-known/security.txt

Always include Expires and rotate it. Security teams ignore unexpiring security.txt files.

MCP and AI agent discovery

/mcp and /.well-known/mcp (proposed)

Model Context Protocol endpoints. As of mid-2026, MCP servers commonly live at /mcp directly, but /.well-known/mcp is increasingly proposed for discovery. Watch this space — the convention is in flux.

/.well-known/ai-plugin.json (legacy)

The old ChatGPT plugin manifest. Largely deprecated in 2026 as plugin support has shifted to MCP and custom GPT actions. Worth removing if you have one to avoid agent confusion.

Site-level descriptive resources

These are not strictly /.well-known/ paths but live alongside them in 2026 conventions.

/robots.txt

The original. Crawler policy. AI vendors increasingly read this for AI-specific user agents like GPTBot and ClaudeBot.

/llms.txt

Markdown index of important pages. Not standardized through IETF but adopted widely enough in 2026 to be effectively conventional.

Build one with the llms.txt Generator.

/sitemap.xml

XML sitemap for search engines. Reference it from robots.txt. Generate one with the sitemap.xml Generator.

Discovery via Link headers

Agents that do not know which /.well-known/ paths to try can read your homepage's Link response header instead. Send a multi-relation header that advertises every machine-readable resource:

Link: </.well-known/api-catalog>; rel="api-catalog",
      </.well-known/agent-card.json>; rel="https://a2a.dev/rel/agent-card",
      </llms.txt>; rel="describedby"; type="text/plain",
      </sitemap.xml>; rel="sitemap"; type="application/xml"

In Next.js 16, set this from proxy.ts. Build the header with the Link Headers Builder.

Content type matters

The most common bug across all of these URIs is the wrong content type. Agents reject documents whose declared MIME type does not match the spec. A few examples:

Set them explicitly in your route handlers. Do not rely on the framework guessing from extension.

How to ship a new well-known URI in Next.js

// app/.well-known/agent-card.json/route.ts
import { NextResponse } from "next/server";

const CARD = {
  /* your agent card object */
};

export async function GET() {
  return NextResponse.json(CARD, {
    headers: {
      "content-type": "application/json; charset=utf-8",
      "cache-control": "public, max-age=300",
    },
  });
}

The folder name preserves the dot — Next.js handles it correctly in the App Router.

What to ship this quarter

In priority order:

1. /robots.txt with explicit AI bot rules and a sitemap reference.
2. /sitemap.xml listing every canonical URL.
3. /llms.txt if your site has structured content worth indexing.
4. /.well-known/api-catalog if you publish APIs.
5. /.well-known/security.txt regardless of what else you ship.
6. /.well-known/agent-card.json if you build an agent.

Three of those take an hour each. Two are infrastructure already.

Why this matters

/.well-known/ is the universal addressing scheme for machine-readable metadata in 2026. Agents that respect it skip discovery entirely and start working. Sites that ignore it force agents to guess, fail, and skip them. The work to fix it is small. The decision is whether you want to be on the addressable web or not.