MCP integration: build a testable contract between AI and tools

The original specification describes a host application, clients inside that host and servers exposing capabilities through JSON-RPC. Servers can offer resources, prompts and tools. A resource supplies context; a tool exposes an operation. Conflating these concepts makes integration reviews harder because reading a document and changing a record have different failure consequences. 1

Anthropic’s launch framed MCP as a way to reduce custom connectors. That is a standardization objective, not proof that every server behaves consistently. 2 Keep the protocol boundary separate from the underlying API contract. A successful MCP message can still contain a business-level failure, such as an unavailable product or a customer record the user cannot access.

Imagine a service-desk integration. A lookup tool accepts a ticket identifier and returns a small, structured result. A separate update tool accepts explicitly permitted fields. This is easier to test than a general-purpose operation accepting arbitrary natural-language instructions and broad database access. The model should choose among defined capabilities, not improvise the backend’s validation rules.

Document required inputs, permitted values, result shape and business errors. Include the difference between an empty result and a denied request. Preserve identifiers so the host can show where information originated. Company knowledge addresses the organizational value of connected information; MCP integration needs the narrower guarantee that every returned field has a known meaning and authorized origin.

A server often translates a model-selected action into an existing API request. That translation must preserve the acting user’s authority. A shared service credential can make a demonstration work while silently broadening everyone’s access. The backend should enforce authorization independently of what the model claims the user requested or what a tool description says is allowed.

Separate local process credentials from remote service authentication. Do not copy a remote authorization recipe into a local transport design without checking the applicable protocol version and threat model. Authentication details have evolved since the initial specification. This article therefore does not present the November 2024 text as the complete authorization guidance for an implementation deployed in 2026.

Record the server build, SDK version, transport and negotiated capabilities in the integration inventory. A protocol name alone is insufficient for reproducibility. Test startup, capability discovery, malformed inputs, missing fields and responses larger than the host can reasonably process. A server upgrade should trigger contract tests before it is offered to production users.

Maintain fixtures for both successful and rejected operations. Check that structured outputs remain stable when backend APIs change and that errors do not leak secrets. Broader rules about permissions and approval ownership belong in agent safety. The engineering contribution here is a repeatable compatibility gate that catches an integration change before a model starts consuming a different contract.

A timeout does not establish whether the backend performed an action. For writes, use an application-level operation identifier where the underlying service supports it, then reconcile state before retrying. This is an integration pattern, not a claim that MCP itself guarantees exactly-once execution. Read-only tools also need limits: an unrestricted query can overload a database or return unnecessary personal information.

Return actionable failure categories to the host rather than a generic success-shaped paragraph. Separate invalid input, unavailable service, denied access and uncertain completion. The host can then request correction, retry within limits or escalate. AI security remains relevant, but precise error semantics are the technical mechanism that makes controlled recovery possible.

Begin with one read-only tool and a representative set of authorized users. Verify that permitted records are available, forbidden records remain inaccessible and absent records produce unambiguous results. Add a reversible write only after identity propagation and error handling are proven. Log metadata sufficient to replay failures without retaining entire sensitive payloads by default.

Acceptance should include a host restart, a server upgrade, a backend timeout and a permission change during a session. Assign ownership for both sides of the connector. Advisory can help prioritize this integration inventory. The enduring lesson from the 2024 launch is not merely that tools became easier to attach: their contracts still need to be engineered, tested and operated.