What /.well-known/ files AI agents actually look for

There is no argument about which of these files are real, because there is a registry. RFC 8615 reserved the /.well-known/ prefix in May 2019 and handed the list to IANA. On 15 August 2026 that list held 146 suffixes, 33 of them provisional. api-catalog is in it, permanent, from RFC 9727. security.txt is in it, permanent, from RFC 9116. So is agent-card.json, registered by the Linux Foundation on 1 August 2025 for the A2A protocol.

The MCP server card is not in it. It is two competing draft proposals with two different paths, and one of those paths is the one this site serves.

Key Takeaways

• The IANA well-known URI registry settles what is standard. Check it before you trust a blog post, including this one.
• api-catalog (RFC 9727, June 2025, Standards Track) and security.txt (RFC 9116, April 2022, Informational) are registered permanent entries.
• The MCP server card is a draft. SEP-1649 and SEP-2127 disagree about the path.
• llms.txt is deliberately not a well-known file, and the spec explains why.
• Our own site publishes an agent-skills index whose $schema URL does not resolve. Details at the end.

The registry is the whole answer

RFC 8615, Well-Known Uniform Resource Identifiers, Mark Nottingham, May 2019, Standards Track. It does one thing: it carves out /.well-known/ so site-wide metadata has a place to live that will not collide with a real page.

The rule that shapes everything downstream is about location: "Well-known URIs are rooted in the top of the path's hierarchy; they are not well-known by definition in other parts of the path. For example, '/.well-known/example' is a well-known URI, whereas '/foo/.well-known/example' is not."

Registration is open to anyone. You submit a name, a change controller, a document that specifies the format, and a status of permanent or provisional. That low bar is exactly why the registry is useful. Registering costs an email and a specification link, so a proposal that has not done it either is not finished or has nobody driving it.

api-catalog is the one that is finished

RFC 9727, "api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs", K. Smith of Vodafone, June 2025, Standards Track. It defines the well-known URI and a matching api-catalog link relation, and it is prescriptive about format: publishers MUST serve the catalog in Linkset format, media type application/linkset+json. Other formats are allowed through content negotiation, but that one is the floor.

Ours, live:

$ curl -s https://seobuilder.tech/.well-known/api-catalog
{"linkset":[{"anchor":"https://seobuilder.tech/api/mcp",
"service-doc":[{"href":"https://seobuilder.tech/auth.md",
  "title":"How an agent authenticates"}],
"service-desc":[{"href":"https://seobuilder.tech/.well-known/mcp/server-card.json",
  "title":"MCP server card","type":"application/json"}]}]}

One anchor, because we have one programmatic surface a customer is meant to call. Everything else under /api is this app's own browser client talking to itself, and every one of those routes expects a session cookie. Listing them would point agents at endpoints that can only answer 401.

That restraint is the actual work of an api-catalog. A catalog that enumerates every route you have is a directory of things that will fail. service-doc and service-desc come from RFC 8631 and mean what they say: documentation for humans, description for machines.

security.txt is real, and we do not have one

RFC 9116, April 2022, Informational (not Standards Track, which people routinely get wrong). It defines a plain text file at /.well-known/security.txt telling a researcher where to send a vulnerability report.

Two fields are mandatory. Contact is the obvious one. Expires is the one people forget: an RFC 3339 timestamp after which the file should be treated as stale. Requiring it is the smartest thing in the document. A file that declares its own expiry date cannot quietly rot for four years while the address inside it bounces.

Ours:

$ curl -s -o /dev/null -w "%{http_code}\n" https://seobuilder.tech/.well-known/security.txt
404

We publish an MCP server card, an API catalog and an agent skills index, and we do not tell anyone where to report a security bug. That is the wrong order of priorities, and it is going on the list this week. If you are building the agent-facing files before the security one, you have the same bug.

The MCP server card is a proposal, twice over

This is where precision matters, because the file is being described as a standard in places it should not be.

