CCA-F › Domain 2 › MCP Skeletons

MCP Skeletons

Eight bare-minimum servers, one per design pattern · Tool Design & MCP, 18% of the exam · ~45 minutes to read

Why this section exists

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.

8 skeletons Python · FastMCP Runnable & tested Objectives 4.5 – 4.8

First, the mental model

MCP is a port, not a feature

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
      └─────────┘  └─────────┘  └──────────┘
The bit that catches people: the model is not in this picture. The model never speaks MCP. The host collects the tool lists from its clients, hands them to the model as ordinary tool definitions in the Messages API, and translates the model's 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?"

The three primitives, sorted by who decides

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.

PrimitiveControlled byShapeIn 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
The trap: "read-only, so it must be a resource." Not quite. Read-only is necessary, not sufficient. A read-only operation that needs searching — arguments, a decision, a query the model composes — is still a tool, because a resource URI cannot express a search. Skeleton 2 shows the same catalogue exposed both ways, side by side, so the boundary stops being abstract.

Transports: the only two you need

stdioHTTP (streamable)
RunsAs a subprocess on your machine, launched by the host As a remote service you connect to by URL
Talks overstdin / stdoutHTTP POST, streaming responses via SSE
AuthEnvironment variables — it is already your machine, your user OAuth 2.1 / bearer tokens — it is a network boundary
ConcurrencyOne client per processMany clients, one process
Use whenLocal tools, local files, personal credentials Shared/hosted servers, team-wide services
Why this is not trivia: the transport decides whether server-side state is safe. A module-level dict is a perfectly good session store on stdio (one process serves one client) and a cross-user data leak over HTTP (one process serves everybody). Skeleton 4 is built on exactly that fault line, and the scenario questions love it — they give you a working stdio design and then say "now 500 users share it."

Older material mentions a separate SSE transport; it has been folded into streamable HTTP and is deprecated. Recognise the name, do not choose it.

The lifecycle, in four beats

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 eight skeletons

Skeleton 01 · the baseline

Tools-only server

