MCP: advanced topics

1 · Beyond tools — the full protocol essential

Here's the mental jump most people never make. The first time you meet MCP, you learn it as "a way to give the model tools" — a function the model can call, like a fancy plugin. That framing is true but small, and it quietly caps how good your servers ever get. The people who ship MCP servers a whole org depends on made one realization: MCP isn't a plugin format, it's a protocol — a two-way conversation between a client and a server. Once you see it that way, a pile of "advanced" features stop looking like a grab-bag and start looking like the obvious consequences of a real connection.

An analogy: think of the difference between a vending machine and a phone call. A vending machine is one-directional — you press a button, it drops a snack, conversation over. That's the "MCP is just tools" picture: the client pokes the server, the server hands something back. A phone call is different — either side can speak, ask a question, or say "hold on, something changed." That's what MCP actually is. The server can call back to the client's model (sampling), it can interrupt to ask the user a question (elicitation), it can tap the client on the shoulder to say "your data is stale" (notifications), and the client can hand the server a fenced-off patch of the filesystem to work in (roots). None of that fits in a vending machine.

The common mistake is to build every server as a lonely bag of tools and then reach for hacks when you need the missing pieces — a server that ships its own API key so it can call an LLM (now you have a second key to secure and a second bill to watch), or one that makes the user re-run a command because it had no way to ask a mid-task question. Every one of those hacks is a feature MCP already gives you, done properly, with the client staying in charge of trust and cost. So this chapter isn't "six unrelated add-ons." It's the rest of the protocol you already started using — the capabilities that turn a toy server into shared infrastructure. It's worth learning because the ceiling on what an agent can safely do is set by how rich and how well-governed its server connections are.

In C4 you built an MCP server exposing tools, resources, and prompts. Production MCP adds four capabilities that make servers interactive and composable: sampling, notifications, elicitation, and roots — over a real transport.

2 · Sampling — the server asks the model essential

Picture a server that wants to be smart. Say you're writing a server that summarizes files, or drafts a commit message, or classifies a support ticket — all jobs that need an LLM. The naive path is obvious and tempting: give the server its own API key, let it call the model directly, done. And it works on your laptop. Then you try to share the server with your team and the cracks appear: now every server has its own key to rotate and leak, its own bill nobody's watching, its own model choice that might not match what the user wants, and — worst of all — its own way to quietly burn tokens with no one approving the spend. You've scattered trust and cost across a dozen little programs.

Sampling is the protocol's answer, and the trick is that it turns the connection around. Instead of the client always calling the server, the server calls back to the client and says "please run the model on this prompt for me." The client — which already owns the model, the key, the budget, and the user's trust — runs it and hands the completion back. The server got all the LLM power it wanted and holds none of the keys.

The analogy that makes it click: sampling is a server asking to borrow the client's phone rather than buying its own. You don't hand a contractor your credit card and let them make calls on any line they like; you let them use your phone, in front of you, so you see every call and can hang up. The client is that single point of control — one place that approves requests, enforces rate limits, picks the model, and pays the bill. One key, one budget, one approval prompt, no matter how many servers are connected.

The mistake to avoid is thinking sampling is just a convenience for keyless servers. Its real value is governance: it collapses N scattered trust-and-billing decisions into one. That's why a security-minded team will insist their servers use sampling instead of embedded keys — not because it's easier, but because there's exactly one throat to choke when spend or safety goes wrong. In the SDK this is a single call, ctx.session.create_message(...), which the lab shows next. Normally the client calls the server's tools. Sampling reverses it: the server asks the client's model for a completion — so a server can use the LLM without its own key, and the client keeps control of model, cost, and approval.

sampling_server.pyfrom mcp.server.fastmcp import FastMCP, Context

mcp = FastMCP("summarizer")

@mcp.tool()
async def summarize_file(path: str, ctx: Context) -> str:
    """Summarize a file by asking the CLIENT's model (sampling)."""
    text = open(path).read()[:4000]
    result = await ctx.session.create_message(
        messages=[{"role": "user",
                   "content": {"type": "text", "text": f"Summarize:\n{text}"}}],
        max_tokens=200)
    return result.content.text

3 · Notifications & elicitation intermediate

Imagine an agent that never gets told anything changed. Its MCP server just added three new documents, but the client still shows the old list — because nothing told it to look again. So the client does the only thing it can: it asks, over and over, "anything new? anything new? anything new?" That's polling, and it's the software equivalent of a kid in the back seat asking "are we there yet?" every thirty seconds. It wastes traffic, it's always either too slow (you asked a minute ago) or too chatty (you're asking constantly), and it scales terribly once many clients are all nagging the same server.

