III · Tool Use & EnvironmentEmerging★

Direct API Wrapper

also known as Direct Translation, 1:1 API-to-MCP Mapping, Thin MCP Wrapper, API-to-MCP Wrapper

Expose an existing API as MCP tools by mapping each operation one-to-one to a tool, so a stable API becomes agent-callable with minimal wrapper logic.

This pattern helps complete certain larger patterns —

  • specialisesModel Context Protocol★★— Standardise how agents discover and call tools so that a tool written once is usable by any conformant agent.

Context

An organisation already runs a stable, well-documented HTTP API and wants agents to call it without re-implementing business logic. The API has an OpenAPI document or a typed SDK, and the team wants the fastest path to making every operation reachable from MCP-speaking hosts.

Problem

Agents cannot call a raw HTTP API through MCP; something must translate the API surface into the protocol's typed tool contract. Hand-writing an MCP tool for every endpoint is repetitive and drifts from the API as it changes, while skipping the wrapper leaves the API unreachable from any MCP host. The team needs the operations exposed quickly without inventing new semantics or maintaining a parallel hand-coded layer.

Forces

  • Speed of integration competes with the quality of the agent-facing interface.
  • A one-to-one mapping is cheap to generate but can flood the agent with many low-level tools.
  • Endpoint names and error shapes were designed for programmers, not for a model choosing among tools.
  • Generated wrappers stay in sync with the contract but inherit its granularity.
  • Auth and rate limits of the underlying API now apply per individual tool call.

Example

A team owns a stable customer API described by an OpenAPI document. Rather than hand-write an MCP tool per endpoint, they run a generator that emits one tool for each operation — createCustomer, getCustomer, listInvoices — and serve them over MCP. An agent in Claude Desktop can now call the API the same day, and when the API adds an endpoint the team regenerates the server instead of editing tool code by hand.

Diagram

Solution

Therefore:

Map each API operation to a single MCP tool, deriving the tool name, input schema, and output shape from the API contract — an OpenAPI document or a typed SDK. A generator reads the contract and emits the server, so the tool surface tracks the API rather than a hand-written copy: FastMCP's from_openapi/from_fastapi, fastapi-mcp, and the Speakeasy and Stainless generators all follow this shape, and API gateways such as Kong can autogenerate the same server from any REST API. This is the thinnest wrapper and the baseline against which composite-service-mcp is the next step once the one-to-one surface proves too granular; when the orchestration itself is better written as code, mcp-as-code-api applies. Keep the wrapper free of new business logic so regeneration stays cheap.

What this pattern forbids. The server may expose only the operations the underlying API already provides, one tool per operation; it must not add orchestration, merge endpoints, or invent capabilities the API does not have.

And the patterns that stand alongside it, or against it —

  • alternative-toComposite Service★— Expose one MCP tool that orchestrates several underlying API calls into a single higher-level operation, so the agent invokes a task-level capability instead of chaining many low-level endpoints.
  • complementsTranslation Layer★★— Insert a typed boundary between the agent's clean domain model and a messy or legacy external API.
  • complementsAgent Adapter★★— An interface layer connecting an agent's tool-calling protocol to heterogeneous external tools, normalizing their schemas into one the agent expects.
  • complementsMCP-as-Code-API★— Materialize MCP servers as a directory of typed code wrappers so the agent writes code that imports them and large tool outputs flow between calls inside the sandbox without ever entering the model's context window.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

References

Provenance