Agent-ready APIs: audit the contract before MCP rollout
By Greg Nowak. Updated 17 August 2026.
An internal API can work well for years while depending on knowledge that was never written down. Developers remember which fields are effectively mandatory. Operations teams know which actions are safe to retry. Someone on Slack can explain what an obscure error really means.
An AI agent has none of that institutional memory. Once an API becomes a set of MCP tools, its names, descriptions and schemas influence which tool the model selects, what arguments it supplies and what it does after receiving a result. Ambiguity stops being a documentation problem and becomes runtime behaviour.
That is why an MCP rollout should begin with a contract audit, not simply an adapter. The business question is whether an agent can understand the operation, stay inside the user’s authority and recover safely when reality differs from the happy path.
MCP does not repair a vague API contract
The current MCP Tools specification defines each tool through a name, human-readable description, input schema and optional output schema and annotations. Tools are model-controlled: a model may discover and invoke them based on the conversation. The specification therefore recommends keeping a person able to deny tool invocations and showing clearly when tools are exposed or called.
This makes wording operational. A generic tool such as update_record gives the model little help. update_crm_contact is better, but its description must still say what changes, which identifier is required, whether omitted fields remain unchanged and whether the action triggers another workflow.
OpenAPI 3.2.0 is a strong starting artifact because it describes HTTP APIs for both people and machines. It can expose missing types, unclear parameters, undocumented responses and inconsistent security definitions. However, a valid OpenAPI document only proves that the document follows a structure. It does not prove that a model can distinguish similar operations or understand their business consequences.
The latest MCP release changes the rollout checklist
MCP 2026-07-28 replaced the earlier HTTP handshake and protocol-level session with a stateless request model. Method and tool names now travel in HTTP headers, list results can be cached, and applications that need cross-call state should use explicit handles instead of hiding state in a transport session.
For teams that started building against a 2025 protocol revision, compatibility now belongs in the audit. Check the protocol versions supported by the server, client and SDK; identify code that assumes an Mcp-Session-Id; and decide how workflow state will be represented explicitly. Do not treat a successful connection as proof that every tool, authorization flow and retry path behaves correctly.
A practical six-part contract audit
| Audit area | Questions to answer | Release decision |
|---|---|---|
| Purpose | Can a model distinguish this tool from neighbouring tools? | Rename, rewrite or remove ambiguous operations. |
| Inputs | Are required fields, formats, enums, limits and defaults explicit? | Reject guess-dependent payloads. |
| Outputs | Is success structured consistently and covered by an output schema? | Validate before the next agent step. |
| Failure | Can the caller separate bad input, denied access, business rules and transient faults? | Define retry, stop and escalation behaviour. |
| Authority | Which user, tenant, scope and downstream system authorize the action? | Block calls without a complete identity chain. |
| Impact | Is the action read-only, reversible, destructive, financial or externally visible? | Add approval and logging in proportion to risk. |
Start with an endpoint inventory. Classify every candidate operation as read-only, write, externally visible, destructive, financial, identity-related or administrative. Expose the smallest coherent set first. A support pilot may need to find a customer and read an order, but it does not automatically need refund, deletion and account-administration tools.
For each selected operation, compare the real implementation with its OpenAPI description and MCP definition. Confirm required fields, nullable values, identifier formats, pagination, idempotency, timeouts, rate limits and response schemas. Use examples to clarify unusual fields, but never use an example as a substitute for a constraint.
Then test failure paths deliberately: missing properties, invalid enums, stale IDs, cross-tenant identifiers, expired credentials, insufficient scopes, rate limits, upstream timeouts, malformed results and partial completion. State whether a call may be retried safely. If a write might have succeeded before the connection failed, the agent needs a status check or idempotency mechanism—not another blind attempt.
Permission design is workflow design
For HTTP deployments, the current MCP authorization specification treats the MCP server as the protected resource. Tokens must be intended for that server, carried in the authorization header and validated for the correct audience. Passing the client’s token unchanged to a downstream API is explicitly prohibited because it weakens trust boundaries and auditability.
Map the complete chain before launch: resource owner, MCP client, MCP server, authorization server, tenant and downstream API. Give read and write operations separate scopes where the underlying system supports it. Request elevated access when it becomes necessary rather than granting every possible permission at sign-in. Sensitive actions should show the user the actual arguments before approval, not merely ask whether they trust “the agent.”
Pilot the boundary, not just the demo
A controlled pilot should run through the same integration layer, identity rules and observability you expect in production. Current agent SDKs can support tool filtering, per-tool approvals, model-visible failure handling and tracing, but those controls still require business decisions.
- Allow-list only the tools required by the pilot.
- Require approval for destructive, financial and externally visible actions.
- Record the acting user, tenant, tool, arguments, result and approval decision without leaking secrets.
- Set timeouts and retry rules per operation rather than globally.
- Review unsuccessful and corrected tool calls, not only completed tasks.
- Keep a fast way to disable an individual tool without taking down the whole integration.
The outcome of the audit should be a short release plan: which tools can launch, which contracts need repair, where approval is mandatory and which risks remain accepted. That gives owners and delivery teams something more useful than a technically successful MCP connection.
If you are deciding which internal APIs are ready—or need someone to coordinate the contract, security and operational work—talk to Greg about a focused agent-readiness review.
Related on GrN.dk
- A Voice Agent Is Only Ready When the Human Handoff Works
- OpenAI Presence Arrived—But Is Your Workflow Ready for an Agent?
- Copilot Has Repo-Level Metrics Now. What Should Teams Measure?
Need help with this kind of work?
Discuss an agent-readiness review Get in touch with Greg.