API-first with a real API: what the MCP layer taught us
An API is a promise before it is an endpoint
Most teams discover they are not API-first only after a human developer becomes the integration layer. One person reads the documentation, remembers the authentication sequence, fixes an inconsistent field, and teaches the next client where the sharp edges live. The endpoint exists, but the system does not know how to use it.
API-first reverses that dependency. The contract is designed before the interface. Inputs have stable types. Outputs distinguish a result from a failure. Names mean the same thing across clients. Capabilities can be discovered, composed, and replaced without relying on tribal memory.
That matters even more when the consumer is an agent. An agent can read a specification, but it cannot ask the original developer what a field probably means. It will use the contract exactly as written. The API is no longer a window into the product. It is the product’s executable boundary.
The machine consumer removes the human safety net
Human-oriented APIs often borrow context that the machine does not possess. A field may be documented as a string but returned as a number in one path. A retry is safe in one operation and duplicative in another. An error is clear to a developer who knows the system, but opaque to a client that sees only the response.
Documentation still matters, but documentation cannot repair an ambiguous contract. It is a map, not a boundary. The boundary must say what enters, what leaves, what may change, and what happens when the system says no.
This is the difference between a human-first interface and a machine-readable capability. A human can infer, pause, and ask. An autonomous caller must often choose among the states the contract permits. Ambiguity that feels charming in a README becomes a propagated error in an agent fleet.
MCP makes the capability layer explicit
The Model Context Protocol gives agents a common way to discover and use external capabilities. Its core vocabulary separates tools, which perform actions; resources, which expose information; and prompts, which provide reusable interaction patterns. Transports such as stdio and HTTP move structured messages between client and server.
The transport is useful, but the deeper lesson is architectural. A client can encounter a named capability, inspect its description, understand its arguments, invoke it, and receive a structured result without first learning one private integration for every system. Tool boundaries become part of a shared interface rather than a collection of bespoke adapters.
MCP therefore sharpens a familiar design rule: name the operation, declare the contract, and keep the implementation behind the boundary. A database query, publishing action, calendar lookup, or internal status check can have different mechanics while presenting the same discipline: bounded input, explicit output, and observable failure.
Describe capability, do not merely document it
A good API description lets a caller answer four questions without guessing: What action or information is available? What inputs are valid? What result proves completion? Which errors or constraints change the next move?
- Name the action precisely: “publish article” is not “process content.”
- Carry units, scope, and freshness where ambiguity changes a decision.
- Make optionality real rather than presenting always-required fields as optional.
- State what changes and what returns; the description is part of the interface.
The same discipline applies to an MCP tool. A generic label such as “manage content” is not a capability. A precise operation tells the agent when to use it, what it changes, and what comes back.
Failure belongs in the contract
Success paths make a demo look finished. Error paths decide whether the system is production-ready. A caller should be able to distinguish invalid input, denied action, unavailable dependency, temporary pressure, and completed work that produced an empty result.
That distinction allows an agent to recover intelligently. It can correct a malformed request, stop on a denied action, retry only a transient condition, or continue when an empty result is valid. “Request failed” collapses those decisions into one opaque event.
Idempotency belongs here too. When a call can create a post, send a message, reserve a resource, or move money, the contract should make repeated intent safe or explicitly unsafe. A stable operation identifier and a way to inspect prior completion turn retry from guesswork into continuity.
Design the contract before the convenience layer
API-first is not a ban on interfaces. A visual dashboard, a chat command, and an agent tool can all sit on the same capability boundary. The discipline is that each one consumes a stable contract instead of owning the underlying business rule privately.
That order prevents the interface from becoming the accidental architecture. When validation, permissions, state transitions, and error semantics live inside a screen or prompt, every new client must reproduce them. When they live in the capability layer, the client can focus on interaction while the system preserves one operational truth.
This is why the API is more than plumbing. It is the point where policy meets possibility. The interface renders that policy; it should not invent it.
Version for continuity, not ceremony
A published contract is a record. Once another system depends on it, changing the meaning of a field is not an implementation detail. It is history being rewritten without a migration.
Continuity requires versioning, deprecation paths, and observable change. A new capability can be added without forcing every client to understand it. A breaking change can carry a successor contract while old consumers finish their migration. Compatibility notes can travel with the contract instead of living in a private message.
The North Star treats records as the basis for continuity because untranscribed work does not exist for the next system. An API makes that idea operational. Its schema, examples, tests, changelog, and observed responses form a durable description of what the system can do.
Sovereignty lives at the boundary
A sovereign digital business should not lose its operating capability when one vendor, interface, or model changes. That does not require rejecting every remote dependency. It requires knowing where authority lives.
The capability contract should make dependencies inspectable, data portable, permissions narrow, and behavior replaceable. A compatible client should not be locked to one client. A record should not be trapped inside a presentation layer. A provider outage should reduce convenience, not erase the ability to understand or continue the work.
This is the body-center principle applied to software: the center coordinates, while capability nodes perform bounded work. No interface should become an accidental monopoly on the business. The API is the bridge that keeps authority inspectable and intention connected to action.
A practical API-first review
Before calling an API real, test it against the agent that must use it:
- Can a new client discover the capability without a private tutorial?
- Are names, types, units, optional fields, and outputs unambiguous?
- Can the client distinguish retryable, terminal, and policy failures?
- Are write operations safe under repeated intent?
- Does a version change have an owner, migration path, and verification?
- Are results observable and attributable to a specific request?
- Can authority and data be exported or replaced when the implementation changes?
A “no” does not always mean the product is broken. It means the interface is carrying more weight than it should. Fix the contract at the boundary instead of training every consumer to compensate.
The real test is autonomous use
An API-first system earns the label when another client can discover, evaluate, invoke, and recover from its capabilities without private human interpretation. The MCP layer made that standard visible. Information becomes infrastructure when it is typed, recorded, and transmissible. A real API is the geometry that turns intention into action; design it first, and the interface becomes a projection instead of a cage.
