Capstone: a production MCP server

Review checklist

Before you hand over the keys to a new house, you walk through every room. Before publishing, walk the server through what this phase taught:

• Protocol: server/discover works; unknown methods give -32601; missing _meta gives -32602; unknown versions give -32022 with supported; notifications get no reply; ids are echoed.
• Tools: task-shaped, described for the model, strict schemas, concise structured results, teaching isError messages, annotations that tell the truth, a fixed order.
• Resources and prompts: a template instead of a giant list; -32602 for missing resources; prompt arguments validated and filled safely.
• Transport: nothing but protocol on stdout; logs on stderr; compact one-line JSON.
• Security: read-only credentials for a read-only server; no secrets in descriptions or results; input validated; no token passthrough when it goes remote.
• Shipping: conformance probes in CI; semantic versioning; listed in the registry when public.

tools = [
    {"name": "get_order", "annotations": {"readOnlyHint": True}},
    {"name": "check_stock", "annotations": {"readOnlyHint": True}},
    {"name": "cancel_order", "annotations": {"readOnlyHint": False}},
]

def writers(tools):
    return [t["name"] for t in tools if not t.get("annotations", {}).get("readOnlyHint")]

found = writers(tools)
print("tools that may change data:", found)
print("review", "FAILS" if found else "passes")

import json

PV, CAPS = "io.modelcontextprotocol/protocolVersion", "io.modelcontextprotocol/clientCapabilities"
SERVER_INFO = {"name": "mini", "version": "0.1.0"}

def dispatch(msg):
    if "id" not in msg:
        return None
    meta = msg.get("params", {}).get("_meta", {})
    if PV not in meta or CAPS not in meta:
        return {"jsonrpc": "2.0", "id": msg["id"], "error": {"code": -32602, "message": "missing _meta"}}
    if msg["method"] == "server/discover":
        result = {"supportedVersions": ["2026-07-28"], "capabilities": {"tools": {}}}
        return {"jsonrpc": "2.0", "id": msg["id"],
                "result": {"resultType": "complete", **result, "_meta": {"io.modelcontextprotocol/serverInfo": SERVER_INFO}}}
    return {"jsonrpc": "2.0", "id": msg["id"], "error": {"code": -32601, "message": "Method not found"}}

line_in = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "server/discover",
                      "params": {"_meta": {PV: "2026-07-28", CAPS: {}}}})
line_out = json.dumps(dispatch(json.loads(line_in)), separators=(",", ":"))
print(line_out)

def classify(msg):
    if "id" not in msg:
        return "notification: no reply"
    if "_meta" not in msg.get("params", {}):
        return "error -32602"
    return "route " + msg["method"]

print(classify({"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}))

Getting the order right

The order your dispatcher checks things in isn't arbitrary, and getting it wrong causes bugs that are easy to miss.

An airline checks your passport before it looks for your flight. Check the protocol version and metadata first, then route by method. If you route first, an unknown method gets "method not found" even when the real problem is that the client speaks a version you don't support. The client then looks for the wrong fix.

def dispatch(msg, methods, versions=("2026-07-28",)):
    meta = msg.get("params", {}).get("_meta", {})
    if "protocolVersion" not in meta:
        return -32602, "missing _meta"
    if meta["protocolVersion"] not in versions:
        return -32022, "unsupported version"
    if msg["method"] not in methods:
        return -32601, "method not found"
    return 0, "ok"

methods = {"tools/list"}
print(dispatch({"method": "tools/list", "params": {}}, methods))
print(dispatch({"method": "nope", "params": {"_meta": {"protocolVersion": "1999"}}}, methods))
print(dispatch({"method": "nope", "params": {"_meta": {"protocolVersion": "2026-07-28"}}}, methods))

Nothing may escape the dispatcher

One unhandled exception in a handler can end the whole connection, cutting off every other request in progress. So wrap the call to each handler. Log the details on your side, and return an internal error with no details in it.

Read-only now, safe later

This server changes nothing, which is what the brief asks for. When you add tools that write, like refunds, you'll want a confirmation from the user before anything happens, as in the multi-round-trip pattern you learned earlier in this phase. Don't rely on the model to ask first, since a prompt injection could talk it out of that.

Test beyond your own setup

A recipe that works in your oven may burn in someone else's. If you've only tried your server in one host, you've tested that host as much as your server. Hosts differ in what they send and how strictly they read replies. Your protocol tests and conformance probes run against the spec rather than one app. Run them in CI, and then try at least two hosts by hand before you publish. It's a small amount of work compared with a broken release.

Writing the README

A server isn't finished until someone else can install it. Think of the label on a medicine bottle: what it's for, how to take it and when not to. Your README should say what the server does, list every tool with what it needs, show the exact config to add to a host, and name any environment variables. Include one example of a real question it can answer.

Say plainly what it can't do, too. "Read-only: it can't change orders" is exactly what a security reviewer wants to see. It also tells users what to expect from their agent, and it saves you from support questions you'd otherwise answer one at a time. Keep it up to date, because a wrong README is far worse than a short one, and it costs little to keep right.