# Well-known URIs

RFC 8615 reserves the path prefix `/.well-known/` so that a protocol can define a fixed location on any site without colliding with the site's own URLs. Names are recorded in an IANA registry. On this site the prefix serves the A2A agent card, its legacy alias, and a description of the MCP endpoint.

- **Status:** Reference
- **Audience:** developer
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/protocols/well-known-uris/

## The problem the prefix solves

Some protocols need a document at a predictable place: a client that has only a domain name must be able to find something without prior arrangement. Before RFC 8615 each such protocol claimed its own path at the site root, which meant every new convention took a name that some website was already using, and site owners had a growing list of reserved-by-accident URLs to avoid.

The fix is one reserved prefix. Everything of this kind lives under `/.well-known/`, names inside it are recorded in an IANA registry so two protocols cannot claim the same one, and a site owner has exactly one path segment to keep clear.

Two well-known conventions predate the RFC and stayed where they were: `/robots.txt` and `/sitemap.xml` sit at the root, not under the prefix. Looking for `/.well-known/robots.txt` is a common and fruitless mistake.

## Properties a well-known document should have

- **Fetchable without credentials.** The point is discovery by someone who has nothing but the domain. A document behind a login is not discoverable.
- **Correct content type.** A JSON document served as `text/html` is technically present and practically invisible to the client looking for it.
- **Cross-origin readable when browsers will fetch it.** A card another agent reads from a page needs permissive CORS, or the browser refuses it.
- **Cheap and cached.** These are probed by strangers. A short cache directive costs nothing and prevents a well-known path becoming a load source.
- **Never a place for secrets.** Anything here is public by construction, whatever the surrounding documentation implies.

> **Note** `404` is a legitimate and useful answer. A domain that does not speak a protocol should say so quickly rather than returning a soft error page with status `200`, which leaves a probing client parsing HTML to work out that there was nothing there.

## Does Connect use well-known URIs?

Yes, for three documents, and the list is short on purpose.

| Path | What it is | Notes |
|---|---|---|
| `/.well-known/agent-card.json` | The A2A Agent Card | Generated from the documentation registry; cached five minutes; `Access-Control-Allow-Origin: *` |
| `/.well-known/agent.json` | The same card, at the earlier A2A draft path | Carries a `Link` header naming the current path as canonical |
| `/.well-known/mcp.json` | A short description of the MCP endpoint | Name, endpoint, transport, protocol version, supported versions, tool names, documentation URL |

The agent card has a deliberate fallback: if the generated file is missing, the route builds a minimal card in process rather than returning `404` on a path other agents probe — and that fallback says it is one, with an empty skill list, so nobody is told about skills that are not being served.

Connect publishes no `security.txt` and no other well-known document. Crawler policy is at `/robots.txt` and the page index at `/sitemap.xml`, both at the site root where those conventions live.

## Probing a domain sensibly

1. Request the exact path the protocol specifies, over HTTPS.
   - Result: You get the document, or a status that means something. Trust in anything found this way comes from the certificate, so plain HTTP proves nothing.
2. Check the content type before parsing.
   - Result: A `text/html` body on a JSON path is almost always a catch-all error page, not a document.
3. Treat `404` as a final answer for that protocol on that domain.
   - Result: No retry loop, no fallback guessing at similar names. The one exception worth coding is A2A's older `agent.json` path.
4. Respect the cache directive you were given.
   - Result: Re-fetch when something stops working, not on every request. Well-known documents are static files and change on release.

## Questions

### Why is robots.txt not under /.well-known/?

Because it predates the prefix by decades and moving it would break every crawler ever written. RFC 8615 reserved the prefix for future conventions; it did not relocate the existing ones. `robots.txt` and `sitemap.xml` remain at the site root.

### Can I put my own file under /.well-known/?

You can serve whatever you like, but names there are meant to be registered with IANA so that two protocols do not collide. An unregistered private name works and is a small landmine for whoever adopts that name later.

### Does a well-known document prove anything about the site?

Only that the domain served it, which is exactly what the TLS certificate attests. It does not prove the described service works — for that, send one small real request, as [A2A agent discovery](/docs/protocols/a2a-discovery/) sets out.

## Related

- [The A2A Agent Card](https://connectbyjbrh.com/docs/protocols/agent-card/)
- [A2A agent discovery](https://connectbyjbrh.com/docs/protocols/a2a-discovery/)
- [RFC 9309 — the Robots Exclusion Protocol](https://connectbyjbrh.com/docs/protocols/rfc-9309/)
- [The machine-readable documentation](https://connectbyjbrh.com/developers/machine-manifests/)
- [Model Context Protocol](https://connectbyjbrh.com/docs/protocols/mcp/)

## What this page is based on

- https://www.rfc-editor.org/rfc/rfc8615
- `backend/app/a2a_server.py` — the agent-card and legacy agent.json routes
- `backend/app/mcp_server.py` — the /.well-known/mcp.json route
- `webapp/.well-known/` — the generated card on disk