MCP vs OpenAPI: A Protocol vs an API Description, for AI Tools

MCP defines messages and their meaning. A server declares capabilities (tools, resources, prompts) during initialisation; the client asks tools/list to discover tools, each with a name, a description, an inputSchema (JSON Schema), and optionally an outputSchema and annotations; and it calls tools/call to run one. Messages travel over one of two standard transports: stdio, where the client launches the server as a subprocess, or Streamable HTTP, a single HTTPS endpoint that accepts POST and GET and may stream with server-sent events.

OpenAPI describes an HTTP API you already have. A document lists paths and operations, each with an operationId, parameters (path, query, header, cookie), a requestBody, responses, and references to securitySchemes for authentication. It says nothing about how a model should use the API; it is a machine-readable contract used for documentation, client and server code generation, testing, and gateways.

So the categories differ. MCP is closer to "HTTP plus a fixed set of methods for AI tools"; OpenAPI is closer to "a typed interface definition for one service".

Here is one capability, "get an order by ID", in each form. As an MCP tool, returned from tools/list:

1{2  "name": "get_order",3  "title": "Order lookup",4  "description": "Fetch one order by its ID. Use only for order questions.",5  "inputSchema": {6    "type": "object",7    "properties": { "order_id": { "type": "string" } },8    "required": ["order_id"]9  }10}

As an OpenAPI 3.1 operation:

1openapi: 3.1.02info: { title: Orders API, version: 1.0.0 }3paths:4  /orders/{id}:5    get:6      operationId: getOrder7      summary: Fetch one order by its ID8      parameters:9        - name: id10          in: path11          required: true12          schema: { type: string }13      responses:14        "200": { description: The order }15        "404": { description: No such order }

The difference is who executes. With MCP, the host sends tools/call to the server and the server runs whatever code implements the tool, returning content (and optionally structuredContent) or a result with isError: true. With an OpenAPI-based integration, the host reads the document, turns operations into function definitions for the model, and then builds and sends the HTTP request itself.

MCP fits when the consumer is an AI host and you want one server to work across several hosts, when tools are local (a CLI that reads files, a database on your laptop) and should run as a subprocess, or when the set of tools changes at runtime. It also suits curated tools: an MCP server can expose three narrow, well-described tools over an API that has three hundred endpoints.

An OpenAPI-described API fits when the API already exists and serves non-AI clients too, when you rely on gateways, SDK generation, and contract testing, and when stateless HTTP calls are all the model needs.

Each has a characteristic failure. MCP's is trust: a server is code or a remote service whose tool descriptions and outputs enter the model's context, so a malicious or careless server can inject instructions or receive data it should not; the spec says clients must treat tool annotations as untrusted unless the server is trusted, and should keep a human in the loop for sensitive operations. OpenAPI's is shape: exposing a large, fine-grained REST API to a model directly means many tools, ambiguous names, and multi-call workflows the model must assemble correctly.

In practice the two meet often. A team with an OpenAPI-described API builds an MCP server in front of it: each tool calls one or more API operations, and the server adds what a model needs: fewer, clearer tools, input validation, combined calls, trimmed output, and errors phrased so the model can recover.

A sketch of one such tool using the official TypeScript MCP SDK's high-level API:

1import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";2import { z } from "zod";3 4const server = new McpServer({ name: "orders", version: "1.0.0" });5 6server.registerTool(7  "get_order",8  {9    title: "Order lookup",10    description: "Fetch one order by ID. Use only for questions about a specific order.",11    inputSchema: { order_id: z.string().regex(/^ORD-\d+$/) },12  },13  async ({ order_id }) => {14    const res = await fetch(`${process.env.ORDERS_API}/orders/${order_id}`, {15      headers: { Authorization: `Bearer ${process.env.ORDERS_TOKEN}` },16    });17    if (res.status === 404) {18      return { content: [{ type: "text", text: `No order ${order_id}.` }], isError: true };19    }20    const order = await res.json();21    return { content: [{ type: "text", text: `Status: ${order.status}, total: ${order.total}` }] };22  }23);

The OpenAPI document stays the contract for the API; the MCP server is an AI-facing adapter with its own, smaller surface. Generating MCP tools directly from every OpenAPI operation is possible, but it tends to reproduce the "too many, too fine-grained" problem; curating is usually worth the effort.

The MCP specification's security requirements are a good checklist for either approach. Servers must validate all tool inputs, implement access controls, rate-limit invocations, and sanitise outputs. Clients should prompt for confirmation on sensitive operations, show tool inputs to the user before calling the server to avoid data exfiltration, validate results before passing them to the model, set timeouts, and log tool use for audit.

For Streamable HTTP servers the spec adds transport rules: validate the Origin header to prevent DNS-rebinding attacks, bind local servers to 127.0.0.1 rather than all interfaces, and authenticate all connections.

For OpenAPI-based integrations, the same principles apply through the API: scoped credentials per user, read-only operations exposed by default, and no operation that changes state without a confirmation step in the host. The model should never hold a credential broader than the user it acts for.

1. Pick one read-only operation from an API you own and write its OpenAPI 3.1 description with an operationId, parameters, and 200 and 404 responses.
2. Write an MCP server with a single tool that calls that operation, validates input, and returns a short text result or isError: true.
3. Connect the MCP server to one host (for example Claude Code with claude mcp add, or Gemini CLI with gemini mcp add) and ask a question that needs the tool.
4. Ask a question that should not use the tool, and one with an invalid ID.
5. Compare: how many tokens of tool definition and output did each design put in context, and which errors could the model recover from?

Pass criterion: the same capability works through both, the MCP tool refuses invalid input itself, and you can state which design you would ship for AI hosts and why.