By Greg Nowak. Updated 8 November 2026.
Before you let an AI agent update your CRM, handle orders or trigger client workflows, check what your API actually promises. A connection can work perfectly while leaving the agent guessing about permissions, side effects and what to do after a timeout.
Internal APIs often rely on unwritten knowledge: which identifier to use, which fields must travel together, or which status change sends a customer an email. Turning those operations into Model Context Protocol (MCP) tools makes that missing detail an operational problem.
An API contract audit gives owners, operations leads and agency teams a concrete release decision: which actions are ready, which need repair and who takes responsibility when something goes wrong.
Start with one business workflow
Choose a bounded task, such as finding an order and preparing a support response. List the information and actions it requires. Access to refunds, deletion or account administration should each have a separate business justification.
Use the following matrix as a starting point. Even read-only access needs scrutiny: searching one customer record and exporting an entire client database have different consequences.
| Action | Controls to establish | Pilot decision |
|---|---|---|
| Read a specific record | User and tenant checks, limited fields, result limits | Good first candidate |
| Make a reversible internal change | Validation, audit history, tested reversal | Release with monitoring |
| Send or publish something externally | Preview recipient and content; approval tied to exact arguments | Release with explicit oversight |
| Refund, delete or change access | Narrow permissions, duplicate prevention, recovery procedure | Defer unless essential |
| Administer multiple tenants | Separate administrative authority and isolation tests | Exclude from a general pilot |
Make the contract explain the business action
The MCP Tools specification defines tool names, descriptions, input schemas and optional output schemas. These help an agent select and use an operation. A name such as update_record provides little guidance; update_crm_contact gives it a clearer starting point.
Review each candidate tool with the API developer and the person who owns the workflow. Resolve these questions against actual behaviour:
- Purpose: When should this tool be used, and when should the agent choose another action or ask a person?
- Inputs: Which identifier is authoritative? Define required fields, allowed values, limits, time zones and the difference between an omitted field and
null. - Outputs: Return stable identifiers and an unambiguous outcome. Distinguish an accepted request from a completed action. Where an
outputSchemaexists, MCP requires conforming structured results and recommends client validation. - Consequences: State whether the action sends notifications, starts billing, changes access or triggers another system.
OpenAPI 3.2.1 is the current published specification and a useful basis for inspecting parameters, responses and security definitions. Compare your existing description with implementation and sample responses. A valid document alone cannot establish that a refund policy or approval process is correct.
You do not need to make a specification upgrade the first deliverable. Establish which version your validators and generators support, then fix the contract gaps that affect the chosen workflow.
Decide what happens when a call fails
A timeout after a write is particularly awkward: the change may have succeeded even though the caller received no result. Repeating the request could send a second email or create a duplicate transaction.
For repeatable writes, define and test an idempotency mechanism: the same logical request should not produce another action. Document how long duplicate protection lasts and what happens if the same key arrives with different arguments. Where completion is uncertain, provide a status lookup or a route to human review.
Separate invalid input, missing records, insufficient permission, business-rule rejection and temporary upstream failure. Each outcome needs a clear next step. Test expired credentials, rate limits, stale IDs, malformed responses and another tenant’s identifier. Agree retry limits per operation; do not let the agent improvise them.
Keep authority outside the model’s judgement
Map the user, MCP client, MCP server and downstream API, including which identity reaches each system. The MCP authorization specification covers HTTP transports and requires access-token validation for the MCP server’s intended audience. The security guidance explicitly forbids accepting tokens intended for other resources and passing them downstream.
Enforce user, tenant and record permissions in server-side code. A tenant ID supplied in tool arguments is something to validate against the caller’s authority. For agencies managing several clients, test that a valid identifier from one client cannot be used under another client’s credentials.
Separate read and write permissions where practical. For sensitive actions, show the actual recipient, amount, record or content before approval, and ensure the execution matches what was approved. Descriptions and tool annotations can inform the interface; they cannot enforce these boundaries.
Check the protocol version you actually run
The July 2026 MCP release introduced a stateless core without the earlier initialization handshake or protocol-level sessions. An integration built against a 2025 revision needs an explicit compatibility review across its client, server and SDK.
When migrating, inspect assumptions around Mcp-Session-Id and connection-bound state. Workflows that span calls should use explicit state handles where needed, with ownership checked on every use. A handle must never become a substitute for authorization.
Finish with a release decision and an owner
The audit should leave the team with an approved tool list, documented contract fixes, tested failure cases and named owners for approval, support and recovery. Agree how to disable an individual tool quickly. Log enough to investigate actions and approval decisions, while redacting credentials and limiting sensitive payloads.
During the pilot, review corrected and abandoned calls alongside completed tasks. Those are useful signals that a tool description, permission boundary or recovery path needs work.
If this crosses several suppliers or internal teams, talk to Greg about coordinating an agent-readiness review. Bring one proposed workflow and the API documentation; start by identifying the decisions and fixes needed for a controlled pilot.
Related on GrN.dk
- A Voice Agent Is Only Ready When the Human Handoff Works
- One Timeout, Two Orders: How to Make AI Actions Safe to Retry
- NGINX Can Read JSON Before Routing—Should It Handle Your AI API?
Need help with this kind of work?
Discuss an agent-readiness review with Greg Get in touch with Greg.