---
title: "MCP vs API: what changes when an AI agent calls your service"
description: "MCP vs API compared: who calls, discovery, JSON-RPC vs REST, auth, errors, and context cost, with one GitHub request shown both ways and when to use each."
summary: "An MCP server does not replace an API: it usually wraps one or more APIs and exposes them to models as discoverable tools described for a model to read. This comparison sets the two side by side, shows one GitHub request as a REST call and as an MCP tools/call, and covers when to build each."
type: "comparison"
canonical_url: "https://theaiengineering.com/articles/mcp-vs-api"
markdown_url: "https://theaiengineering.com/articles/mcp-vs-api.md"
topic: "Model Context Protocol"
author: "The AI Engineering Editors"
publisher: "The AI Engineering"
published: "2026-11-18"
updated: "2026-11-18"
keywords: ["mcp vs api","mcp vs rest api","mcp server vs rest api","mcp vs api difference","mcp vs api example"]
citation: "The AI Engineering Editors. \"MCP vs API: what changes when an AI agent calls your service.\" The AI Engineering, updated Nov 18, 2026. https://theaiengineering.com/articles/mcp-vs-api"
---

# MCP vs API: what changes when an AI agent calls your service

## TL;DR

- MCP does not replace APIs: an MCP server usually wraps one or more existing APIs and exposes them to AI applications as tools that a model can discover and call at runtime.
- With a plain API, developer code decides which endpoint to call when the code is written; with MCP, the model chooses a tool at runtime from the names, descriptions, and JSON Schema inputs that tools/list returns.
- MCP messages are JSON-RPC 2.0 over stdio or Streamable HTTP, and the current revision, 2026-07-28, is stateless: every request carries its protocol version and client capabilities in _meta.
- Tool definitions cost context: Anthropic reported 58 tools from five MCP servers consuming about 55,000 tokens before a conversation started, so large APIs need a few task-shaped tools rather than one tool per endpoint.
- Use a plain API for deterministic integrations, direct tool calling for a few tools inside one application, and an MCP server when several AI hosts or teams should reuse the same capability.