Pattern: capabilities as tools, nothing else ~80% of real servers

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.
    """
What it exposes: the description is the selection mechanism. The model never sees your source, your function body, or your intent — only three fields: 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.
Exam shape: "The agent calls the wrong tool / never calls the tool / passes the wrong arguments." The fix is the description, not the code. Write it for a competent new hire who can see the signature but has never seen the system.
Skeleton 02 · the boundary

Resources server

Pattern: content catalogue addressed by URI Tool vs resource

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]: ...
What it exposes: the decision is about control, not about data. Known address, client attaches it → resource. Needs searching, arguments, or a judgement → tool. Changes state, sends, charges, deletes → tool, always. Note the {topic} placeholder makes the second one a template, listed separately from static resources: a family of addresses, not one address.
The practical caveat: resource support is client-dependent. Claude Code surfaces MCP resources via @-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.
Exam shape: "Should this be a tool or a resource?" Ask who chooses, and whether it changes anything.
Skeleton 03 · the one that changes agent behaviour most

Structured-error server

Pattern: every failure carries category + retryability

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
What it exposes: four categories cover almost everything, and the difference between them is what the agent should do next — which is why 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.
Returned vs raised — two different mechanisms, and a verified finding. Returning a dict means the call succeeded at the protocol level and the payload describes a business failure. Raising sets the protocol-level 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.

Exam shape: "The agent retried a failing tool 20 times." / "The agent gave up on a request that would have succeeded."
Skeleton 04 · prose is not a control

Gated / stateful server

Pattern: prerequisite enforced server-side get_customer → process_refund

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."}
    ...
What it exposes: you cannot enforce ordering with prose. Writing "always call get_customer first" in a description is a request; the model complies most of the time — which is the worst possible rate for something that moves money. The server is the only place ordering can actually be enforced. Note also that this failure is unusually 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.
The follow-up question you should expect: "now it runs over HTTP for 500 users." The module-level 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.
Exam shape: "How do you ensure the agent verifies identity before refunding?" → gate it server-side; the description is documentation, not a control.
Skeleton 05 · where mapping belongs

Heterogeneous-backend server

Pattern: three upstreams, one contract

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"
What it exposes: normalising in the server costs 30 lines once. Normalising in the model costs tokens on every call, forever — three schemas to hold, three status vocabularies to reconcile, cross-system comparisons done in prose — and it is only probably right. Two details carry weight: IDs are prefixed so they round-trip to the correct upstream and never collide, and 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."
The limit of the pattern: normalise the shape, never the meaning. If Zendesk's "solved" and Salesforce's "Closed" carry genuinely different business meaning, collapsing both to closed destroys information. Keep a sourceStatus alongside when the vocabularies do not truly align.
Exam shape: "Three CRMs with different formats — how should the MCP server expose them?" → one tool, one normalised contract, mapping in the server. Not three tools.
Skeleton 06 · the context window is the scarce resource

Paginated / large-result server

Pattern: bounded pages, cursor, total

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
What it exposes: four moves, in priority order. Clamp — if the ceiling is a parameter the model can set, it is not a ceiling; this is the one that actually saves you. Signal — silent truncation is the real hazard, the agent confidently reporting "3 errors" when there were 300 and it saw one page. Continue — an opaque cursor it just passes back. Aggregate — the best large result is the one you never return.
Exam shape: "The tool returns 50,000 rows and the agent runs out of context." → cap server-side, paginate, and offer a summarise tool. The model cannot impose the bound; by the time it sees the result, the damage is done.
Skeleton 07 · secrets and scope

Env-var-config server

Pattern: ${VAR} expansion, nothing committed

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:

ScopeReachesCommitted?Secrets?
localThis project, this machineNoAcceptable
project.mcp.json at the repo root, whole team YesNever — use ${VAR}
userAll your projects, this machineNoPersonal tokens
What it exposes: the server fails loudly at startup if the token is missing, rather than starting happily and failing later as a confusing error inside the model's transcript. And 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.
Three things that go wrong. (1) The token is pasted in literally "just to test it" and reaches git — rotate it, because a secret in git history stays leaked after the fix commit. (2) The server inherits your interactive shell's environment until it does not: a GUI-launched client may never source your ~/.zshrc, so the variable is set in your terminal and empty in the server. (3) Config is logged at startup.
Exam shape: "The team needs the same MCP server, but each developer has their own API key." → project scope for the wiring, ${VAR} for the value.
Skeleton 08 · when servers collide

Namespacing & collision

Pattern: two servers, one tool name

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."
What it exposes: the client namespaces tool names by server, so the wire-level clash is handled for you — the model cannot literally call the wrong name. But it still has to choose, and descriptions are not namespaced. If both say "Search for information", the prefix was cosmetic and the model picks by coin-flip. Three moves actually disambiguate: lead with the domain in the first words, state the negative ("Do NOT use for X — that is the Y server"), and give trigger phrases matching how a user will really ask.
The real answer, and the one people miss: every connected server's full tool list sits in the context window on every request. Ten servers × eight tools is eighty descriptions re-read each turn — tokens, latency, and more chances to choose wrong. The strongest fix for tool confusion is usually not better descriptions at all. It is connecting fewer servers.
Exam shape: "Two MCP servers expose similar tools and the agent picks the wrong one." → disambiguate the descriptions; renaming alone does not fix selection.

What this maps to on the exam

SkeletonDomain 2 clusterThe question shape it answers
1 · Tools-only2 · Designing tools"The agent picks the wrong tool"
2 · Resources6 · MCP primitives"Tool or resource?"
3 · Structured errors3 · Results & errors"It retried 20 times" / "it gave up too early"
4 · Gated / stateful7 · Building servers"Ensure identity is verified before the refund"
5 · Heterogeneous2 · Designing tools"Three systems, different formats"
6 · Pagination3 · Large results"50,000 rows blew the context window"
7 · Env config8 · MCP security"Each developer has their own key"
8 · Namespacing2 · 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.

Running them

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.