API vs. MCP vs. an Agent Interface

An API exposes software capabilities. MCP standardizes how an AI client discovers and invokes context, tools, and interactive resources. An agent interface is the complete product boundary: the API and adapter plus identity, authority, approval, errors, recovery, evaluation, documentation, and operational evidence.

The terms overlap, but they are not substitutes.

The shortest useful distinction

| Layer | Question it answers | What it must own | | --- | --- | --- | | Domain API | What can the product do? | State, rules, identity, errors, idempotency | | MCP adapter | How can a compatible client discover and call it? | Protocol transport, tool catalog, resources, client-facing metadata | | Agent interface | Can an agent use it correctly and responsibly? | Task design, authority, confirmation, evaluation, UI, monitoring |

A polished MCP server cannot repair ambiguous product state. A strong API does not automatically give a model tools it can select correctly. The interface has to connect both layers to a specific user outcome.

Start from one outcome

The Permadyn operations lab begins with one observable result: an operator can find an exception, inspect its evidence and policy, preview a reversible change, and explicitly confirm that exact write.

That outcome becomes five tools:

search_cases -> get_case -> search_policy
                         |
              preview_case_update
                         | human confirmation
                apply_case_update

The tool set is intentionally small. Search, detail, policy, preview, and apply each have one job. The write is not hidden inside a general “manage case” operation.

What belongs below MCP

The domain layer remains responsible for facts no model or adapter should invent:

the current case version,
which identities have read and write scope,
whether a state transition is valid,
whether a confirmation matches the proposed change,
whether an idempotency key has already been used,
and what state actually changed.

This makes the same contract useful through direct HTTP, MCP, or a future platform adapter. The product does not depend on one model vendor’s conversation state.

What belongs in the adapter

The MCP surface describes each tool with versioned schemas, concise names, user-facing descriptions, and behavior annotations. It also publishes the confirmation interface as an MCP App resource.

Those details influence model behavior, but they are not an authorization system. A readOnlyHint helps a client reason about a tool; the server must still enforce scope. A “confirmation required” description helps the model explain the workflow; the apply endpoint must still reject a missing or replayed capability.

What makes it an interface

An agent interface is complete when the human, model, and product share a stable contract:

The user can tell what outcome is in scope.
The model can distinguish tools and provide valid arguments.
The server independently enforces identity and authority.
Consequential changes are previewed at a known version.
Failure is structured enough to recover safely.
Tests show when a release changes behavior or breaks compatibility.
Operators can connect a tool call to the resulting product state.

That is why “build an MCP server” can be either a small adapter task or a substantial product-engineering engagement. The answer depends on what already exists beneath and around it.

A practical scoping test

Ask for one golden workflow and trace it through all three layers.

If the API cannot express the outcome without database access or informal knowledge, begin with API repair. If the API is sound but the tools are broad or confusing, work on the agent contract. If both exist but authority, confirmation, and regression evidence are missing, the interface is still unfinished.

The right first release is usually narrower than the eventual ambition. A small surface makes failures legible and gives the team evidence for expanding authority.

Claim boundary

MCP compatibility does not establish that a product workflow is safe, useful, or supported in every client. Permadyn treats MCP as one delivery layer and makes compatibility claims only for tested clients, protocol versions, and workflows.