MCP and APIs are not alternatives. An API is the interface a service offers to programs, and the [Model Context Protocol](https://theaiengineering.com/glossary/model-context-protocol) (MCP) is a standard way for AI applications to discover and call capabilities at runtime, usually through an [MCP server](https://theaiengineering.com/glossary/mcp-server) that wraps one or more existing APIs. The MCP vs API question is really about what changes when the caller is a model instead of code you wrote: who decides to call, how the interface is described, how calls travel, and how they are authorized. This comparison checks each difference against the current MCP specification, revision 2026-07-28, shows one GitHub request both ways, and ends with when to build which. For the protocol's architecture, start with [what the Model Context Protocol is](https://theaiengineering.com/articles/what-is-model-context-protocol).

## What is the difference between MCP and an API?

An API is a contract between a service and the developers who write code against it. MCP is a protocol between AI applications and servers that describe their capabilities to a model. An MCP server usually sits in front of APIs: the model picks a tool, the server turns the call into API requests, and the API does the work.

GitHub shows the layering. It offers a REST API and a GraphQL API for code, and a separate [GitHub MCP server](https://github.com/github/github-mcp-server) (MIT licensed, written in Go) for AI hosts, with a remote endpoint at `https://api.githubcopilot.com/mcp/`. In the server's current source, its `list_issues` tool queries GitHub's GraphQL API, not the REST issues endpoint. The host never sees that choice, because the MCP tool is its own interface, designed for a model to read.

**Figure 1: An MCP server is a layer in front of existing APIs, shared by every AI host; ordinary code still calls the APIs directly.**

Backend code calls a REST API directly, while two AI hosts reach the same REST API, a GraphQL API, and a database through one MCP server that wraps them.

Components:

- **Backend code**: Calls known endpoints
- **AI host**: Model + MCP client
- **Another AI host**: Same server, no glue code
- **MCP server**: tools/list, tools/call Schemas written for models
- **REST API**: System of record
- **GraphQL API**: System of record
- **Database**: Internal data

Groups:

- AI applications: AI host, Another AI host
- Your service: REST API, GraphQL API, Database

Connections:

- Backend code → REST API: HTTPS + API key
- AI host → MCP server: JSON-RPC
- Another AI host → MCP server: JSON-RPC
- MCP server → REST API
- MCP server → GraphQL API
- MCP server → Database

MCP adds what a model needs and a developer does not: runtime discovery, descriptions written for a model, [JSON Schema](https://theaiengineering.com/glossary/json-schema) inputs, one result and error format for every tool, and a consent model in which the host asks the user before acting. It does not store data, enforce business rules, or replace the API's own authorization. MCP also does not replace [tool calling](https://theaiengineering.com/articles/tool-calling): the model still emits calls through its provider's tool calling interface, and MCP standardizes where those tools come from and how the host executes them.

## MCP vs API at a glance

The table compares a conventional HTTP API (REST or gRPC) with an MCP server on the dimensions that change when a model becomes the caller. MCP entries follow the [2026-07-28 specification](https://modelcontextprotocol.io/specification/2026-07-28); API entries describe common practice, with GitHub's REST API as the running example.

| Dimension | API (REST or gRPC) | MCP server |
|---|---|---|
| Who decides to call | Developer code, written ahead of time | The model at runtime; the host executes, and a person can deny the call |
| Discovery | Documentation, SDKs, or an OpenAPI document read at build time | `tools/list` at runtime, paginated and cacheable; `server/discover` for versions |
| Interface description | OpenAPI or Protocol Buffers, written for developers and generators | Tool `name`, `description`, `inputSchema`, optional `outputSchema` and `annotations`, read by the model |
| Transport and protocol | REST: resource URLs, verbs, status codes; gRPC: Protocol Buffers | JSON-RPC 2.0 over stdio or Streamable HTTP (POST to one endpoint) |
| Session state | Stateless requests by convention; state lives in resources | Stateless since 2026-07-28; cross-call state travels as explicit handles |
| Auth | API keys, OAuth 2.0 scopes, or mTLS, defined by each API | Optional; OAuth 2.1-based, audience-bound tokens over HTTP; environment credentials on stdio |
| Primitives beyond calls | None at the protocol level | Resources, prompts, and elicitation; sampling and roots deprecated |
| Error handling | HTTP status codes with an error body | JSON-RPC errors for protocol failures; `isError: true` results the model can correct |
| Versioning | Per API, in the URL or a header such as `X-GitHub-Api-Version` | Date-stamped protocol revision on every request; no version field on tools |
| Performance and context cost | One network round trip; nothing enters a model's context | Extra hop and model round trips; each loaded tool definition occupies context |

## Who decides to call: developer code or the model

The biggest difference is who chooses the call. With an API, a developer reads the documentation and writes code that calls a specific endpoint with specific parameters, and that code behaves the same way every run. With MCP, the model reads tool definitions at runtime and decides which tool to call, with which arguments, based on the conversation.

That shift changes what counts as the interface. A REST endpoint's documentation can be long, because a person reads it once. An MCP tool's description is read by the model on every request that includes it, so it must say in a sentence or two what the tool does and when to use it. The [MCP tools page](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) calls tools model-controlled: the model discovers and invokes them.

It also changes what the server must assume. Developer code sends the calls it was written to send; a model can pick the wrong tool, invent an ID, or follow instructions planted in a tool result. The specification says there should always be a [human in the loop](https://theaiengineering.com/glossary/human-in-the-loop) who can deny tool invocations, and it requires servers to validate all inputs, enforce access controls, rate limit invocations, and sanitize outputs. In [tool calling](https://theaiengineering.com/glossary/tool-calling) terms, the model only requests the action; the host and server decide whether it happens.

## The same operation shown both ways

The clearest MCP vs API example is one task done twice, here listing a repository's open bugs on GitHub. As a REST call, it is one GET request with query parameters. As an MCP call, it is a tool definition the host lists first, then a JSON-RPC `tools/call` message whose arguments the model filled in.

### As a REST request

GitHub's [list repository issues](https://docs.github.com/en/rest/issues/issues#list-repository-issues) endpoint takes the filters as query parameters. `state` accepts `open`, `closed`, or `all`, `labels` is a comma-separated list, and `per_page` defaults to 30 with a maximum of 100. The version header pins the API version, here the newest one GitHub listed on November 16, 2026:

```bash
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/repos/OWNER/REPO/issues?state=open&labels=bug&per_page=20"
```

The response is a JSON array of issue objects, failures come back as HTTP status codes, and the developer chose the endpoint, parameters, and token in advance.

### As an MCP tool definition and tools/call

Before the model can call anything, the host sends `tools/list` and receives definitions like the one below, abridged from the GitHub MCP server's source (the full schema adds sorting, date, field, and cursor parameters). This text is what the model reads:

```json
{
  "name": "list_issues",
  "description": "List issues in a GitHub repository. For pagination, use the 'endCursor' from the previous response's 'pageInfo' in the 'after' parameter.",
  "annotations": { "title": "List issues", "readOnlyHint": true },
  "inputSchema": {
    "type": "object",
    "properties": {
      "owner": { "type": "string", "description": "Repository owner" },
      "repo": { "type": "string", "description": "Repository name" },
      "state": {
        "type": "string",
        "description": "Filter by state, by default both open and closed issues are returned when not provided",
        "enum": ["OPEN", "CLOSED"]
      },
      "labels": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Filter by labels"
      }
    },
    "required": ["owner", "repo"]
  }
}
```

When the model decides to use the tool, the host sends a `tools/call` request. Over Streamable HTTP in the 2026-07-28 revision, it is a POST to the server's single endpoint, with the protocol version, method, and tool name mirrored into headers and repeated in the body's `_meta`:

```http
POST /mcp/ HTTP/1.1
Host: api.githubcopilot.com
Authorization: Bearer <token issued for this MCP server>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: list_issues

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "list_issues",
    "arguments": { "owner": "OWNER", "repo": "REPO", "state": "OPEN", "labels": ["bug"], "perPage": 20 },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-host", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}
```

A server still on an earlier revision, such as 2025-11-25, receives the same `name` and `arguments` after an `initialize` handshake, without the per-request `_meta` fields. The result comes back as a JSON-RPC response with `resultType: "complete"`, a `content` array (the GitHub server returns the issues as JSON text), and optionally `structuredContent` that matches the tool's output schema.

### Where the two requests differ

The two requests reach the same data but differ in almost every detail. REST takes `state=open` and `per_page`; the MCP tool takes `"OPEN"` and `perPage`, and paginates with a cursor (`after`) instead of page numbers, because the server is built on GraphQL. The `enum` tells the model exactly which states exist, and a host can validate arguments before sending them. The REST call carries a GitHub token the developer chose, while the MCP call carries a token for the MCP server. And the REST response goes to code that knows its shape, while the MCP result goes into the model's context, where its size and wording matter.

## The two call paths, step by step

A direct API call is one request that code makes and code reads. An MCP call is a loop: the host lists tools, the model sees their definitions and chooses one, the host checks or asks for approval, the MCP server calls the API, and the result returns to the model's context. Each step adds latency and a decision point.

**Figure 2: Steps 1 and 2 are a direct API call; steps 3 to 12 are the MCP path, where the model chooses the call and the server makes it.**

Sequence comparing a direct REST call from application code with an MCP call, where the app lists tools, the model picks one, and the MCP server calls the API.

Steps:

1. Your app → REST API: GET /repos/.../issues
2. REST API → Your app: 200 OK, JSON
3. Your app → MCP server: tools/list
4. MCP server → Your app: tool definitions
5. Your app → Model: prompt + tool list
6. Model → Your app: call list_issues
7. Your app → MCP server: approve, tools/call
8. MCP server → REST API: API call, own token
9. REST API → MCP server: API response
10. MCP server → Your app: content, isError
11. Your app → Model: result into context
12. Model → Your app: final answer

Two of the extra steps can be cheap: `tools/list` results carry a `ttlMs` freshness hint, so a host need not list tools before every call, and approval can be automatic for read-only tools under a policy the user set. The model round trips cannot be skipped, and each inference call usually takes far longer than the API request itself.

## MCP vs REST API: transport, sessions, and state

MCP is not REST. A REST API exposes resources at URLs and uses HTTP verbs and status codes; MCP sends [JSON-RPC 2.0](https://theaiengineering.com/glossary/json-rpc) messages, either over a subprocess's standard input and output or as HTTP POSTs to a single endpoint. Since the 2026-07-28 revision, MCP is also stateless: every request carries everything a server needs to process it.

The MCP server vs REST API difference shows up first in how messages travel. MCP defines two standard [transports](https://theaiengineering.com/glossary/mcp-transport):

- **stdio.** The host launches the server as a subprocess and exchanges newline-delimited JSON-RPC messages over stdin and stdout, with logs on stderr. There is no HTTP layer, so there are no headers, status codes, or URLs.
- **Streamable HTTP.** The server exposes one endpoint, such as `https://example.com/mcp`. Every client message is its own POST, and the server answers each request with one JSON object or a server-sent events stream scoped to that request.

The [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http) still borrows from HTTP where it helps intermediaries. Every POST carries `MCP-Protocol-Version` and `Mcp-Method` headers, plus `Mcp-Name` for `tools/call`, `resources/read`, and `prompts/get`, so load balancers and gateways can route without parsing the body. Servers reject requests whose headers do not match the body with a `HeaderMismatch` error (`-32020`).

On state, REST and modern MCP now agree. The 2026-07-28 revision removed MCP's `initialize` handshake and the `Mcp-Session-Id` header, so any server replica can answer any request. A server that needs state across calls, such as an open shopping cart, returns a handle that the model passes back as an ordinary tool argument. Revisions 2025-03-26 through 2025-11-25 allowed protocol-level sessions, so older servers and tutorials still use them.

## Discovery and interface description: OpenAPI vs tools/list

An API is described ahead of time, most often in an OpenAPI document that developers and code generators read before a line of client code runs. An MCP server describes itself at runtime: the host calls `tools/list` and receives each tool's name, description, and schemas, written for the model that will choose among them.

The two descriptions share a schema language. The [OpenAPI Specification](https://spec.openapis.org/oas/latest.html), at version 3.2.1 since September 10, 2026, defines its Schema Object as a superset of JSON Schema Draft 2020-12, and MCP's `inputSchema` and `outputSchema` default to JSON Schema 2020-12 when no `$schema` is given. So converting an OpenAPI operation's parameters into a tool schema is mechanical, but the text is not: an OpenAPI summary is written for a developer browsing reference docs, while a tool description must tell a model when to pick this tool over its neighbors.

Runtime discovery has rules of its own in the current specification:

- **Caching.** `tools/list` supports cursors, and its result must include `ttlMs`, a freshness hint in milliseconds, and `cacheScope` (`public` or `private`), which says whether shared intermediaries may cache it.
- **Stable order.** Servers should return tools in a deterministic order, which the specification says improves prompt cache hit rates when tools are included in model context.
- **Per-caller lists.** The list must not vary per connection, but may vary by the authorization on the request, so a token with fewer scopes can see fewer tools.

## Primitives beyond tools

A REST or gRPC API exposes operations and nothing else at the protocol level. MCP defines more: servers can offer tools, resources, and prompts, and clients can offer elicitation, which lets a server ask the user for input partway through a request. The 2026-07-28 revision deprecated two older client features, sampling and roots.

The [server features overview](https://modelcontextprotocol.io/specification/2026-07-28/server) assigns each primitive a controller: tools are model-controlled functions, resources are application-controlled context such as file contents, and prompts are user-controlled templates such as slash commands.

Elicitation has two modes. Form mode collects structured data that the client sees, and the specification forbids using it for passwords, API keys, access tokens, or payment credentials. URL mode sends the user to a web page for sensitive steps, such as a third-party OAuth flow, so that data bypasses the client and the model. Either way, the server returns `resultType: "input_required"` and the client retries the request with the answers.

Sampling (a server borrowing the client's model) and roots (a client sharing directories) still work during their deprecation window, but new implementations should not adopt them. Optional extensions add long-running Tasks and MCP Apps for interactive UI.

## Authentication and authorization

APIs authenticate callers however each API chooses, usually with API keys or OAuth 2.0 scopes. MCP standardizes one flow for HTTP servers: an OAuth 2.1-based authorization in which the MCP server acts as a resource server and accepts only tokens issued for itself. Authorization is optional in MCP, and stdio servers read credentials from their environment instead.

The [authorization specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization) builds the flow from existing standards. A protected server must publish OAuth 2.0 Protected Resource Metadata (RFC 9728) so clients can find its authorization server. Clients must name the server in a Resource Indicator (RFC 8707), and servers must check that each token was issued for them. When a call needs more permission, the server should answer with HTTP 403 and the scopes required, so the client can step up its authorization.

MCP also forbids token passthrough. The specification says an MCP server "MUST NOT accept or transit any other tokens," so it cannot forward the client's MCP token to the API it wraps. A wrapping server therefore runs two separate hops:

1. **Host to MCP server**, with a token issued for the MCP server.
2. **MCP server to the API**, with the server's own credential for that API, such as a service account or a per-user token the server stores.

When the server needs a user's consent for the upstream API, URL-mode elicitation lets it send the user through that API's OAuth flow directly, so the third-party credentials never transit the MCP client. The split takes more work than pasting an API key into a config file, but it keeps each hop's permissions attached to the right identity.

## Errors and versioning

APIs report errors with HTTP status codes and version themselves however their owners choose. MCP separates protocol errors from tool errors so that a model can recover from the second kind, and it versions the protocol on every request rather than versioning individual tools, which changes how a wrapper around an API should behave.

### Error handling

The MCP specification defines two error channels. Protocol errors, such as an unknown tool or a malformed request, return as JSON-RPC errors; an unknown tool is code `-32602`. Tool execution errors, such as API failures, invalid values, and business-rule violations, return as normal results with `isError: true` and a message that clients should pass to the model, so it can retry with corrected arguments.

For a server that wraps an API, this means translating status codes into sentences. A 404 should become an `isError` result naming the ID that was not found, a validation failure should name the field and the expected format, and a rate limit should say when to retry. A bare "request failed" gives the model nothing to correct.

### Versioning

GitHub's REST API uses date-named versions in the `X-GitHub-Api-Version` header. On November 16, 2026, its [API versions page](https://docs.github.com/en/rest/about-the-rest-api/api-versions) listed `2026-03-10` and `2022-11-28` as supported, with `2022-11-28` as the default and each previous version supported for at least 24 months after a newer one ships.

MCP also uses dates, but for the protocol. Every request declares a revision, such as `2026-07-28`, and a server that does not support it returns an `UnsupportedProtocolVersionError` (`-32022`) listing the versions it does support. Tools have no version field: clients learn about a renamed tool or a changed schema from the next `tools/list` or a list-changed notification. Allowlists and prompts that name a tool break when it is renamed, so treat tool names and schemas with the same change discipline as public endpoints.

## Performance and context cost of tool definitions

A direct API call adds nothing to a model's context. An MCP tool adds its definition to every model request that includes it, so a large tool list costs tokens and attention before the conversation starts. That cost, more than network latency, is usually the performance difference that matters when choosing between an API and MCP.

Anthropic's engineering team [described the effect](https://www.anthropic.com/engineering/advanced-tool-use) in November 2025: a setup with five MCP servers (GitHub, Slack, Sentry, Grafana, and Splunk) exposed 58 tools that consumed approximately 55,000 tokens before the conversation began, and the team reported seeing tool definitions consume 134,000 tokens internally before optimization. Those definitions are resent on each model request that carries the tools, and a crowded [context window](https://theaiengineering.com/glossary/context-window) also makes selection harder: in the same post, Anthropic reported that deferring definitions with its Tool Search Tool raised Claude Opus 4's accuracy on its MCP evaluations from 49% to 74%.

Ways to keep the cost down:

- **Load fewer tools.** The GitHub MCP server groups tools into toolsets and enables a default set (context, repos, issues, pull requests, and users) unless configured otherwise, and its `--read-only` flag drops write tools. Tool search features, such as Anthropic's Tool Search Tool, defer rarely used definitions.
- **Shape tools around tasks.** One search tool with filters costs less context than a tool for every endpoint.
- **Let the model write code against the API.** Cloudflare's MCP server for its API, which has over 2,500 endpoints, exposes two tools, `search()` and `execute()`, in [about 1,000 tokens](https://blog.cloudflare.com/code-mode-mcp/); Cloudflare estimated that an equivalent server without this approach would consume 1.17 million tokens. Some gateways apply the same idea across servers, and Maxim AI's [Bifrost Code Mode documentation](https://docs.getbifrost.ai/mcp/code-mode) reports input tokens falling by 92.8% in its own benchmark of 508 tools across 16 servers, at the same pass rate. Benchmark any of these on your own tools and tasks.

Each host converts MCP definitions into its provider's tool format, such as the `tools` array of an [OpenAI-compatible API](https://theaiengineering.com/glossary/openai-compatible-api) request, so the cost applies with any provider.

## When to use an API, an MCP server, or both

Use a plain API when your own code calls a known endpoint in a fixed workflow. Use direct tool calling when one application gives one model a few functions. Build an MCP server when several AI hosts, agents, or teams should reuse the same capability without custom glue. Offer both when developers and agents are both your users.

| Scenario | Use | Why |
|---|---|---|
| Backend jobs, webhooks, or UI code calling a known endpoint | Plain API | Deterministic, cheapest, no model in the path |
| One application, one model provider, a handful of functions over your API | Direct tool calling | Tool definitions live in application code; no extra server to run |
| A capability that should work in Claude, ChatGPT, Cursor, VS Code, and your own agents | MCP server | One server, many hosts, discovered at runtime |
| Internal systems that many teams' agents need under one policy | MCP servers behind an MCP gateway | Central authentication, tool allowlists, and audit logs |
| A public platform with both developers and agent users | API and MCP server | The API serves code; a curated MCP server serves models |
| An API with hundreds or thousands of endpoints | MCP server with toolsets or search-and-execute tools | Avoids loading every endpoint's definition into context |

A remote MCP server also reaches model APIs directly. OpenAI's Responses API accepts an `mcp` tool with a `server_url`, asks for approval before sharing data by default, and can import an `allowed_tools` subset, per its [MCP guide](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). Anthropic's MCP connector, in beta on the Messages API as of November 2026, supports only tool calls on remote HTTP servers.

GitHub and Cloudflare both offer both: a full API for code, and an MCP server designed for models, with curated toolsets at GitHub and two code-execution tools at Cloudflare. The API remains the source of truth, and the MCP server is a client of it with its own release cycle.

## Generating an MCP server from an OpenAPI spec

Several tools generate an MCP server from an OpenAPI document, which makes a first version quick to produce. The output inherits the API's shape: one tool per endpoint, descriptions written for developers, and parameters that mirror HTTP. Generated servers work best as a starting point that a person then curates.

Generators with documented behavior include:

- **FastMCP.** The Prefect-maintained framework's `FastMCP.from_openapi()` method [converts an OpenAPI spec](https://gofastmcp.com/integrations/openapi), and by default every endpoint becomes a tool. Route maps can reclassify or exclude routes, and the documentation states that models perform significantly better with well-designed, curated MCP servers than with auto-converted ones.
- **Speakeasy.** `speakeasy quickstart --mcp` [generates a TypeScript MCP server](https://www.speakeasy.com/docs/standalone-mcp/build-server) from an OpenAPI document. An `x-speakeasy-mcp` extension customizes tool names, descriptions, and scopes, and a dynamic mode exposes only a few meta-tools, such as `list_tools` and `execute_tool`, for APIs with many operations.
- **AWS Labs OpenAPI MCP Server.** This open-source server [creates MCP tools](https://awslabs.github.io/mcp/servers/openapi-mcp-server) from the endpoints in an OpenAPI spec. Its documentation lists limits: stdio transport only, internal `$ref` targets only (split specs must be bundled), and no credential inheritance for additional specs.

Gateways can do this at the network layer: IBM's ContextForge, an Apache 2.0 project, adapts REST APIs into MCP tools and translates gRPC services through server reflection.

The common limits follow from the API's design, not the generator's quality. Dozens of endpoints become dozens of definitions in context. OpenAPI summaries rarely say when to choose one operation over a similar one, which is the question a model faces. A task that takes three API calls becomes three tool calls for the model to chain, and full payloads with opaque IDs consume context that a curated tool would trim.

A practical workflow is to generate, then cut: exclude write and admin routes, merge endpoints that always run together, rewrite each remaining description for a model, and test the result on real tasks. [How to build an MCP server](https://theaiengineering.com/articles/how-to-build-an-mcp-server) shows a hand-written wrapper of this kind.

## Security and governance for model-driven calls

A model-driven call needs controls that a developer-written call does not, because the caller can be wrong or manipulated. Restrict which tools each user or agent can see, require approval for writes, treat tool descriptions and results as untrusted input, and log every call. A gateway in front of MCP servers can apply these rules centrally.

The controls, by layer:

- **Allowlists.** Expose only the tools a workflow needs, through server options such as GitHub's toolsets and read-only mode, host settings such as OpenAI's `allowed_tools`, or per-caller filtering in a gateway.
- **Approvals.** The MCP tools page says clients should confirm sensitive operations and show tool inputs to the user before calling the server.
- **Untrusted text.** Tool descriptions, annotations, and results all enter the model's context, so they can carry [prompt injection](https://theaiengineering.com/glossary/prompt-injection); a description changed after approval is a form of [tool poisoning](https://theaiengineering.com/glossary/tool-poisoning).
- **Least privilege upstream.** Back read-only tools with read-only API credentials.
- **Audit.** The specification says clients should log tool usage for audit purposes.

An [MCP gateway](https://theaiengineering.com/glossary/mcp-gateway) applies these controls once for many servers. [Bifrost](https://docs.getbifrost.ai/mcp/overview), for example, exposes the MCP servers it connects to at one `/mcp` endpoint, filters tools per virtual key, and does not execute a model's tool calls unless the application calls its execute endpoint or turns on agent mode with configured auto-approval.

The [AI gateway explainer](https://theaiengineering.com/articles/what-is-an-ai-gateway) covers the gateway pattern for model and tool traffic, and the [MCP platforms directory](https://theaiengineering.com/platforms/mcp-platforms) lists other MCP gateways, registries, and hosting options.

## Where to go next

MCP sits on top of APIs and tool calling, so the next reads depend on which side you are building. For the server side, follow [how to build an MCP server](https://theaiengineering.com/articles/how-to-build-an-mcp-server); for the protocol that connects agents to other agents rather than to tools, read [A2A vs MCP](https://theaiengineering.com/articles/a2a-vs-mcp). The [MCP topic hub](https://theaiengineering.com/topics/mcp) collects every guide on the protocol.

## Frequently asked questions

### Does MCP replace APIs?

No. MCP is a protocol for connecting AI applications to capabilities, and most MCP servers call existing APIs to do the work. GitHub's MCP server, for example, implements its list_issues tool with GitHub's GraphQL API. The API stays the system of record for data, permissions, and business rules, while the MCP server adds runtime discovery, descriptions written for models, and a call format that any MCP host understands.

### Is MCP just an API wrapper?

Often, but a useful MCP server is more than a pass-through. A thin wrapper that maps every endpoint to a tool exposes too many tools, with descriptions written for developers. A well-designed server offers a few tools shaped around tasks, constrains inputs with JSON Schema, returns compact results, turns API failures into errors a model can act on, and adds resources or prompts where they help.

### Is MCP a REST API?

No. Over the Streamable HTTP transport, MCP runs on HTTP, but every message is a JSON-RPC 2.0 request sent as a POST to one endpoint, such as /mcp, rather than HTTP verbs on resource URLs. The method and tool name are mirrored into Mcp-Method and Mcp-Name headers so gateways can route requests. Over the stdio transport, MCP does not use HTTP at all.

### Why use MCP instead of calling an API directly?

Use MCP when the caller is a model and the capability should work in many AI applications. One MCP server works in any compatible host, such as Claude, ChatGPT, Cursor, or VS Code, and each host lists its tools at runtime instead of shipping custom integration code. When your own code calls a known endpoint in a fixed workflow, calling the API directly is simpler, faster, and cheaper.

### Can you convert an OpenAPI spec into an MCP server?

Yes. FastMCP's from_openapi method, Speakeasy's generator, and the AWS Labs OpenAPI MCP Server all build MCP tools from an OpenAPI document. By default FastMCP turns every endpoint into a tool, and its documentation says models perform significantly better with curated servers. Treat a generated server as a starting point: exclude routes, merge related endpoints, and rewrite descriptions for a model.

## Terms in this guide

- [Model Context Protocol (MCP)](https://theaiengineering.com/glossary/model-context-protocol): Model Context Protocol (MCP) is an open protocol, introduced by Anthropic in November 2024, that standardizes how AI applications connect to external tools, data sources, and prompts through MCP servers.
- [MCP server](https://theaiengineering.com/glossary/mcp-server): An MCP server is a program that exposes tools, resources, and prompts to AI applications through the Model Context Protocol, running locally over stdio or remotely over Streamable HTTP.
- [Tool calling](https://theaiengineering.com/glossary/tool-calling): Tool calling is an LLM capability in which the model, given a list of tool definitions, outputs a structured request naming a tool and its arguments, which the application executes and returns.
- [JSON-RPC](https://theaiengineering.com/glossary/json-rpc): JSON-RPC is a lightweight, transport-agnostic remote procedure call protocol that encodes method calls, results, and errors as JSON objects; version 2.0 is the message format of MCP and A2A.
- [MCP transport](https://theaiengineering.com/glossary/mcp-transport): An MCP transport is the binding that carries Model Context Protocol messages between a client and a server; the specification defines stdio for local subprocesses and Streamable HTTP for remote servers.
- [JSON Schema](https://theaiengineering.com/glossary/json-schema): JSON Schema is a declarative vocabulary, itself written in JSON, for describing the structure of JSON data; LLM APIs and MCP use it to define tool arguments and constrain model output.
- [OpenAI-compatible API](https://theaiengineering.com/glossary/openai-compatible-api): An OpenAI-compatible API is an HTTP API that accepts OpenAI's request and response formats, so code written for OpenAI's SDKs can call another server by changing the base URL, API key, and model name.
- [Context window](https://theaiengineering.com/glossary/context-window): A context window is the maximum number of tokens a language model can take into account in a single request, including the system prompt, conversation history, tool results, and the generated output.
- [Human-in-the-loop](https://theaiengineering.com/glossary/human-in-the-loop): Human-in-the-loop (HITL) is an agent design in which the run pauses at defined checkpoints, such as before a sensitive tool call, so a person can approve, edit, or reject the action.
- [Prompt injection](https://theaiengineering.com/glossary/prompt-injection): Prompt injection is an attack in which text supplied to a large language model, typed by a user or hidden in content the model reads, alters the application's intended behavior or output.
- [Tool poisoning](https://theaiengineering.com/glossary/tool-poisoning): Tool poisoning is an attack in which a malicious or compromised MCP server hides instructions in a tool's description or schema, which the model reads as trusted context and may follow.
- [MCP gateway](https://theaiengineering.com/glossary/mcp-gateway): An MCP gateway is a proxy that sits between MCP hosts and many MCP servers, exposing them through one endpoint and centralizing authentication, tool access policy, and audit logging.

## Related guides

- [What is the Model Context Protocol (MCP)? How it works](https://theaiengineering.com/articles/what-is-model-context-protocol): The Model Context Protocol (MCP) is an open standard for connecting AI apps to tools and data. Learn its architecture, transports, tool calls, and security.
- [How to build an MCP server: a Python and TypeScript tutorial](https://theaiengineering.com/articles/how-to-build-an-mcp-server): Learn how to build an MCP server with the official Python and TypeScript SDKs: tools, resources, transports, testing, client config, and production security.
- [What is tool calling? How LLM function calling works](https://theaiengineering.com/articles/tool-calling): Tool calling lets an LLM request actions from your code through structured calls. Learn the request loop, parallel calls, structured outputs, security, and MCP.
- [A2A protocol vs MCP: differences and when to use each](https://theaiengineering.com/articles/a2a-vs-mcp): A2A protocol vs MCP: A2A connects AI agents to other agents, and MCP connects an agent to tools and data. Compare agent cards, tasks, transports, and security.

Part of the [Model Context Protocol](https://theaiengineering.com/topics/mcp) topic hub.

## Cite this guide

The AI Engineering Editors. "MCP vs API: what changes when an AI agent calls your service." The AI Engineering, updated Nov 18, 2026. https://theaiengineering.com/articles/mcp-vs-api

- Title: MCP vs API: what changes when an AI agent calls your service
- Author: The AI Engineering Editors
- Publisher: The AI Engineering
- Published: 2026-11-18
- Updated: 2026-11-18
- URL: https://theaiengineering.com/articles/mcp-vs-api
- Markdown: https://theaiengineering.com/articles/mcp-vs-api.md

To cite one section, link to its anchor:

- [What is the difference between MCP and an API?](https://theaiengineering.com/articles/mcp-vs-api#what-is-the-difference-between-mcp-and-an-api)
- [MCP vs API at a glance](https://theaiengineering.com/articles/mcp-vs-api#mcp-vs-api-at-a-glance)
- [Who decides to call: developer code or the model](https://theaiengineering.com/articles/mcp-vs-api#who-decides-to-call-developer-code-or-the-model)
- [The same operation shown both ways](https://theaiengineering.com/articles/mcp-vs-api#the-same-operation-shown-both-ways)
- [The two call paths, step by step](https://theaiengineering.com/articles/mcp-vs-api#the-two-call-paths-step-by-step)
- [MCP vs REST API: transport, sessions, and state](https://theaiengineering.com/articles/mcp-vs-api#mcp-vs-rest-api-transport-sessions-and-state)
- [Discovery and interface description: OpenAPI vs tools/list](https://theaiengineering.com/articles/mcp-vs-api#discovery-and-interface-description-openapi-vs-toolslist)
- [Primitives beyond tools](https://theaiengineering.com/articles/mcp-vs-api#primitives-beyond-tools)
- [Authentication and authorization](https://theaiengineering.com/articles/mcp-vs-api#authentication-and-authorization)
- [Errors and versioning](https://theaiengineering.com/articles/mcp-vs-api#errors-and-versioning)
- [Performance and context cost of tool definitions](https://theaiengineering.com/articles/mcp-vs-api#performance-and-context-cost-of-tool-definitions)
- [When to use an API, an MCP server, or both](https://theaiengineering.com/articles/mcp-vs-api#when-to-use-an-api-an-mcp-server-or-both)
- [Generating an MCP server from an OpenAPI spec](https://theaiengineering.com/articles/mcp-vs-api#generating-an-mcp-server-from-an-openapi-spec)
- [Security and governance for model-driven calls](https://theaiengineering.com/articles/mcp-vs-api#security-and-governance-for-model-driven-calls)
- [Where to go next](https://theaiengineering.com/articles/mcp-vs-api#where-to-go-next)
- [Frequently asked questions](https://theaiengineering.com/articles/mcp-vs-api#faq)