Notifications flip that around. Instead of the client asking, the server tells — a one-way message that says "the resource list changed, refresh yourself" with no reply expected. Think of it as the difference between refreshing a webpage every few seconds versus a live feed that pushes new posts to you the moment they arrive. The server fires the message and moves on; the client updates itself when it's ready. Because nobody's waiting on a round-trip, it's cheap and it's instant.

Elicitation is the mirror image, and the distinction between the two is the whole point of this section — get it wrong and your server either hangs or silently guesses. Elicitation is when the server needs an answer it genuinely can't figure out on its own: "which environment — staging or prod?" It routes that question through the client to the human, waits for the reply, and continues. The one-line test that separates them: does the server expect a reply? If no — it's just informing you — that's a notification (fire-and-forget). If yes — it's stuck until a human answers — that's elicitation (a paused conversation). The common trap is reaching for a tool argument when you should elicit: forcing the caller to know the deploy target up front, instead of letting the server ask at the exact moment it matters and keeping the human in the loop for the choice that needs judgment.

Notifications are one-way messages ("the resource list changed") so the client refreshes without polling. Elicitation lets a server ask the user for input mid-task through the client's UI.

notify.pyfrom mcp.server.fastmcp import FastMCP, Context
mcp = FastMCP("docs")
def save_document(name, body): ...              # your storage

@mcp.tool()
async def add_document(name: str, body: str, ctx: Context) -> str:
    save_document(name, body)
    await ctx.session.send_resource_list_changed()   # client cache is now stale
    return f"added {name}"

4 · Transports — stdio vs HTTP intermediate

Everything so far has been about what the client and server say. This section is about the wire the words travel down. A transport is the physical connection — the pipe — and MCP gives you two. It's easy to skate past this as a boring plumbing detail, but the transport you pick quietly decides how your server is deployed, who can reach it, and how much security you're now on the hook for. Choosing it is a real architectural decision wearing plumbing's clothes.

The two options map onto a distinction you already understand from everyday computing. stdio ("standard in / standard out") is like a program you run on your own machine — the client launches the server as a subprocess and talks to it through the same input/output channels a terminal uses. There's no network, no port, no address. It's the simplest thing that works, and it's how most desktop tools connect: one client, one local server, sitting right next to each other. Streamable HTTP is the other extreme: the server runs as a networked service at a URL, and any number of clients can reach it over the network — exactly like a web API.

The analogy: stdio is talking to someone in the same room — no phone needed, no way for a stranger to eavesdrop, but they have to be physically present. HTTP is a phone line — now people anywhere can reach the server, which is powerful, but you've also opened a door the whole world can knock on. And that's the trade the section turns on: HTTP buys you reach and sharing, but the moment you go networked you inherit everything that comes with running a public service — authentication, so not just anyone can call it; TLS, so the traffic isn't sniffed; rate limiting and hardening, so it can't be hammered. stdio has none of that surface because there's no network to attack.

The common mistake is defaulting to HTTP because it sounds more "production." It isn't — it's more exposed. The right instinct is the reverse: reach for stdio unless you specifically need remote access or multiple clients, because the safest network surface is the one that doesn't exist. Only step up to HTTP when the requirement forces it, and then treat it like any other service you'd expose to a network. The lab below shows how the same server code runs either way, chosen by a single flag — proof that the transport is a deployment choice, not a rewrite.

A server speaks over a transport. stdio is a local subprocess the client launches — simplest, common for desktop tools. Streamable HTTP runs it as a networked service — for remote/shared, multi-client servers.

run_server.pyfrom mcp.server.fastmcp import FastMCP
mcp = FastMCP("docs")            # tools registered above

if __name__ == "__main__":
    import sys
    mcp.run(transport="streamable-http" if "--http" in sys.argv else "stdio")

5 · Advanced — roots & the request lifecycle advanced

Here's a scenario that should make you a little nervous. You connect a filesystem MCP server so your agent can read and edit your project. Handy. But that server is a program running on your machine, and the model is deciding which paths it opens. What stops it — or a cleverly crafted request, or an outright buggy tool — from reading ~/.ssh/id_rsa, or your browser cookies, or /etc/passwd? Nothing, unless something draws a line. Roots are that line: the client tells the server "you may operate inside these directories and nowhere else," and it's the server's job to honor it on every single file access.

Think of roots like a visitor badge that only opens certain doors. A contractor in an office building isn't trusted to roam everywhere; their badge works on floor 3 and the doors slam shut everywhere else. Roots are that badge for the filesystem. The client grants a scope (the project folder), and the server must check every path against it before touching disk — the same way the badge reader checks before the door clicks open.

