# MCP vs OpenAPI vs llms.txt: what agents need They are not competing formats. Each answers a different question in the agent discovery loop, and a good API publishes all three. By APIStead Published: 2026-11-10 Updated: 2026-11-10 Category: Discovery Tags: MCP, OpenAPI, llms.txt, agent discovery, API design MCP, OpenAPI and llms.txt are often compared as if one will replace the others. They solve different problems. An agent may use all three in the same task, and a provider that publishes only one is leaving a gap. The easiest way to see the difference is to ask what question each format answers. ## OpenAPI answers "what is the exact contract?" OpenAPI describes routes, methods, parameters, request bodies, response schemas and status codes. It is the format a developer uses to generate a client, and the format an agent uses when it needs to construct a call without a tool wrapper. It is precise and verbose. That is the point. A good OpenAPI document removes ambiguity about field names, types and errors. For a paid API, the document should also describe the payment challenge. If the route returns 402, say so. If the price is in the challenge rather than a static field, explain where to read it. Do not document a paid route as a free 200 response. ## MCP answers "what can I do right now?" MCP is a runtime tool surface. The model sees a list of tools with names, descriptions and input schemas. It chooses one and calls it. The server handles the transport. MCP is not a replacement for OpenAPI. It is a wrapper around a capability. The tool description has to be short enough for a model to compare with other tools, and specific enough that the model knows when to use it. A good MCP tool has: - A verb-led name. - A one-sentence description of the outcome. - An input schema with clear field descriptions. - A note on price and network, if the tool is paid. - A stable error shape. The common mistake is to expose every internal endpoint as a separate tool. That creates a list the model cannot scan. A smaller set of outcome-oriented tools is easier to use. ## llms.txt answers "what is this site and where do I start?" llms.txt is a plain-text map for a model doing research. It is not a tool protocol and it is not a schema. It is a concise explanation of the site, the important pages and the next action. A useful file includes the product summary, the discovery endpoints, the payment model, the catalogue summary and links to the machine-readable records. It should be short enough to read in one pass. llms.txt is also a good place to state the boundaries. If the catalogue is small, say so. If the data is preview-only, say so. If payments are on testnet, say so. A model that understands the limits is less likely to make a bad recommendation. ## Agent cards answer "who are you?" An agent card is a lightweight identity and capability document. It tells another agent who operates the service, what it does and where to find it. It is useful for discovery and for routing between agents. It is not a substitute for a listing page or a receipt. It is a handshake. ## How they fit together A typical agent task might look like this: 1. The agent reads llms.txt to understand the site. 2. It calls an MCP tool or an HTTP discovery endpoint to search the catalogue. 3. It reads the listing JSON or OpenAPI document to get the route and schema. 4. It calls the route unpaid and reads the 402 challenge. 5. It pays and retries. 6. It stores the receipt. Each format has a job. Removing one makes the loop slower or impossible. ## What to publish first If you are starting from nothing, publish in this order: 1. **OpenAPI** for the exact contract. 2. **llms.txt** for the site map and the next action. 3. **MCP** for the runtime tool surface. 4. **Agent card** for identity. 5. **Receipts** for evidence. OpenAPI first because it forces you to define the contract. llms.txt second because it is cheap and improves research. MCP third because it takes more design work. Receipts last only because they depend on a working paid route. ## The mistake to avoid The mistake is treating one format as a marketing checkbox. A generated OpenAPI file with empty examples, an MCP server with one vague tool and an llms.txt that is a copy of the homepage will not help an agent. The formats are only useful when they contain real information: real routes, real prices, real examples and real limits. That is the same principle as good documentation. The format changes. The need for clarity does not. ## What APIStead publishes APIStead publishes all of the surfaces above: an MCP server, an OpenAPI document, llms.txt, llms-full.txt, agent HTTP endpoints, per-listing JSON and Markdown, and a receipt index. The catalogue is small, and every verified route has a settlement. If you are building for agents, start with the contract. Then make it discoverable. Then prove it works.