MCP vs API: what's the difference?
MCP and an API solve different problems. An API is a fixed contract your code calls; you read the docs and write the integration. MCP is a protocol that lets an AI model discover a service's tools at run time and call them in one standard shape, so every MCP client can use the service without custom code.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
With an API, you read the reference, pick endpoints, write code that calls them and parse the responses yourself. The model never sees any of this.
With MCP, the client asks the server what it offers. tools/list returns each tool's name, a description written for the model, and a JSON Schema for its input.
The model reads those descriptions and picks a tool. The client sends tools/call with the arguments, and the result comes back as context for the model.
{"method":"tools/call","params":{"name":"publish","arguments":{...}}}The server does the real work, most often by calling the service's own API with the credentials the person signed in with.
Change an API and the code written against it has to change too. Change an MCP tool's description and the model reads the new one on its next tools/list.
Source: MCP docs: architecture overview
What MCP adds on top of an API
The comparison is slightly unfair, because MCP is built from the same parts. The protocol encodes its messages as JSON-RPC 2.0, and a remote MCP server answers HTTP POST requests at a single endpoint. If you squint, that is an API.
The difference is who reads the interface, and when. An API is designed for a programmer at build time. You read the reference, choose endpoints, and ship code that only ever makes the calls you wrote. MCP is designed for a model at run time. The client lists the server's tools, each with a description and an input schema, and the model chooses among them while it works. The MCP docs put the server's job as providing context to the client; what the model does with that context is left to the application.
That shift moves three things out of your code and into the protocol. Discovery: the client learns what exists by asking, not by reading docs. Shape: every call is tools/call with a name and JSON arguments, whatever the service does underneath. Portability: a server written once works in any MCP host, instead of one plugin per editor.
Example: Intraface's CLI and its MCP server
Intraface offers both shapes. Its command-line tool is ordinary code: you, or an agent that runs shell commands, tell it exactly what to do, pull this board, publish with this message, list the comments. Its MCP server offers the same operations as tools, with names such as pull_board, publish and list_comments, so an agent in Claude Code or Codex can decide on its own to pull the board, edit a file and publish. The board's version history does not care which door the change came through. The CLI is there when a program or a person is in charge of the steps; the MCP server is there for agents that need to find the tools themselves.
When to use the API and when to use MCP
Use the API when a program decides what happens: a nightly job, a deploy step, a backend that fetches a record on every request. It is cheaper, deterministic and easy to test. Use MCP when a model decides what happens: an agent that may or may not need to read a board, call a search, or file a ticket depending on the task.
The costs run in opposite directions. An API integration costs engineering time up front and nothing per call. An MCP tool costs nothing to integrate, but every tool description takes room in the model's context window, and every call is a round trip through the client. A server with eighty tools is harder for a model to use well than one with ten, which is why tool lists deserve the same editing as any API surface.
Common mistakes
- Exposing every endpoint as a tool. A model does not need the full REST surface. Offer the handful of actions an agent plausibly takes, with descriptions that say when to use each.
- Skipping the API because MCP exists. Scripts, CI and other services still need a contract they can call without a model in the loop.
- Treating tool descriptions as documentation. They are part of the interface. A vague description produces wrong calls as surely as a wrong URL does.
- Hard-coding tool names in client code. The point of tools/list is that the list can change. Read it.
FAQ
- Is MCP a replacement for a REST API?
- No. An MCP server almost always sits in front of an API and translates tool calls into API calls. The API remains the thing scripts, backends and the vendor's own apps use. MCP adds a layer models can discover on their own.
- Why not give the model the API docs instead of using MCP?
- You can, and for one-off scripts it works. But the model then writes HTTP calls by hand, handles auth itself and gets no schema validation. MCP gives it a typed tool list that every client understands, so one server serves Claude Code, Cursor, Codex and the rest.
- Is an MCP server itself an API?
- Technically yes. It speaks JSON-RPC 2.0, and a remote one is reached over HTTP. The difference is who the interface is designed for: an MCP server describes itself to a model at run time; an API describes itself to a programmer in documentation.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.