Agent readiness¶
A docs site built by either docs target is readable and usable by AI agents without any setup: the build writes what an agent looks for into the site it publishes. A few things live outside the site (DNS records, zone rules, an OAuth server), and those are the owner's to add. This page says which is which. The yardstick is isitagentready.com, whose check names are used below, and a scan says where a host stands:
curl -s -X POST https://isitagentready.com/api/scan \
-H 'content-type: application/json' -d '{"url":"https://docs.example.com"}' | jq .checks
What every build writes¶
Three steps after mkdocs build, on github-pages and cloudflare-docs alike. None needs
credentials or network, each is on by default, and each leaves alone whatever the site already
publishes of its own.
| Check | What the build writes | Step (input) |
|---|---|---|
markdownNegotiation (half of it) |
every page's markdown at <page>/index.md, linked from the page |
page metadata (pages-seo) |
| llms.txt, llms-full.txt | /llms.txt and /llms-full.txt (cloudflare-docs only) |
the corpus (cloudflare-docs-index) |
agentSkills |
/.well-known/agent-skills/index.json and one SKILL.md |
agent readiness (pages-agent-ready) |
webMcp |
WebMCP tools on every page, from assets/javascripts/webmcp.js |
agent readiness (pages-agent-ready) |
authMd |
/auth.md, for a site at the root of its host |
agent readiness (pages-agent-ready) |
The skill¶
/.well-known/agent-skills/index.json follows the Agent Skills Discovery
RFC (v0.2.0) and lists one skill,
/.well-known/agent-skills/<name>/SKILL.md, which tells an agent:
- what the site covers:
site_descriptionand the top of the nav, a line per section with the pages in it; - how to read it:
llms.txt,llms-full.txt, the markdown copy of each page, asking a page URL forAccept: text/markdown, the MCP server when one is configured, and the WebMCP tools; - how to cite it: the page URL, never the markdown copy's.
Each of those is mentioned only when the build actually wrote it. github-pages writes no
llms.txt, and pages-seo: false writes no markdown copies, so the skill does not send an agent
to either.
The index carries the SHA-256 of the exact bytes written, which a client checks before it loads
the skill. The name is site_name lowercased and hyphenated (Caleb Sargeant's Docs becomes
caleb-sargeants-docs), and the skill's URL in the index is path-absolute at the address the
site is served from (/<repo>/.well-known/... behind a router). MkDocs leaves dot-directories
out of the build, which is why the step writes these into the built site rather than reading
them from docs/. On github-pages the Pages artifact then includes dot-directories, since
actions/upload-pages-artifact drops them otherwise and the index would never be published.
WebMCP¶
Every page loads one same-origin script, deferred, which registers four tools with the browser's model context (WebMCP):
| Tool | What it does |
|---|---|
search_docs |
searches MkDocs' own search index (or llms.txt without one), best match first |
read_page |
returns a page of the site as markdown, the open page by default |
list_pages |
lists every page with its title, URL and markdown URL |
open_page |
navigates the tab to another page of the site |
The script uses document.modelContext and navigator.modelContext, whichever the browser has,
and never defines either. It registers on load rather than on an event, because a scanner reads
the registrations a few seconds after navigation. It fetches nothing until a tool runs, and
nothing outside the site: every URL a tool is handed is checked against the site's root, which
the script finds from its own address, so it works at / and at /<repo>/ alike. A CSP of
script-src 'self' and connect-src 'self' admits all of it. In a browser without WebMCP it
does nothing at all.
auth.md¶
Written only when the site is served at the root of its host (site_url with a path of /),
because /auth.md speaks for the host, and never for a site behind Cloudflare Access
(cloudflare-docs-require-access), which nobody reads without signing in. A GitHub Pages site
with access control turns it off with auth_md: false. It says what is true of a public static
site: reading needs no account, there is nothing to register for, and no credential is sent.
When an MCP server is configured it names it and points at the server's own OAuth
protected-resource metadata (RFC 9728) as the authority on its access, rather than restating it.
That is what keeps it from contradicting a real one. A host that routes /auth.md to an MCP
Worker (see OAuth below) never serves this file at
that path, because the route answers first; the copy only surfaces if the route goes, and it is
true either way.
Configuration¶
Everything is optional, under extra.agents in mkdocs.yml. extra is a dict, so a shared
base can set it once through INHERIT:
extra:
agents:
mcp: https://mcp.example.com/ # named in the skill and in auth.md
skill: # or `false`: no skill
name: example-docs # default: site_name, lowercased and hyphenated
description: ... # default: from site_name and site_description
webmcp: true # false: no WebMCP script
auth_md: auto # auto: only at the root of a host; true; false
pages-agent-ready: false turns the whole step off, and the Pages artifact goes back to leaving
dot-directories out.
A site keeps what it already publishes: its own /.well-known/agent-skills/, whole; its own
webmcp.js at that path, with no page pointed at a second one; a page that already loads a
webmcp.js; and its own auth.md. The same rules make a second run change nothing.
What the docs router adds¶
On a host shared by path, like docs.magmamoose.com, a client only ever looks at the host's
root, and each site's files sit under /<repo>/. The router in workers/docs-router/ fills the
gap:
/.well-known/agent-skills/index.jsonlists a skill for the host itself, then every public site's skills, read from each site's own index over the service binding, re-addressed from the root and cached like thellms.txtsummaries. Sites inPRIVATE_SITESare never read.- WebMCP on the landing page:
list_docs_sites,search_docsacross every site'sllms.txt,read_pageandopen_site, from/webmcp.js, which the page's CSP admits as'self'. Only whileLANDING_REDIRECTis blank: once/redirects, a browser (a scanner's included) reads the tools of the page it lands on, which then needs its own. - Markdown negotiation: a page asked for with
Accept: text/markdownis answered with itsindex.md, falling back to the HTML page where a site has none. - CORS on every skills file, which the RFC asks for when browser-based clients read them.
A site behind the router gets no auth.md of its own: /auth.md on the host is the host's.
What only the owner can do¶
Markdown negotiation on a host of its own¶
The build writes the markdown; answering Accept: text/markdown with it happens before the
request reaches the site. The router does this for its host. A site on a host of its own needs
a URL rewrite Transform Rule on the zone (Rules → Transform Rules → URL Rewrite), which is
what docs.calebsargeant.com uses:
-
When incoming requests match:
(http.host eq "docs.example.com" and ends_with(http.request.uri.path, "/") and starts_with(http.request.headers["accept"][0], "text/markdown")) -
Path → Rewrite to → Dynamic:
concat(http.request.uri.path, "index.md")
The first media range has to be text/markdown, the rule the router follows too, so a browser
never gets markdown by accident. Unlike the router, a zone rule cannot fall back to the HTML
page, so every page needs its markdown copy, which the page metadata step writes for every page
the build emits. On cloudflare-docs add Vary: Accept and Content-Type: text/markdown;
charset=utf-8 in the site's _headers. GitHub Pages can neither rewrite nor set a header, so a
site there needs a proxy in front of it (a Cloudflare zone does), or does without.
DNS-AID records¶
The dnsAid check looks for DNS for AI
Discovery records: SVCB
records under the host's _agents name, signed with DNSSEC. A docs host whose MCP server lives
elsewhere publishes, for example:
_index._agents.docs.example.com. 3600 IN SVCB 1 docs.example.com. alpn="h2,h3" port=443
_mcp._agents.docs.example.com. 3600 IN SVCB 1 mcp.example.com. alpn="mcp" port=443 mandatory=alpn,port
_index is the draft's well-known entry point, pointing at the host that describes what is
there; the second names the MCP endpoint, with the agent protocol in alpn. The draft's own
parameters (cap, well-known and the rest) have no registered code points yet, so use numeric
keyNNNNN names for them until they do. The zone needs DNSSEC switched on, or a validating
resolver never returns the records as authenticated. The scanner's
dns-aid skill has the
checks it runs.
OAuth for an MCP server on the docs host¶
oauthDiscovery, oauthProtectedResource and a real authMd describe a server that issues
tokens, and a static site issues none. Serve them from the MCP server's own Worker, with Workers
routes on the zone for these paths of the docs host:
docs.example.com/mcp*
docs.example.com/auth.md
docs.example.com/oauth/*
docs.example.com/agent/*
docs.example.com/.well-known/oauth-authorization-server*
docs.example.com/.well-known/oauth-protected-resource*
docs.example.com/.well-known/openid-configuration
A route is more specific than the site's own docs.example.com/* route, and takes precedence
over a Custom Domain such as the router's, so these paths reach the MCP Worker and everything
else still reaches the docs. The site's own auth.md stays in the build, shadowed at /auth.md
by the route, which is why it says nothing about the server that could go stale.
Not covered¶
a2aAgentCard describes an agent that speaks the A2A protocol. A docs host runs none, so there
is no honest card to publish.