Before Your MCP Rollout, Audit the API Contract

Illustrated infographic summarizing: Agent-ready APIs need a contract audit before MCP rollout

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
Choose tools by business consequence, then verify that the controls exist in the implementation.

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 outputSchema exists, 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

Need help with this kind of work?

Discuss an agent-readiness review with Greg Get in touch with Greg.

Sources

Latest articles

Before changing an AI workflow, check that it still does the job. Use realistic examples, clear release criteria and a comparison with the version running today.

Sending an invoice does not mean it has arrived. Understand delivery statuses, the system requirements coming in 2027, and how focused AI support can help finance teams handle errors and follow-up.

Before scaling AI content, check the pages you already have. Verify claims, resolve overlapping coverage, and give WordPress reviewers control over publication.

Build a refund approval workflow in n8n and Stripe that shows reviewers the exact action, expires old approvals and tracks refunds through to completion.

A timeout can hide a successful job creation. Use stable operation IDs, destination API rules and a clear recovery process to prevent duplicate work.

Does your ChatGPT subscription cover website translation? Understand API credits, access and a WordPress workflow that turns approved Danish content into translation drafts.

An internal AI can keep quoting a deleted policy. Check document updates, indexed passages and cached answers to find where outdated guidance survives.

Codex drew all ten pages of my Ninjai comic from the script Claude wrote in the first test. What made that handover work, and what it cost.

ChatGPT delivered ten painted comic pages; Claude drew one page in code. A practical look at AI tool selection, creative briefs and approval decisions.

Get missing supporting documents under control with a clearly scoped AI workflow that sorts replies, coordinates reminders and gives the bookkeeper a clear follow-up list.