mcpexplained
the reference

A guide to MCP

What each piece is, who calls it, and a demo you can run.

updated august 25, 2026spec 2025-06-188 runnable figures

who's whosessiontoolsresourcespromptssamplingelicitationrootsprogresstransports

agent · host server request resultevery figure runs · click things

Who's who

Five words the rest of this page leans on. The confusing one is host: it is simply the spec's formal name for the agent application itself.

  • agent · hostthe AI application you talk to: a chat app, an IDE, Claude. The spec says host; this page mostly says agent. Same thing.
  • clienta small piece inside the host that holds one connection to one server. Five servers, five clients, one host.
  • serverthe capability being plugged in: files, flights, a calendar. One job each, no knowledge of the others.
  • modelthe LLM inside the host. It only writes text; the host turns that text into real calls.
  • youthe person. Some hops park until you click.

The session

A session is the live connection between an agent and one server. Opening it is a handshake: each side lists what it can do, and that exchange defines everything allowed afterwards. Click connect to watch one open.

initializenotifications/initialized

  • opens withinitialize: protocol version and capabilities, both directions
  • the ruleuse nothing the other side didn't declare
  • shapeone session · one client · one server
Opening a session
no session
host · client
client declares
server
server declares
the pills are live: each one links to its concept below
on the wire · the handshake, trimmed
→ initialize
{ "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "sampling": {}, "elicitation": {}, "roots": {} },
    "clientInfo": { "name": "my-host", "version": "1.0" }
  } }

← result
{ "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": {}, "resources": { "subscribe": true }, "prompts": {} },
    "serverInfo": { "name": "notes", "version": "2.1" }
  } }

specspecification · 2025-06-18JSON-RPC 2.0 underneath, always

the serverthe capability you plug in

Tools

server

Tools are how a server lets the agent do things: search files, send an email, book a flight. The model decides a tool is needed, the host makes the call, and the result lands back in the conversation.

tools/listtools/call…/list_changed

  • isa function with a name and a JSON schema for its arguments
  • called bythe model; the host executes
  • effectsyes, they live here; approvals apply here first
  • discovertools/list is the whole universe; list_changed announces edits
Discover, then execute
host
files
tools unknown
call stays locked until the list exists: you can only call what discovery returned

specconcepts · tools

Resources

server

Resources are how a server shares things to read: files, tables, logs. Reading one changes nothing, which is why the host can pull them into context freely. Subscribing keeps your copy honest when the original moves on.

resources/listresources/readresources/subscribe

  • iscontent behind a URI: a file, a table, a log
  • chosen bythe host or the person, never the model
  • effectsnone, by definition; reading is always safe
  • freshsubscribe → updated → read again
A document and its copy
host
no copy yet
notes
report.md v1
without the subscription the host would keep trusting v1 forever

specconcepts · resources

Prompts

server

Prompts are canned requests a server offers the person: pick one, the server fills in the details, and a ready-to-send message appears. Think slash commands.

prompts/listprompts/get

  • isa named template the server fills into ready messages
  • invoked bythe person; slash-command material
  • returnsmessages with roles, not prose
  • notethe model picks tools, never prompts
A template, filled
host
notes
template
you picked it, the server filled the hole. the model was never asked

specconcepts · prompts

the agentthe host that runs them

Sampling

agent

Sampling lets a server borrow the agent's model for its own thinking: summarize this, classify that. The server hands over a question and gets an answer; it never touches the keys or your conversation.

sampling/createMessage

  • isthe server borrowing the model, through the host
  • hiddenkeys, model choice, your other context
  • host mayedit, refuse, or put it in front of you
  • shapeone request in, one completion back
A server borrowing the model
host · model inside
notes
notes wants the model to summarize a doc. allow it?
outcome
watch the ring while it runs: the model never leaves the host

specconcepts · sampling

Elicitation

agent

Sometimes a server needs the person to decide something mid job: which flight, which folder. Elicitation is that question, asked through the agent's own UI and answered with a click.

elicitation/create

  • isthe server asking the person a question
  • rendered bythe host's UI; server screens never cross
  • answerschema-validated; declining is a valid outcome
A question travelling upstream
host · your UI
flights
two flights match. which did you mean?
delivered
those buttons are the host's UI. the server only ever sees the answer

specconcepts · elicitation

Roots

agent

Roots are how the agent tells a server where it is welcome to work: these folders, this repo. A courtesy boundary the server should respect, not a lock.

roots/list…/list_changed

  • isthe host declaring where a server should operate
  • powerscoping, not enforcement; locks stay with the files
  • changeany time; a notification announces the new world
The server's visible world
host
files
~/projects~/finance ✕
every flip is a list_changed notification. the server was never asked for consent

specconcepts · roots

Progress · cancellation

Long jobs shouldn't go silent. Progress ticks in while the work runs, and a cancellation tells the other side to stop. Neither ever gets a reply.

notifications/progressnotifications/cancelled

  • tickprogress streams against a request's token
  • stopcancelled says stop caring; best effort
  • naturenotifications, both directions; no reply ever
Long work, kept honest
host
reports
each tick is a notifications/progress message. cancel and the last flight never arrives

specutilities · progress

Transports

The same messages can travel two ways: stdio when the agent starts the server on your machine, Streamable HTTP when the server lives somewhere else.

stdioStreamable HTTP

  • stdiothe host spawns the server locally; private, fast, no network
  • httpremote; POSTs up, optional SSE stream back down
  • sameidentical JSON-RPC either way; sessions live at this layer

specconcepts · transports

What is stable

  • stableeverything above · spec 2025-06-18
  • draftMCP Apps (SEP-1865): sandboxed UI, app-visible tools
  • draftTasks (SEP-2663): durable handles for long work
  • policywhen the roadmap moves, this page gets edited

References

fin · spec revisions welcome