Now the part that traps people, and it's a genuine security bug when they get it wrong. The obvious check is "does this path start with the allowed folder?" — a simple string comparison. It's also broken, because a path can lie. /home/user/project/../secrets.txt starts with /home/user/project, so a naive string check waves it through — but that ../ means "go up a level," and the file it actually reaches is /home/user/secrets.txt, outside the root. That's a path-traversal escape, one of the oldest tricks in the book, and it works against anyone who checks the text the user typed instead of the place it truly points.

The fix is one function: resolve the path to its real, canonical location first — os.path.realpath collapses the ../ and follows any symlinks — and only then compare against the allowed roots. You check the destination, not the label. That single discipline (normalize before you compare) is the beating heart of nearly every filesystem-security check you'll ever write, well beyond MCP. The lab below is a runnable model of exactly that boundary — legitimate paths pass, escapes get blocked. Roots let the client tell the server which directories it may operate in — a security boundary for filesystem servers. Model the access check the server should enforce.

roots.pyimport os

def within_roots(path, roots):
    """Only allow access inside client-granted roots (prevents path escape)."""
    real = os.path.realpath(path)
    return any(real.startswith(os.path.realpath(r) + os.sep) or real == os.path.realpath(r)
               for r in roots)

roots = ["/home/user/project"]
for p in ["/home/user/project/src/app.py",
          "/home/user/project/../secrets.txt",   # path-escape attempt
          "/etc/passwd"]:
    print(f"{within_roots(p, roots)!s:5}  {p}")

True   /home/user/project/src/app.py
False  /home/user/project/../secrets.txt
False  /etc/passwd

6 · Professional — errors, timeouts & robustness professional

The gap between a demo server and a production one is almost never the happy path — it's what happens when things go wrong. Your tool works perfectly when it's handed the input you imagined. Then a real client sends a number where you expected text, or the database it queries is down, or the operation that usually takes 200ms hits a slow disk and takes forever. On a demo, you shrug and re-run. In production, a tool that throws an unhandled exception or hangs doesn't just fail itself — it can wedge the whole agent that's waiting on it. One stuck server, one frozen conversation.

The habit that fixes this is to treat your tool like a well-trained receptionist rather than a nervous intern. Hand an intern a request they can't handle and they freeze, or blurt out a confusing error, or just disappear. A good receptionist always comes back with a composed answer — "done, here's the result," or "I couldn't do that, and here's exactly why" — but never leaves you standing there or panicking. Every call gets a clean, predictable response. That's the discipline: your tool should catch its own failures and return a tidy, uniform result whether it succeeded or not, so the caller can always keep working.

Two failure modes deserve special naming because beginners handle them worst. The first is bad input — the wrong type, a missing field, a nonsensical value — which should produce a clear error naming what was wrong, not a raw stack trace. The second, and the sneakier one, is the slow operation that never finishes: without a timeout, a single wedged call blocks forever, and "forever" is the one duration a user will never forgive. A hard timeout converts an infinite hang into a fast, honest failure the agent can recover from — retry it, route around it, or tell the user. The common mistake is optimism: assuming inputs are valid and operations are quick, so no guards are needed. Production is precisely the place that assumption dies. The lab below wraps any tool so every outcome — success, bad input, timeout — comes back as the same shaped dictionary, which is the small, boring pattern that keeps a client alive. This is the same resiliency discipline you'd give any real service (DF4). A production MCP server handles bad input, times out slow operations, and returns clear errors rather than hanging the client. Same resiliency discipline as any service (DF4).

robust_tool.pydef safe_tool(fn, *args, timeout_hit=False):
    """Wrap a tool call: validate, guard, return a clean result or error."""
    try:
        if timeout_hit:
            raise TimeoutError("operation exceeded 10s")
        return {"ok": True, "result": fn(*args)}
    except TimeoutError as e:
        return {"ok": False, "error": f"timeout: {e}"}
    except Exception as e:
        return {"ok": False, "error": f"{type(e).__name__}: {e}"}

print(safe_tool(lambda x: x.upper(), "hello"))
print(safe_tool(lambda x: x.upper(), 42))                 # int has no .upper
print(safe_tool(lambda x: x, "x", timeout_hit=True))

{'ok': True, 'result': 'HELLO'}
{'ok': False, 'error': "AttributeError: 'int' object has no attribute 'upper'"}
{'ok': False, 'error': 'timeout: operation exceeded 10s'}

7 · Tech-lead — MCP servers as shared infrastructure tech-lead

