By Greg Nowak. Updated 17 September 2026.
An internal API can run successfully for years while depending on knowledge that never reached the documentation. Developers remember which fields are effectively mandatory. Operations teams know which errors permit a retry. Someone in the agency knows that changing a particular status also sends an email.
An AI agent has none of that institutional memory. When API operations become MCP tools, their names, descriptions and schemas influence what the model chooses, which arguments it supplies and how it responds to failure. Ambiguity is no longer just a documentation problem; it becomes runtime behaviour.
That is why an MCP rollout should begin with a contract audit, not an adapter. The practical question is not merely “Can we connect it?” It is “Can an agent use it predictably, within the user’s authority, when real-world inputs and failures appear?”
MCP cannot repair an ambiguous API
The current MCP Tools specification gives each tool a name, description, input schema and optional output schema and annotations. Models can discover and select those tools, so wording has operational consequences.
A tool called update_record leaves too much open to interpretation. update_crm_contact is more useful, but its contract should still explain which identifier is authoritative, whether omitted fields remain unchanged, which validations apply and whether the update starts another workflow.
OpenAPI 3.2.1, published on 10 September 2026, is a valuable audit input. It can reveal missing types, unclear parameters, undocumented responses and inconsistent security definitions. But a syntactically valid OpenAPI description does not prove that an operation is safe for agent use. Business consequences, retry rules and escalation paths also need to be explicit.
Choose the first tools by consequence, not convenience
Do not expose the entire API because generating wrappers is easy. Start with a small workflow and classify every operation it could require. A customer-service pilot may need to find an account and read an order; that does not automatically justify access to refunds, deletion or account administration.
| Operation type | Typical control | Release position |
|---|---|---|
| Read-only lookup | Tenant checks, result limits and logging | Good early candidate |
| Reversible internal change | Validation, audit trail and clear confirmation | Pilot with monitoring |
| Externally visible action | Preview exact arguments and require approval | Release only with tested oversight |
| Financial or destructive action | Strong authorization, idempotency and recovery procedure | Defer unless the workflow truly requires it |
| Administrative or cross-tenant action | Separate scopes and strict identity boundaries | Keep out of a general-purpose pilot |
Audit the contract from purpose to recovery
For every candidate tool, review five areas against the real implementation—not only the documentation.
- Purpose: Can a model distinguish the tool from neighbouring operations? State when it should and should not be used.
- Inputs: Define required properties, formats, enums, limits, defaults and nullable values. Examples help, but they do not replace constraints.
- Outputs: Return stable structured data and provide an output schema where possible. The MCP specification says clients should validate structured results when a schema exists.
- Failure: Separate invalid input, missing records, insufficient permission, business-rule rejection and transient upstream failure. Tell the caller what it may do next.
- Impact: Document side effects, downstream notifications, approval requirements and whether the operation is safely repeatable.
Then test the awkward cases deliberately: missing properties, invalid enums, stale IDs, another tenant’s identifier, expired credentials, insufficient scopes, rate limits, timeouts and malformed downstream responses. If a write might have completed before the connection failed, provide an idempotency key or a status-check operation. A blind retry is not a recovery strategy.
Authorization must follow the complete workflow
Map the acting user, MCP client, MCP server, tenant, authorization server and downstream API before launch. The current MCP authorization specification requires protected HTTP servers to validate that access tokens were issued for that server and intended for its audience. The accompanying security guidance treats unvalidated token passthrough to downstream APIs as an anti-pattern.
Where the underlying platform permits it, separate read and write scopes and request elevated access only when needed. Sensitive calls should show the user the actual operation and arguments before approval. Tool annotations can help a client present risk, but the MCP specification says clients must treat annotations as untrusted unless the server itself is trusted.
Check assumptions from earlier MCP versions
The 2026-07-28 MCP revision removed the earlier initialization handshake and protocol-level session for its stateless core. Requests carry their protocol information independently, and applications that need state across calls should return an explicit handle for later tools to accept.
If your integration began against a 2025 revision, include compatibility in the audit. Check the versions supported by the client, server and SDK; find code that assumes Mcp-Session-Id; and verify authorization on every request. A state handle identifies workflow state—it must not become a substitute for authenticating and authorizing the caller.
Treat the pilot as an operational release
A convincing demo proves that the happy path works. A useful pilot proves that the boundary holds when users, permissions and upstream systems behave unpredictably.
- Allow-list only the tools required for the chosen workflow.
- Require approval for destructive, financial and externally visible actions.
- Log the user, tenant, tool, arguments, result and approval decision without recording secrets.
- Set timeouts and retry rules per operation.
- Review failed, corrected and abandoned calls—not only completed tasks.
- Maintain a fast way to disable one tool without removing the entire integration.
The audit should end with a short release decision: which tools can launch, which contracts need repair, where human approval is mandatory and which operations remain excluded. That gives business owners and delivery teams a safer basis for investment than a technically successful connection.
If you need someone to coordinate the API, security and operational decisions across internal teams or suppliers, talk to Greg about a focused agent-readiness review.
Related on GrN.dk
- Web Browser Automation for Operations and Agency Teams: What to Automate and Which Tool to Use
- OpenAI Computer Use: Browser Agents Need Credentials, Not Demos
- OpenAI's Guardrails and Run State Make Internal Agent Rollouts a Paid Approval-and-Audit Job
Need help with this kind of work?
Discuss an agent-readiness review with Greg Get in touch with Greg.
