Reading the MCP spec is not the same as seeing the smallest thing that works. The spec tells you what is possible; it does not tell you which of the possible things is right, and the exam tests the second one. The design decisions only become visible when several minimal servers sit side by side and you can see what changes between them.
So: eight servers, each about 40–80 lines, each isolating exactly one decision. Every one runs.
All eight are smoke-tested against fastmcp 3.4.7 — the behaviours claimed on this page
were observed, not remembered.
Read them in order. 1–2 establish the primitives, 3–4 the failure and control patterns, 5–8 the ones that only show up at scale. Each card ends with the exam question shape it answers.
Before MCP, every integration was bespoke: your agent needed a GitHub connector, a Postgres connector, a Slack connector, each written against a different SDK, each re-written for the next agent you built. M agents × N systems = M×N integrations. MCP makes it M+N: every system exposes one MCP server, every agent speaks one MCP client. It is the USB-C analogy people reach for, and for once the analogy is accurate — it standardises the socket, not what flows through it.
The three parties. Getting these names right is worth an exam mark on its own, because the question usually turns on which one is doing the choosing:
┌──────────────────── HOST ────────────────────┐
│ Claude Code / Claude Desktop / your agent │ the application the
│ │ human is talking to
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ CLIENT │ │ CLIENT │ │ CLIENT │ │ one client per server,
│ └───┬────┘ └───┬────┘ └───┬────┘ │ 1:1, held by the host
└───────┼────────────┼────────────┼────────────┘
│ │ │ ← the MCP protocol (JSON-RPC 2.0)
┌────┴────┐ ┌────┴────┐ ┌────┴─────┐
│ SERVER │ │ SERVER │ │ SERVER │ your code: exposes tools,
│ (files) │ │ (git) │ │ (tickets)│ resources and prompts
└─────────┘ └─────────┘ └──────────┘
tool_use blocks back into MCP calls. MCP is a host-to-server protocol. Whether a tool
arrived via MCP or was hand-written in your code is invisible to the model — a distinction that
matters when a question asks "what does the model see?"Nearly every "should this be a tool or a resource?" question is answered by one axis: who initiates. Not what the data is — who chooses to bring it in.
| Primitive | Controlled by | Shape | In Claude Code |
|---|---|---|---|
| Tool | Model-controlled — the model decides to call it, mid-turn | A verb. Takes arguments, may have side effects. | Appears as mcp__server__tool |
| Resource | Application-controlled — the client/user decides to attach it | A noun at a URI. Read-only, no side effects. | Attached by @-mention |
| Prompt | User-controlled — the human picks it deliberately | A parameterised template the server supplies. | Appears as /mcp__server__prompt |
| stdio | HTTP (streamable) | |
|---|---|---|
| Runs | As a subprocess on your machine, launched by the host | As a remote service you connect to by URL |
| Talks over | stdin / stdout | HTTP POST, streaming responses via SSE |
| Auth | Environment variables — it is already your machine, your user | OAuth 2.1 / bearer tokens — it is a network boundary |
| Concurrency | One client per process | Many clients, one process |
| Use when | Local tools, local files, personal credentials | Shared/hosted servers, team-wide services |
Older material mentions a separate SSE transport; it has been folded
into streamable HTTP and is deprecated. Recognise the name, do not choose it.
1. initialize client → server protocol version + capabilities, both directions
2. initialized client → server handshake done
3. discovery client → server tools/list, resources/list, prompts/list
4. invocation client → server tools/call, resources/read, prompts/get
Discovery happens at connection time, which is the source of two behaviours worth remembering: a server you edit is not re-read until the client reconnects, and every connected server's full tool list is loaded into the context window before the conversation starts. That second one is the hidden cost in skeleton 8.
That is the whole conceptual base. Everything below is one decision on top of it.
The starting shape. Two tools, no resources, no prompts, no state.
@mcp.tool
def get_order(order_id: str) -> dict:
"""Retrieve the full record for ONE order, given its exact order ID.
Order IDs look like "A-1001". If you only have a customer's email, call
search_orders first to obtain the ID — this tool cannot look up by email.
"""
name, description, inputSchema. Anything you need it to get
right has to live in those three. The docstring above does four things a weak one does not: says
when to use it, says what it does not do, points at the companion tool, and shows
the argument's shape. Compare: """Gets an order.""" — and notice that no amount of
prompt engineering upstream recovers what that one omits.The same policy catalogue, exposed both ways in one file so the boundary is visible rather than described.
@mcp.resource("policy://index") # static — one fixed address
def policy_index() -> str: ...
@mcp.resource("policy://{topic}") # template — a family of addresses
def policy_doc(topic: str) -> str: ...
@mcp.tool # same data, model-controlled, searchable
def search_policies(query: str) -> list[str]: ...
{topic} placeholder makes the second one a template, listed separately
from static resources: a family of addresses, not one address.@-mention; some clients ignore resources entirely and see
only your tools. A capability exposed only as a resource is invisible on those clients —
which is why servers that must work everywhere expose both, exactly as this one does.An error string is not an error contract. "Request failed" tells the agent nothing about whether to retry, fix its arguments, give up, or escalate — so it guesses.
def fail(category, retryable, message, next_step) -> dict:
return {"isError": True, "errorCategory": category,
"isRetryable": retryable, "message": message, "nextStep": next_step}
# already refunded → business, retryable=False → stop, explain
# amount too large → validation, retryable=True → fix the argument, retry
# gateway down → transient, retryable=True → back off, retry identical call
# not your order → permission, retryable=False → escalate to a human
nextStep earns its place. Without the categories the classic failure is an infinite
retry loop against a permanent error; the mirror-image failure is giving up on a 503 that would
have succeeded one second later.isError flag. The two are
not interchangeable, and raising the wrong exception type leaks:
raise ToolError("The payment gateway is unavailable")
→ model sees exactly that text. safe: you wrote it
raise ValueError("conn refused: pg://admin:hunter2@10.0.0.4")
→ model sees "Error calling tool 'x': conn refused: pg://admin:hunter2@…"
an internal DSN, password and all
Observed on fastmcp 3.4.7, not assumed. The rule:
catch your exceptions and re-raise as ToolError with a message you chose, or return a
structured failure. A raw stack-trace message reaching the model is both a context leak and a
security leak.
A side-effecting tool refuses to run until a prerequisite tool has been called in this session.
_verified: set[str] = set() # session state lives in the SERVER
@mcp.tool
def process_refund(email, order_id, amount) -> dict:
if email not in _verified:
return {"isError": True, "errorCategory": "business", "isRetryable": True,
"message": f"Identity for {email} has not been verified.",
"nextStep": f"Call get_customer with email='{email}', then retry."}
...
isRetryable: true, but only after a different call: that is what
nextStep is for, and it lets a capable agent self-correct in one hop instead of
surfacing a dead end to the user.set is correct on stdio — one process, one client — and
becomes a cross-user vulnerability the moment the transport changes, leaking one user's
verification into another user's session. Key it by session ID on HTTP.Salesforce, Zendesk and a legacy database disagree about field names, date formats, status vocabularies and ID shapes. One tool hides all of it.
"CreatedDate": "2026-08-19T09:14:00.000+0000" ┐
"created_at": "2026-08-20T11:02:00Z" ├─→ "createdDate": "2026-08-21"
"CREATED": "20260821" ┘
"Working" / "open" / "P" ─────────────────────→ "status": "in_progress"
Id "500xx1" / id 88231 / TICKET_NO 4471 ────────→ "id": "sf:500xx1" | "zd:88231"
source is kept, because
normalising is not the same as hiding — the model may need to say "that one is in the read-only
legacy system."closed destroys information. Keep a sourceStatus alongside when
the vocabularies do not truly align.A tool result enters the context window and stays there for the rest of the conversation. Fifty thousand rows do not cost you once — they crowd out everything the agent still needs, on every subsequent turn.
size = min(limit, _MAX_LIMIT) # ← the caller CANNOT raise the ceiling
return {"rows": page,
"totalCount": len(matches), # what exists
"nextCursor": str(end) or None, # how to continue
"truncated": end < len(matches)} # what you have NOT seen
@mcp.tool
def summarise_logs(query) -> dict: # counts and buckets, returns no rows
The server reads credentials from the environment; the .mcp.json that launches it
references ${API_TOKEN}, never the value.
{"mcpServers": {"configured-api": {
"command": "python", "args": ["skeletons/07_env_config.py"],
"env": {"API_TOKEN": "${API_TOKEN}",
"API_BASE": "${API_BASE:-https://api.example.com}"}}}}
The committed file holds the wiring; every developer supplies their own value. The three config scopes, narrowest first:
| Scope | Reaches | Committed? | Secrets? |
|---|---|---|---|
local | This project, this machine | No | Acceptable |
project | .mcp.json at the repo root, whole team |
Yes | Never — use ${VAR} |
user | All your projects, this machine | No | Personal tokens |
whoami returns a fingerprint — dem…yz (14 chars)
— never the token: enough to debug "did it load the right key", useless to anyone reading a log.~/.zshrc, so the variable is set in your
terminal and empty in the server. (3) Config is logged at startup.${VAR} for the value.Both a docs server and a tickets server expose search. This file defines both, so
the collision is visible in one place.
mcp__docs__search "Search internal ENGINEERING DOCUMENTATION — architecture
notes, runbooks… Do NOT use for customer conversations."
mcp__tickets__search "Search CUSTOMER SUPPORT TICKETS — conversations with
customers… Do NOT use for internal documentation."
| Skeleton | Domain 2 cluster | The question shape it answers |
|---|---|---|
| 1 · Tools-only | 2 · Designing tools | "The agent picks the wrong tool" |
| 2 · Resources | 6 · MCP primitives | "Tool or resource?" |
| 3 · Structured errors | 3 · Results & errors | "It retried 20 times" / "it gave up too early" |
| 4 · Gated / stateful | 7 · Building servers | "Ensure identity is verified before the refund" |
| 5 · Heterogeneous | 2 · Designing tools | "Three systems, different formats" |
| 6 · Pagination | 3 · Large results | "50,000 rows blew the context window" |
| 7 · Env config | 8 · MCP security | "Each developer has their own key" |
| 8 · Namespacing | 2 · Overlap · 5 · Fundamentals | "Two servers, similar tools" |
When you have read all eight, sit the Domain 2 quiz bank — sets 5 to 8 are the MCP ones. The bar is not picking the right option; it is being able to say why each distractor fails. Most MCP distractors are plausible because they solve the problem in the wrong place — in the prompt instead of the server, in the model instead of the contract.
cd CCA-F/D2-MCP-Skeletons/skeletons
pip install fastmcp
python test_skeletons.py # exercises all eight in-process, no network
python 01_tools_only.py # or run one as a real stdio server
To wire one into Claude Code, copy
mcp.json.example to .mcp.json at a repo root
and reconnect. Discovery happens at connection time — edits to a running server are not picked up
until then.
A hands-on lab built on these same servers — wire them up, break them deliberately, watch the agent react — is the planned follow-on to this page.