Build a client

Reading results carefully

• resultType. "complete" is an ordinary result. Results from legacy servers have no resultType at all, and clients must treat that as "complete". A value the client doesn't recognize is invalid. ("input_required" is a request for more information, covered in a later lesson.)
• Errors come back as JSON-RPC errors. Raise them as an exception carrying the code, message and data, so callers can react to specific codes.

Version fallback

A client usually prefers the newest version it knows. If the server answers UnsupportedProtocolVersion (-32022), error.data.supported lists what it speaks. The client picks the best version both sides know, remembers it for this server, and retries the request once. If there's nothing in common, it raises a clear error instead of looping.

In plain words: if you ask in French and they say "English or German", switch once and remember. Don't keep asking in French.

Paging and caching

tools/list, prompts/list, resources/list and resources/templates/list can be paged. A helper should follow nextCursor until it's absent, the way you turn pages until the book ends. It should also guard against a server that returns the same cursor twice, which would loop forever.

List results carry ttlMs, which works like a "best before" date. A client can reuse a cached list for that long instead of asking again, which saves round trips and keeps the model's tool list stable. Remember cacheScope too: a "private" result must never be shared with another user.

TOOLS = [f"tool_{n}" for n in range(1, 8)]

def tools_list(cursor=None, page=3):
    start = int(cursor) if cursor else 0
    result = {"tools": TOOLS[start:start + page]}
    if start + page < len(TOOLS):
        result["nextCursor"] = str(start + page)
    return result

tools, cursor, requests_made = [], None, 0
while True:
    reply = tools_list(cursor)
    requests_made += 1
    tools += reply["tools"]
    cursor = reply.get("nextCursor")
    if cursor is None:
        break

print(len(tools), "tools in", requests_made, "requests")
print(tools)

import requests

URL = "https://api.gradient.test/mcp"
NAMED = {"tools/call": "name", "prompts/get": "name", "resources/read": "uri"}

def http_transport(msg):
    params = msg["params"]
    headers = {"Accept": "application/json, text/event-stream",
               "MCP-Protocol-Version": params["_meta"]["io.modelcontextprotocol/protocolVersion"],
               "Mcp-Method": msg["method"]}
    if msg["method"] in NAMED:
        headers["Mcp-Name"] = str(params[NAMED[msg["method"]]])
    return requests.post(URL, json=msg, headers=headers, timeout=10).json()

class Session:
    def __init__(self, transport):
        self.transport, self.next_id = transport, 0

    def request(self, method, params=None):
        self.next_id += 1
        meta = {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
                "io.modelcontextprotocol/clientCapabilities": {},
                "io.modelcontextprotocol/clientInfo": {"name": "lesson", "version": "1.0"}}
        reply = self.transport({"jsonrpc": "2.0", "id": self.next_id, "method": method,
                                "params": {**(params or {}), "_meta": meta}})
        if "error" in reply:
            raise RuntimeError(f"{reply['error']['code']}: {reply['error']['message']}")
        return reply["result"]

s = Session(http_transport)
info = s.request("server/discover")
print(info["_meta"]["io.modelcontextprotocol/serverInfo"], info["supportedVersions"])
print([t["name"] for t in s.request("tools/list")["tools"]])
print(s.request("resources/read", {"uri": "docs://help/doc_care"})["contents"][0]["text"][:60])

Why a client needs bookkeeping

A client looks simple until two requests overlap. Your code sends request 12 and then request 13. The reply to 13 arrives first. If your code assumes the next line is the reply to its last request, it hands request 12's caller the wrong answer. It's a waiter giving table 12 the food for table 13. This raises no error, and it only happens under load.

So keep a table of what's waiting, by id:

pending = {12: "list tools", 13: "read a file"}

for reply in [{"id": 13, "result": "file text"}, {"id": 12, "result": "tools"}]:
    asked = pending.pop(reply["id"])
    print(asked, "->", reply["result"])

print("still waiting:", pending)

If a reply arrives with an id you're not waiting for, log it and drop it. Add a timeout for each entry as well, so that a reply that never comes doesn't leave a caller stuck forever.

Version errors: try once, then stop

When a server says it doesn't support your version, it tells you which ones it does. Pick one you both know and retry once. If nothing matches, stop and report it clearly. A loop that keeps retrying can run forever, and the error never changes.

Don't fetch what you already have

Calling tools/list before each model call adds a slow network request to every turn. Replies can carry a ttlMs saying how long they stay good, so cache them until then. That also keeps your tool list stable, which helps prompt caching, as you'll see in the next phase.

Be careful what you share, though. A result marked private belongs to one user. Sharing it across users in one cache would show one customer's data to another. Include the user in the cache key, or don't cache it.

Treat every result as untrusted

Check a parcel before you carry it into the house. A client passes tool results to a model, and those results come from outside your system. They may be huge, oddly shaped, or carefully written to mislead the model. So check the structure before you use it, cap the size, and don't follow instructions found inside a result. Your code is the last place that can catch this before the model reads it, so it's well worth the few extra lines of code it takes.