‹ all guides

The /.well-known directory for agent discovery

Sources checked 2026-09-15

Well-known URLs give clients predictable places to look for specific metadata. Publish the documents your service actually supports and identify the convention behind each one.

The /.well-known directory is a standard place at the root of a site where clients look for machine-readable descriptions of what the site offers. Instead of crawling pages and guessing, a client fetches a predictable path and reads a manifest that points it to everything else. The idea comes from a long-standing web convention, and it now carries several files that matter to agents, each backed by a different level of standardisation.

PathPurposeStandard or convention
/.well-known/api-catalogLists a site's public APIs from one URLRFC 9727
/.well-known/oauth-authorization-serverDescribes how a client authenticatesOAuth discovery, RFC 8414
/.well-known/security.txtStates where to report a security problemRFC 9116
/.well-known/mcp/server-card.jsonDescribes an MCP server and how to reach itDeployed convention, not yet standardised
/.well-known/x402, /.well-known/mpp, /.well-known/ap2Payment and agent-payment manifests: how an agent is quoted and how it paysx402, MPP and AP2, deployed conventions

What each file establishes

An API catalog at a well-known path, defined by RFC 9727, lets a client enumerate a site's public APIs from a single URL. OAuth metadata describes how to authenticate, under its own long-established RFC. security.txt says where to report a problem, also under its own RFC. Each of these three has a fixed specification behind it, so a client that supports the standard can rely on the path staying put.

On this page

Where MCP discovery still moves

A server card describes an MCP server and how to reach it, but this one is not yet settled the way the three above are. Deployed cards, turva.dev's among them, sit at /.well-known/mcp/server-card.json. The experimental Server Card specification instead reserves the MCP endpoint URL followed by /server-card as its default, and expects a client to follow the URL a site's own catalog gives rather than assume a fixed well-known path. Treat the MCP card path as a deployed convention, not as a ratified standard on the same footing as RFC 9727 or OAuth discovery.

Why lookup beats crawling

The value of a well-known path is that discovery becomes a lookup rather than a search. A client that knows the convention can ask one predictable question and get a map, which is faster and more reliable than inferring structure from rendered HTML. A site that publishes a well-known surface is announcing its capabilities in a form clients already know how to parse.

What a missing directory means

A missing or thin well-known directory does not break a site for people, and it does not mean every client will abandon the site outright. It does mean a client that relies on lookup rather than crawling has to fall back to guessing or skip the site, so the practical effect depends on which clients the site cares about and how those clients behave when a lookup fails. turva.dev publishes an API catalog, a server card, OAuth metadata, payment manifests and a security contact under /.well-known.

Frequently asked

What is the /.well-known directory?

The /.well-known directory is a standard place at the root of a site where clients look for machine-readable descriptions of what the site offers. A client fetches a predictable path and reads a manifest that points it to everything else.

What files do agents look for under /.well-known?

An API catalog defined by RFC 9727, an MCP server card, OAuth metadata, payment and agent-payment manifests, and a security contact. The MCP card is the one whose home is still moving: deployed cards use /.well-known/mcp/server-card.json, while the experimental specification defaults to the MCP endpoint URL plus /server-card and does not recommend a well-known path for the card itself.

Why do clients use the well-known directory instead of crawling pages?

Because it turns discovery into a lookup rather than a search. A client fetches a predictable path and reads a manifest that points it to everything else, instead of inferring capabilities from navigation.

Sources