Everything up to here has been about building one good server. This section is about what changes when other people start depending on it. That shift — from "my handy script" to "the thing five teams' agents now call" — is where the tech-lead mindset kicks in, and it reframes an MCP server as something bigger than code: it becomes infrastructure. The leverage is enormous. Build one solid server that wraps your ticket system or your deploy logs, and every agent and every teammate in the org gains that capability with a single config line. You wrote it once; the whole company got smarter.

The analogy that captures both the upside and the responsibility: a shared MCP server is like the office electrical wiring, not a desk lamp. A lamp is yours — if it flickers, you deal with it. Wiring is everyone's — if it fails, the whole floor goes dark, and if it's unsafe, everyone's at risk. The moment a server is shared, its bugs, its downtime, its security holes, and its breaking changes are no longer your private problem; they're a blast radius. That's why leads stop treating internal servers like scripts and start treating them like the shared APIs they are: versioned (so a change doesn't silently break every caller), documented (so people can adopt it without reading your source), access-controlled (because it runs with real permissions over real data), and monitored (so you learn it's down before your users do).

The mistake here is two-sided. One direction is building a fresh server for every need when a maintained, vetted one already exists — reinventing wiring the building already has. The other, more dangerous direction is adopting a third-party server without vetting it, forgetting that it will run with your agent's permissions and see your agent's data: a server you don't trust is a lamp wired straight into the mains with no fuse. The lead's real job is the deliberate build-vs-adopt call — prefer a maintained, vetted server by default, build only when nothing fits or the candidate fails the security check — and then to run whatever you adopt like the load-bearing infrastructure it now is. A lead treats internal MCP servers like shared APIs: versioned, documented, access-controlled, monitored. One well-built server (your ticket system, deploy logs) becomes reusable across every agent and teammate — the tool layer the whole org builds on.

def primitive_role(kind):
    return {
        "tools":     "actions the model can invoke (do something)",
        "resources": "data the server exposes to read (files, records, docs)",
        "prompts":   "reusable prompt templates the server offers",
    }[kind]

for k in ("tools", "resources", "prompts"):
    print(k, "->", primitive_role(k))

Flow (sampling request):
  server  --("please complete this prompt")-->  client
  client  --(applies its own approval/limits, calls the model)-->  model
  model   --(completion)-->  client  --(result)-->  server

Why the client stays in control:
  - the client owns the model credentials and cost budget,
  - the client can require user approval before fulfilling the request,
  - the server never gets direct model access — it asks, the client decides.

Notification (one-way, no reply expected):
  server -> client: "the resource list changed, re-fetch it"
  use case: a file-watching server tells the client new files appeared.

Elicitation (request that needs a user answer):
  server -> client -> user: "which environment: staging or prod?"
  user   -> client -> server: "staging"
  use case: a deploy server needs a target it can't infer.

def pick_transport(local, remote_access, multiple_clients):
    if local and not remote_access:
        return "stdio — local subprocess, simplest, no network exposure"
    if remote_access or multiple_clients:
        return "streamable HTTP — networked/shareable, now you own auth + hardening"
    return "stdio — default for a single local tool"

print(pick_transport(True,  False, False))  # stdio
print(pick_transport(False, True,  True))   # streamable HTTP

import time

def call(server, request, timeout=10.0, retries=2):
    for attempt in range(retries + 1):
        start = time.monotonic()
        resp = server.try_request(request, deadline=start + timeout)  # your transport
        if resp is not None and not resp.get("error"):
            return resp
        if resp is not None and resp["error"]["type"] == "invalid_request":
            raise ValueError("permanent error — don't retry")   # fix the request
        # timeout or transient server error -> back off and retry
        time.sleep(2 ** attempt)
    raise TimeoutError("server unresponsive after retries")

def build_or_adopt(exists, maintained, passes_vetting, custom_logic):
    if not exists:            return "BUILD — nothing exists for this need"
    if not passes_vetting:    return "BUILD/FORK — candidate fails security vetting"
    if custom_logic:          return "BUILD on the pattern — logic too specific"
    if maintained:            return "ADOPT — maintained + vetted; faster than building"
    return "ADOPT cautiously — pin a version, watch for abandonment"

def vet(s):
    risk = 0
    risk += 0 if s.get("open_source") else 2
    risk += 2 if s.get("broad_scope") else 0
    risk += 3 if s.get("wants_plaintext_secrets") else 0
    risk += 2 if (s.get("transport")=="http" and not s.get("uses_auth")) else 0
    return "TRUST" if risk==0 else ("REVIEW" if risk<4 else "REJECT"), risk

print(build_or_adopt(True, True, True, False))                 # ADOPT
print(vet({"open_source":True,"transport":"stdio"}))           # ('TRUST', 0)

Knowledge check check yourself