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

Comparison · MCP

MCP and APIs are not alternatives. An API is the interface a service offers to programs, and the Model Context Protocol (MCP) is a standard way for AI applications to discover and call capabilities at runtime, usually through an 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.

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 (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.

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. AI applicationsYour serviceBackend codeCalls known endpointsAI hostModel + MCP clientAnother AI hostSame server, no glue codeMCP servertools/list, tools/callSchemas written for modelsREST APISystem of recordGraphQL APISystem of recordDatabaseInternal dataHTTPS + API keyJSON-RPCJSON-RPC
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.

MCP adds what a model needs and a developer does not: runtime discovery, descriptions written for a model, 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: 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; 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 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 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 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 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:

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:

{
  "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:

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.

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. ModelProvider APIYour appCode or MCP hostMCP serverWraps the APIREST APISystem of record1GET /repos/.../issues2200 OK, JSON3tools/list4tool definitions5prompt + tool list6call list_issues7approve, tools/call8API call, own token9API response10content, isError11result into context12final answer
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.

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 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:

  • 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 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, 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 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 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 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 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 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; 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 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 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. 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, 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 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 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 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; a description changed after approval is a form of 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 applies these controls once for many servers. Bifrost, 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 covers the gateway pattern for model and tool traffic, and the MCP platforms directory 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; for the protocol that connects agents to other agents rather than to tools, read A2A vs MCP. The MCP topic hub 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

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
Updated
View as Markdown

The AI Engineering Editors ·