Model Context Protocol

The Model Context Protocol, or MCP, is a standard way for an AI application to connect to servers that expose tools, resources and prompts, instead of a developer wiring each integration by hand. The protocol’s own architecture overview names three participants: an MCP host is “the AI application that coordinates and manages one or multiple MCP clients”; an MCP client “maintains a connection to an MCP server and obtains context from an MCP server for the MCP host to use”; an MCP server is “a program that provides context to MCP clients”[1]. A host creates one client per server[1].

MCP sits at level 4 for the same reason function calling does: a tool a server exposes is still one fixed action your code carries out once the model picks it, inside a run your code bounds. The line to level 5 falls in the same place too: one choice here, against a loop the model leaves on its own in a single agent. What MCP changes is not how much the model decides but where the tool definitions and the code that runs them live: behind a protocol boundary any compliant host can speak, instead of wired into one application’s own tool-calling code.

This page provides primary references and illustrative examples. The examples are scripted, not measured model runs; source references do not establish the correctness of every implementation or outcome.

"What does part HLV-2205 cost?"

class StandInServer:
    """Handles `tools/list` and `tools/call`, JSON-RPC-shaped. Not a real MCP server: no
    capability negotiation, no other methods, one hard-coded tool."""

    def __init__(self, sections: dict[str, Section]) -> None:
        self._sections = sections

    def handle(self, request: dict) -> dict:
        method = request.get("method")
        if method == "tools/list":
            return _rpc_result(request, {"tools": [SEARCH_TOOL]})
        if method == "tools/call":
            return self._call_tool(request)
        return _rpc_error(request, f"unknown method: {method}")

    def _call_tool(self, request: dict) -> dict:
        params = request.get("params", {})
        if params.get("name") != SEARCH_TOOL["name"]:
            return _rpc_error(request, f"unknown tool: {params.get('name')}")
        query = params.get("arguments", {}).get("query", "")
        hits = bm25_search(self._sections, query, k=SEARCH_K)
        text = "\n\n".join(f"[{s.cite}] {s.title}\n{s.text}" for s, _ in hits) or "no results"
        return _rpc_result(request, {"content": [{"type": "text", "text": text}], "isError": False})


def _rpc_result(request: dict, result: dict) -> dict:
    return {"jsonrpc": "2.0", "id": request.get("id"), "result": {"resultType": "complete", **result}}


def _rpc_error(request: dict, message: str) -> dict:
    # -32602 is the spec's own example code for "Unknown tool" in its protocol-errors example.
    return {"jsonrpc": "2.0", "id": request.get("id"), "error": {"code": -32602, "message": message}}


def connect(server: StandInServer) -> Transport:
    """The in-memory pipe: calling `transport(request)` is this example's entire substitute for
    serializing a JSON-RPC message onto stdio or a Streamable HTTP request and reading the reply
    back off it. A real client does that serialization; here the message dict just changes hands
    inside one process."""
    return server.handle


