Skip to content
LLMSRank
Docs menu

Machine surface

Machine surface — endpoints, params, schemas, examples

Also called machine-readable API docs or MCP server documentation.

In short: Document your API in the file with its base URL and a link to its OpenAPI spec, and list your MCP server if you have one.

  • Category: Agent Readiness · weight 15 of 100 within the category
  • Agent Readiness is worth 30 in technical, 25 in generic and commerce, 20 in regulated (points of 100, by scoring profile)
  • Audit ID A5 (as shown on reports) · rubric v2.1

What it checks

Whether your API or MCP server is documented well enough for an agent to call it.

Why it matters

An agent that can call your API can answer with live data instead of stale pages. It needs the base URL, parameters, response shape and an example to do that. A documented machine surface is the part of generative engine optimization that prose cannot substitute for.

When it applies

Applies when the file mentions an API, OpenAPI spec, MCP server or WebMCP tools, detected from the wording above. With none, this audit and API error handling are Not applicable (the API block); Action endpoints has its own gate and can still apply through a booking or contact link. The API block is the most common Not applicable in the rubric.

An audit that doesn't apply, or that we couldn't verify, is removed from your score and its weight shared among the Agent Readiness audits that do apply. It is never scored as a zero.

How it's scored

1.0 when the file documents an API and an MCP or WebMCP surface · 0.75 an API alone · 0.6 MCP or WebMCP alone. An API is detected from wording such as “endpoint”, “OpenAPI”, “API reference”, GET / or POST /; MCP from “Model Context Protocol”, “MCP server” or an mcp. host; WebMCP from “WebMCP”, navigator.modelContext, document.modelContext or toolname=.

How to fix

  1. Give the base URL and link a machine-readable spec (OpenAPI, or your MCP server’s address).
  2. For the key endpoints, list parameters and the response fields that matter.
  3. Add one worked request and response per key endpoint.

Example

## API

- Base URL: https://api.acme.com/v1
- [OpenAPI spec](https://api.acme.com/openapi.json): Full machine-readable reference
- [MCP server](https://mcp.acme.com/sse): The same operations as tools for agents

Frequently asked questions

What counts as a machine surface for this audit?
A public API, an OpenAPI spec, an MCP server, or, from rubric v2.0, WebMCP tools that your pages register for in-browser agents. Today the scanner detects an API from wording such as “endpoint”, “OpenAPI”, “API reference”, GET / or POST /, and MCP or WebMCP from “Model Context Protocol”, “MCP server”, an mcp. host, “WebMCP”, document.modelContext or toolname=.

Sources: OpenAPI Specification (latest) · Model Context Protocol — What is MCP? · WebMCP — Draft Community Group Report · LLMSRank — Machine surface audit

How is the machine surface check scored?
Today a file that documents both an API and an MCP or WebMCP surface scores 1.0, an API alone 0.75, and MCP or WebMCP alone 0.6. The rubric’s full measure is the mean of six sub-checks (base URL, parameters, response schema, key-field notes, worked examples, a machine-readable spec link); where a judged review of the file exists, its score replaces the detection-based one.

Sources: LLMSRank — Machine surface audit · LLMSRank — How scoring works

My site has no public API. Am I penalized?
No. With no API, OpenAPI spec, MCP server or WebMCP tools, the API block (Machine surface and API error handling) is Not applicable, and its weight is redistributed across the other agent-readiness checks. Action endpoints has its own gate: it still applies if the file lists a booking, quote or contact link. The API block is the most common Not applicable in the rubric.

Sources: LLMSRank — How scoring works · LLMSRank — Machine surface audit

How do I describe WebMCP tools in llms.txt?
Say that the site exposes WebMCP tools, name them and the pages they live on, and what each does. WebMCP is a W3C Community Group draft in which a page registers tools with document.modelContext.registerTool(); a declarative form (<form toolname="…" tooldescription="…">) is described in its explainer but not yet in the draft itself. Our WebMCP and MCP starter kit has a harness and starter code for registering tools.

Sources: WebMCP — Draft Community Group Report · WebMCP — Declarative API explainer (toolname, tooldescription) · LLMSRank — WebMCP and MCP starter kit · LLMSRank — Machine surface audit

In our research, how many llms.txt files document a machine surface?
Just over half. In our 187-site corpus (captured 2026-10-10, scored with rubric v2.1) the check applied to 83 files and was Not applicable to 104; 46 of the 83 (55.4%) earned full marks by documenting both an API and an MCP surface, with a mean score of 0.869. Good examples include tavily.com, you.com, cloudflare.com, developers.deepl.com and attio.com.

Sources: LLMSRank — How scoring works · LLMSRank — Machine surface audit