API-first with a real API: what the MCP layer taught us
Every team says they are API-first. Most of them are lying. They have an API — a REST endpoint that returns JSON, a Swagger doc that nobody reads, a Postman collection that was current three months ago. Having an API is not the same as being API-first. API-first means the API is the product, not a side effect. It means the API was designed before the UI, tested before the frontend was built, and documented in a way that a machine could consume it without a human interpreting the docs. The Model Context Protocol taught us what that actually means — because when your consumer is an agent, not a human, the API has to work on its own terms.
The problem with human-first APIs
Most APIs are designed for humans who will read documentation, write client code, and handle edge cases manually. A developer reads the OpenAPI spec, understands the intent behind each endpoint, writes a wrapper, handles errors, and moves on. The human is the integration layer. The API can be sloppy because the human compensates.
When the consumer is an AI agent, that compensation disappears. The agent does not read your blog post about the authentication flow. It does not guess that the `status` field might be a string in some responses and an integer in others. It does not know that the rate limit is documented in a README but enforced differently in production. The agent calls the endpoint, parses the response, and either the data is what it expected or the task fails.
This is the constraint that makes API-first design real. Not a methodology. Not a buzzword. A survival requirement. If the API is not self-describing, self-validating, and consistent, the agent cannot use it. And if the agent cannot use it, the system it powers does not work.
What MCP actually is
The Model Context Protocol is a standard for connecting AI agents to tools, data sources, and services. It defines three core primitives: tools (functions an agent can call), resources (data an agent can read), and prompts (reusable templates for common interactions). The transport is JSON-RPC over standard HTTP or stdio. The protocol is open, versioned, and designed to be implemented by anyone.
What MCP gets right is not the protocol itself — JSON-RPC is decades old. What MCP gets right is the design philosophy. Every tool declaration includes a name, a description, a parameter schema, and return type hints. Every resource has a URI, a MIME type, and metadata. Every prompt has arguments with descriptions and defaults. The protocol forces you to describe your API in terms a machine can reason about.
This is what API-first means when the consumer is an agent. Not a Swagger doc that a human might read. Not a README with curl examples. A structured, machine-readable declaration of capability that the agent can discover, evaluate, and invoke without human guidance.
The lesson: describe, don’t document
The biggest shift MCP taught us is the difference between documentation and description. Documentation is for humans — prose, examples, tutorials, and guides. Description is for machines — schemas, types, and contracts that can be validated programmatically.
A well-documented API tells you how to use it. A well-described API tells the agent what it can do, what it expects, and what it returns — all in a format the agent can parse without interpretation. MCP enforces this. Every tool declaration is a JSON Schema. Every resource is a typed URI. The agent does not need to read anything. It reads the schema and knows.
This changes how you design. When the consumer is a human, you can be vague about edge cases because the human will ask questions or read the error message and adjust. When the consumer is an agent, every ambiguity is a failure point. If the `amount` field can be a string or a number, the agent needs to know. If the `status` field has three possible values, the agent needs an enum. If the API returns different shapes depending on the input, the agent needs conditional schemas.
The protocol forces clarity. Not because it is rigid, but because ambiguity that a human tolerates is an error that an agent propagates.
Continuity, not completion
The north star says everything is a record and continuity beats completion. An API is a record — it encodes the capabilities of a system in a structured format. But an API that is completed once and never updated is a record that stops being accurate. MCP’s versioned protocol and extensible schema system make the API a living record. New tools can be added. Old ones can be deprecated with migration paths. Resources can evolve without breaking existing consumers.
This is what API-first means at the infrastructure level. The API is not a document you write once. It is a surface that evolves with the system it describes. Every new capability is a new tool declaration. Every changed behavior is a schema update. The API and the system stay in sync because the API is the system’s self-description, not an afterthought.
The fleet trusts its tools. That trust depends on the API being accurate — not when it was written, but when it is used. Continuity is what keeps the description honest.
The sovereign API
There is a sovereignty argument buried in all of this. An API that is designed for agents is an API that can be consumed without human intermediation. An API that is self-describing is an API that does not depend on a human developer to integrate it. An API that is versioned and extensible is an API that can evolve without breaking the systems that depend on it.
This is the sovereign stack at the API layer. Local-first tools, persistent resources, structured prompts — all described in machine-readable schemas that any compatible agent can discover and invoke. The agent does not need permission to use the API. It does not need a human to interpret the docs. It reads the schema, validates the contract, and calls the tool. The API is the bridge between intention and action, and it works because it was designed to work without a human in the loop.
The MCP layer taught us that API-first is not a design methodology. It is a requirement. When the consumer is an agent, the API has to be real — self-describing, self-validating, and continuous. Everything else is documentation that a human reads and an agent ignores.