def list_tools(transport: Transport) -> list[dict]:
    response = transport({"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}})
    return response["result"]["tools"]


def call_tool(transport: Transport, name: str, arguments: dict) -> tuple[str, bool]:
    """Returns (text, is_error). `is_error` covers both the spec's tool-execution errors
    (`isError: true` in a normal result) and this stand-in's one protocol error."""
    response = transport({"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": name, "arguments": arguments}})
    if "error" in response:
        return response["error"]["message"], True
    content = response["result"]["content"]
    text = "\n".join(block["text"] for block in content if block.get("type") == "text")
    return text, response["result"].get("isError", False)

    del embedder  # this level retrieves through the MCP server's tool, not a vector index
    sections = load_sections(corpus_dir)
    transport = connect(StandInServer(sections))

    mcp_tools = list_tools(transport)
    tracer.record(kind="code", decided_by="code", title="List tools from the MCP server", detail=mcp_tools[0]["name"])

    messages = [Message(role="system", content=SYSTEM_PROMPT), Message(role="user", content=question)]
    first = model.complete(messages, tools=[_to_model_tool(t) for t in mcp_tools], max_tokens=300)

    if not first.tool_calls:
        tracer.record(
            kind="model",
            decided_by="model",
            title="Model answers directly, no tool call",
            detail=first.text[:200],
            tokens_in=first.tokens_in,
            tokens_out=first.tokens_out,
            ms=first.ms,
        )
        return Answer.from_text(first.text)

python -m examples.mcp --model stub:scripted

Stateless MCP

“Stateless” is the specification’s own word for the current revision, not a paraphrase. Its changelog lists “Make MCP stateless: remove the initialize/notifications/initialized handshake. Every request now carries its protocol version and client capabilities in _meta”[6] among the major changes since the previous revision, 2025-11-25[6]. The maintainers’ roadmap, updated August 22, 2026, refers to the 2026-07-28 revision as a release already made, not a proposal[9].

Two changes shipped together. The handshake is gone: earlier revisions opened a connection with an initialize call and kept capabilities for as long as it lasted; every request now states its own protocol version and capabilities instead. Protocol-level sessions are gone with it: the same changelog entry removes “protocol-level sessions and the Mcp-Session-Id header from the Streamable HTTP transport”, and says “Servers that need cross-call state use explicit, server-minted handles passed as ordinary tool arguments”[6]. The transport specification is direct about what that took away: servers used to assign a session via a header, a client could open a standalone stream for server-initiated messages, and a broken stream could resume; “None of these mechanisms are part of this revision”[5], and a server that gets an Mcp-Session-Id header from an older client is told to “ignore it, and do not mint or echo session IDs”[5].

The proposal that became this, SEP-2575, gives the reason: the old handshake created “significant challenges for scalability (load balancing requires sticky sessions), resilience (server failure loses session state), and implementation complexity (both client and server must manage session lifecycles)”[7]. A protocol that asks nothing to be remembered between requests has nothing to lose when the backend that handled the last one is gone. The companion proposal, SEP-2567, describes what replaces a session for a server that genuinely needs one: “Stateful workflows use create_*() -> handle + threaded parameters (guidance, not a protocol construct)”[8]: an ordinary tool call hands back an identifier, and later calls pass it back as an argument like any other, rather than something the transport carries.

Both proposals are merged (SEP-2575 on May 11, 2026, SEP-2567 on May 7, 2026), so both changes are in the 2026-07-28 revision: released, not proposed. What is still open is narrower: the roadmap lists “capability scoping for tool lists after SEP-2575” among what maintainers want to look at next[9], a refinement of what a stateless request can express, not a reconsideration of removing sessions in the first place.

Authorization

Connecting to somebody else’s server raises a question the rest of this page does not: how a server you did not write learns who is asking. The specification has a chapter for it, scoped narrowly. The protocol “provides authorization capabilities at the transport level, enabling MCP clients to make requests to restricted MCP servers on behalf of resource owners”, and “This specification defines the authorization flow for HTTP-based transports”[10]. Nothing here is invented for MCP: the chapter builds on OAuth 2.1 and a list of related RFCs, of which it implements a selected subset[10].

None of that moves a decision, which is why it belongs to level 4 rather than a rung of its own. The model still picks one action and your code still carries it out. Authorization is the separate question of whether your code is allowed to carry it out, and on whose behalf. Guardrails limits what may be done; this settles who the server thinks is asking.

You do not need it for a server you run yourself on your own machine: “Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment”[10]. It is optional in general, too: “Authorization is OPTIONAL for MCP implementations”[10]. A remote server that asks for nothing still conforms, so “it speaks MCP” says nothing about who may call it.

The failure mode the specification spends requirements on is a token reaching the wrong server. “MCP servers MUST validate that access tokens were issued specifically for them as the intended audience”, and “MCP servers MUST NOT accept or transit any other tokens”[10]. A host that passes one server’s token along to another is the case those two sentences exist to stop.

Failure modes

Cost and latency

Illustrative, not measured: no result file exists for this technique yet, so every number below is a worked example. See docs/EVALS.md for how a real run is recorded and scored.

How to Evaluate It

The example answers the same kind of question function_calling does, with the same citations, so it is scored against the site’s own 60-question set the same way (see docs/EVALS.md): exact or rubric match, plus citation hit rate. Level 4 adds the same check function calling describes: model_decided_steps should equal the number of questions run, exactly one per question.

The number specific to this technique, beyond accuracy, is how much the protocol layer itself costs: compare tokens_in and wall_time_s on a result file here against function_calling’s own, on the same questions, to see what routing the same one decision through a client and server boundary adds over calling a Python function directly. In this example that boundary is an in-process function call, so the difference is the tools/list round trip and nothing else; over a real transport it also carries network time this measurement will not show.

No result file exists for MCP yet. Run python scripts/eval_run.py --example mcp --model <spec> --dry to project the cost of a real run before spending anything on one.

Run it

Try it

1. Use it

   Find a product that lets you connect an MCP server. Before adding one, read every tool it would expose, and ask whether you would trust a stranger to write instructions your assistant follows automatically.

2. Build it

   Run python -m examples.mcp --model stub:scripted from the repo root: the server lists its one tool, the model calls it, and the answer cites the section with the price in it. Then, in a Python shell, build the transport yourself and call call_tool(transport, "search_docs", {"query": "pump"}): a tool name the server never registered. Back comes ("unknown tool: search_docs", True), a protocol error the caller can read, not an exception. Which layer decided that, and what would a real host do with it?

3. Either lane

   Compare this page’s run to function calling’s. Which steps are identical, and which exist only because a protocol boundary sits between the model’s choice and the code that carries it out?

4. Build it

   Read examples/common/bench.py (docs/THE-BENCH.md describes it): READ_ONLY_HEADERS and is_read_only() sort an instrument’s commands into a query an agent may run on its own, a command that sets a value, and a command that energizes the board, which needs a person’s Approval naming the set point. Exposed as MCP tools rather than Python functions, which class could the specification’s own "Tools" primitive leave to the model alone, and which would still need the human-in-the-loop step this page’s Use it lane describes?