MCP_vs_API
Skip to the simulators
rev 2.0 · spec sheetREST / JSONJSON-RPC 2.0

APIs connect code.
MCP connects models.

A standard API is a fixed request to an endpoint you already know. The Model Context Protocol gives a language model a standard way to discover tools and call them at runtime. This is the blueprint - poke every part of it.

Run the simulatorsOpen the terminals
01Direct callfetch(/api/weather) → JSON. You wrote the URL.
02Discovered toolstools/list returns what the server can do, live.
03Model decidesThe LLM picks a tool and fills the arguments.
§ 01

Flow simulators

Watch a request travel. Same goal, two paths.

Press the buttons. Left: a plain HTTP call goes straight to a known endpoint. Right: an MCP exchange where a model handshakes, lists tools, then calls one - over JSON-RPC.

Standard API

REST over HTTPS · stateless

idle
App
Server

hardcoded endpoint · the app already knows the address

Request

const res = await fetch(  "https://api.example.com/api/weather?city=Lisbon");const data = await res.json();

Response 

{  "city": "Lisbon",  "tempC": 22,  "condition": "Sunny",  "humidity": 0.41}
console

› ready · press send request

Model Context Protocol

JSON-RPC 2.0 · Stdio / SSE · stateful

idle
LLM
MCP Client
MCP Server
reasonshost apptools live here

Prompt

Synthesized answer

The model answers here once the tool returns.

handshake
tools/list
tools/call
answer
console

› ready · pick a prompt and ask

§ 02

Comparison matrix

Where they actually differ. Tap a row to expand.

Six dimensions, side by side. MCP doesn't replace APIs - it sits a layer up and gives a model a standard way to reach them.

API · Read the docs, hardcode the routeMCP · tools/list returns capabilities at runtime

With an API you find endpoints by reading documentation and baking the URL into your code. An MCP client asks the server what it can do during the session, so new tools appear without a code change.

API · None - the model can't call it directlyMCP · First-class - the model is the caller

A REST API has no concept of a language model. MCP is built so an LLM can read tool schemas, decide what to call, and receive structured results back into its context.

API · Bespoke per service (paths, verbs, shapes)MCP · One uniform JSON-RPC 2.0 envelope

Every API invents its own routes and payloads. MCP standardizes the envelope: the same method/params/result structure works across every server.

API · Stateless request/responseMCP · Stateful session after a handshake

HTTP calls are independent. MCP opens a connection, negotiates capabilities once with initialize, then reuses that session for many messages.

API · Versioned endpoints, client updatesMCP · listChanged notifications, live refresh

When an API changes you usually ship a new version and update clients. An MCP server can notify the client that its tool list changed, and the client refetches.

API · Two systems with a fixed contractMCP · A model that needs many tools, safely

Reach for an API when both ends are known software talking a stable contract. Reach for MCP when you want a model to use a growing set of tools through one protocol.

§ 03

Terminal playgrounds

Run the commands. Output streams in, highlighted.

Pick a command and send it. The API terminal speaks REST/JSON; the MCP terminal speaks JSON-RPC 2.0. Notice the API has no way to ask what's available - MCP does.

mcp-session - jsonrpc

mcp › pick a command below, then press send

mcp ›{"jsonrpc":"2.0","id":1,"method":"initialize"}
§ 04

Discovery, as a game

Finding tools the hard way vs. plugging in.

The core difference made playable. With an API you have to already know which door opens. With MCP, you plug in once and the tools announce themselves.

Door Discovery

API · you must know the endpoint

manual

One of these endpoints exists. The server won't tell you which. Knock until you guess right.

0 wrong guesses · keep knocking

MCP Plug & Play

MCP · tools announce themselves

auto

Plug the model into the server once. It discovers every tool, resource, and prompt on its own.

LLMServer
????????tool
????????tool
????????resource
????????prompt
§ 05

Architecture & protocol

Two stacks, top to bottom. Hover a layer.

An API is a fixed contract your code calls over HTTP. MCP is a session: a uniform JSON-RPC protocol over a chosen transport, with a model driving it.

A standard API

request / response
  1. 05Caller
    Your code, written ahead of time
  2. 04Contract
    OpenAPI / hardcoded routes
  3. 03Payload
    JSON, any shape you design
  4. 02Style
    REST or GraphQL
  5. 01Transport
    HTTP / HTTPS

The Model Context Protocol

session
  1. 05Caller
    An LLM that discovers + decides at runtime
  2. 04Capabilities
    Tools · Resources · Prompts
  3. 03Architecture
    Client ↔ Server, stateful session
  4. 02Protocol
    JSON-RPC 2.0 messages
  5. 01Transport
    Stdio · SSE / Streamable HTTP

What an MCP server actually offers

three pillars
§ 06

The one-line version

APIs are how software talks. MCP is how models reach that software.

MCP doesn't replace APIs - it sits a layer up, giving a model a standard way to discover and call them. Often an MCP tool is just a thin wrapper around a normal API.

Reach for an API

  • Two systems with a known, stable contract
  • You control both ends, or read the docs
  • Stateless calls, predictable shapes

Reach for MCP

  • A model needs to use many tools, safely
  • Tools should be discoverable at runtime
  • One uniform protocol across every server

Built as a single blueprint about a protocol. Press the simulators again - the order of those JSON-RPC calls is the whole idea.