SEP-1649 was opened on 14 October 2025 and is labelled draft. It proposes /.well-known/mcp/server-card.json, holding server identity, transport, capabilities and authentication, so a client can learn what a server is before paying for a full initialization handshake.

SEP-2127, created 21 January 2026 by the protocol's own maintainers, covers the same ground and is also marked Draft. It puts the card at /.well-known/mcp-server-card, requires a $schema, and requires the server name in reverse-DNS form.

Two drafts, two paths, one of them from the maintainers. Neither is registered with IANA. If you implement one today you are picking a side in an unresolved discussion, and you should know that is what you are doing.

We picked SEP-1649, because it is the path clients were already probing when we shipped:

$ curl -s https://seobuilder.tech/.well-known/mcp/server-card.json | head -c 240
{"serverInfo":{"name":"seobuilder","title":"SEOBuilder","version":"1.0.0",
"description":"Read your own SEO and AI-visibility data: which questions AI
answers cite you for, where you rank, and what a site audit found.",
"websiteUrl":"https://seobuilder.tech"}

Compare that with agent-card.json, the A2A protocol's equivalent. Same idea, same shape of problem, and it has been a permanent registered entry since 1 August 2025. One ecosystem finished the paperwork and one has not, which tells you which of the two paths is safe to hard-code today.

What is not a well-known file, and why

llms.txt is the interesting omission, because the author considered /.well-known/ and rejected it in the v2 spec. The reason is the origin-root rule quoted above. Well-known URIs only exist at the top of a host, so a GitHub Pages project that owns a directory but not a domain could never publish one, and a file at the root cannot say "this describes /docs/ specifically". llms.txt is designed to sit at any path and cover what is beneath it, which is incompatible with the prefix by construction.

robots.txt and sitemap.xml are also outside the registry, for a duller reason: both predate RFC 8615 by many years and were never retrofitted. Their authority comes from elsewhere. Robots got an RFC of its own in 2022, RFC 9309, Standards Track. Sitemaps never did, and still run on the 2016 revision of a joint vendor agreement at sitemaps.org. Three files, three completely different kinds of authority, and none of them interchangeable.

A schema URL that does not resolve

One more from our own site, found while checking sources for this post. We serve an agent skills index at /.well-known/agent-skills/index.json, and it declares a schema:

$ curl -s https://seobuilder.tech/.well-known/agent-skills/index.json | head -c 70
{"$schema":"https://schemas.agentskills.io/discovery/0.2.0/schema.json"

$ curl -s -o /dev/null -w "%{http_code}\n" https://schemas.agentskills.io/discovery/0.2.0/schema.json
000
$ nslookup schemas.agentskills.io
** server can't find schemas.agentskills.io: NXDOMAIN

The host does not exist. Any client that tried to validate our file against the schema we told it to use would fail before reading a single field. The file itself is fine and no validator has complained, because no validator ran. The schema reference is decoration, and nothing in our build was ever going to tell us.

This is the same failure as the login redirect on our missing llms.txt, covered in what llms.txt is and who reads it. A machine-readable file is only as good as the last time somebody fetched every URL inside it with a script.

What to publish, in order

1. security.txt, with a Contact and an Expires you will renew. Cheapest and most useful of the four.
2. api-catalog, if you have an API a third party is meant to call. List only the endpoints they can actually reach. Follow the linkset format and send application/linkset+json.
3. An MCP server card, if you run an MCP server, knowing you are choosing between two drafts. Watch SEP-2127.
4. Nothing else until it is in the registry.

Then check the files instead of trusting them. Fetch every URL inside every descriptor with a script and fail your build when one breaks. Our HTTP header checker shows raw responses for spot checks, the structured data checker covers the on-page half, and the agent readiness check scores crawler rules, sitemap and descriptors together. For whether any of it shows up in an answer, SEOBuilder asks seven answer engines the same buyer questions and reports which of them cited you, starting with how to measure AI visibility.