The underwriting agent's five tools live inside one program. The registry, the definitions and the execution adapter sit next to the loop in the agent's own process, and they work. Then two more teams want the same tools. The underwriter cockpit wants get_roof_assessment to show the provider's roof age beside the application's. A broker-facing assistant wants the read tools so it can answer "what does the guidance say about roofs in wind zone C?".
The first answer is to copy. Each team copies the definitions into its own application, wires the functions to its own HTTP client for the roof-data provider, and writes its own checks. Six months later there are three versions of get_roof_assessment. One has the pattern ^SUB-[0-9]{4}$ on submission_id, one does not, and one returns the provider's raw error text to its model. A fix to the adapter reaches one of the three. Nobody can say which version the broker assistant runs.
The problem is not the tools. It is that each tool is welded to the application that calls it. The Model Context Protocol (MCP) is an open protocol that separates the two: one program offers the tools behind a standard interface, and any application that speaks the protocol can discover and call them. The model still only proposes a call; your code still decides whether it runs. MCP changes where that code lives and how applications reach it.
Discovery built a catalog the model can choose from. This page puts that catalog behind a protocol.
One server, many applications#
Plain English. Instead of every application carrying its own copy of the underwriting tools, one program offers them. Each application connects to that program, asks "what tools do you have?", and sends "run this tool with these arguments". The program runs the same adapter for everyone.
Before AI. Java developers met this with JDBC. Before it, every database came with its own client library and every application was written against one of them. JDBC fixed one interface; a driver per database implemented it; an application could talk to any database through the same calls. The MCP specification names a different ancestor, the Language Server Protocol, which let one language server serve many editors. The idea is the same: one standard between many consumers and many providers, so that neither side is rewritten for each pairing.
For the insurance example this means one underwriting server holds the registry, the adapter, the scopes and the provider credentials. The agent, the cockpit and the broker assistant each connect to it. A change to the pattern on submission_id is made once, in one place, and every application sees it on its next tools/list.
Three roles: host, client, server#
MCP names three roles. Each one is a different program, or a different part of one, and each has a different job. As documented on 2026-11-17 for revision 2026-07-28:
An MCP host is the application the user works in. It holds the conversation, talks to the model, decides which servers to connect, and asks the user for consent. In the example, the underwriting agent's application is a host, and so is the cockpit.
An MCP client is a connector that the host creates for one server. Each client talks to exactly one server, a one-to-one relation, and attaches the protocol version and its capabilities to every request it sends. A host that uses three servers runs three clients. In the example, mcp_client.py plays this part with its class StdioClient.
An MCP server is the program that offers capabilities: tools, and also two other kinds this page covers below. It can be a local process or a remote service. In the example, mcp_server.py is the server, with the class Server.
Notice what is not a role: the model. The model never speaks MCP. It reads tool definitions that the host gives it and writes tool requests; the host's client turns a request into a protocol message. "The model calls the MCP server" is a short way of saying something false.
Diagram: Host, clients, servers · who holds the conversation, who holds the tools
Read left to right. The host holds the conversation, the model integration and the user's consent. It runs one client per server. Each server offers tools, resources and prompts and sees only the requests its own client sends. The model is not a role: it reads definitions and writes requests inside the host.
- 1 · The host
- MCP host: The application the user works in: it holds the conversation, talks to the model and asks for consent.
- Model: Reads the tool definitions the host gives it and writes requests; it never speaks MCP itself.
- 2 · One client per server
- MCP client: A connector the host creates for exactly one server; it attaches version and capabilities to every request.
- MCP client: A second, separate connector; what it receives never reaches the underwriting server.
- 3 · Servers
- MCP server: Offers the five tools, the roof report as a resource and one prompt; runs the adapter behind tools/call.
- MCP server: Offers its own primitives; it cannot see the conversation or the other server.
The diagram shows who holds what. The host keeps the whole conversation and the user's consent. Each client is a narrow pipe to one server. The architecture page read on 2026-11-17 states a design principle that follows from this shape: servers should not be able to read the whole conversation, nor see into other servers; the full history stays with the host. The underwriting server learns the arguments of each call, not the broker's email or what the documents server returned.
Messages are JSON-RPC#
All MCP messages follow JSON-RPC 2.0, a small standard for remote procedure calls written as JSON. A request has a method, params and an id; the answer carries the same id and either a result or an error with an integer code and a message. A message without an id is a notification: the receiver must not answer it.
MCP narrows that standard in a few ways, as documented on 2026-11-17. A request id must not be null. Every result carries a resultType, which is "complete" for a normal answer. And in revision 2026-07-28, every request carries _meta with the protocol version and the client's capabilities, because the protocol keeps no state between requests. MCP on the wire explains why the protocol became stateless and what the earlier revision did instead.
Here is the smallest real message: the first request of the example's session, captured by mcp_client.py. It asks the server what it can do, and carries nothing but the required metadata.
{
"jsonrpc": "2.0",
"id": 1,
"method": "server/discover",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "uw-tools-teaching-client",
"version": "0.1.0"
},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}
Three primitives, three different controllers#
A server offers three kinds of thing, which the specification calls primitives. What separates them is not their format but who decides when they are used. As documented on 2026-11-17:
Tools are model-controlled. The model discovers them and proposes calls based on the conversation. The specification adds that there SHOULD always be a human in the loop with the ability to deny tool invocations. In the example: the five underwriting tools.
An MCP resource is data the server offers for the host to bring into context, identified by a URI. Resources are application-driven: the host decides how to include them, for example through a picker, a search, or automatic inclusion. In the example: the full roof report at uw://roof-assessments/SUB-1004, the same report the tool result of get_roof_assessment only points to.
An MCP prompt is a message template the server offers for a person to pick. Prompts are user-controlled, typically exposed as commands such as slash commands. The specification clarifies that this is about who decides when a prompt is used, not who writes it: the server defines its content. In the example: one prompt, assess_submission, which a person can pick to start an assessment of a submission.
| Primitive | Who decides when it is used | Methods | In the example |
|---|---|---|---|
| Tool | The model proposes; the host may ask a person | tools/list, tools/call | get_roof_assessment and four more |
| Resource | The host application | resources/list, resources/read | uw://roof-assessments/SUB-1004 |
| Prompt | The user | prompts/list, prompts/get | assess_submission |
The split matters for safety and for design. A resource is attached by code the host controls, so it never depends on the model asking for the right thing. A prompt starts from a person's choice. Only tools put the model in the position of choosing an action, which is why the rest of this site spends most of its time on them. Retrieval uses the difference between a tool and a resource to decide who chooses what the model reads.
Discovering what a server can do#
Before a client uses a server, it needs to know which primitives the server offers. In MCP this is called capability negotiation: each side declares the features it supports, and both keep to what the other declared.
In revision 2026-07-28, as documented on 2026-11-17, the negotiation happens on every request rather than once at the start. The client puts its capabilities in _meta of each request. The server advertises its capabilities in the answer to server/discover, a method every server MUST implement and a client may call before anything else. The result names the protocol versions the server supports, its capabilities, optional instructions for the model, and the server's self-reported name and version, which the specification says clients SHOULD NOT rely on for security decisions.
One rule changed shape with the stateless revision and matters for tools. A server no longer sends requests to the client. When a tool needs something from the user mid-call, such as a confirmation, the server answers the tools/call with a result whose resultType is "input_required", listing what it needs. The client gathers the answer and retries the original request with a new id and the answers attached. The example's server never needs this; MCP on the wire describes the flow.
The example's session, message by message#
The example's MCP-style server is a teaching subset of revision 2026-07-28, written from the specification; it is not the official SDK and is not conformance tested. Use an MCP SDK for a real server. Behind its tools/call sits the same execution adapter as everywhere in the example, so the validation, the scopes and the envelope are the ones earlier pages built.
The script show_mcp_session.py was written for this page and run in a scratch copy of the example, after mcp_client.py recorded the session. It prints one tool definition as the server lists it, then every message of the session on one line, with who sent it. A successful run proves that the server answers discovery with one supported version and three capabilities, lists the five tools with their annotations, runs a valid call, reports a bad argument as a result with isError true and an unknown tool as a JSON-RPC error, and serves a resource and a prompt. It does not prove conformance with the specification.
cd examples/uw-tools
/opt/homebrew/bin/python3 mcp_client.py > /dev/null
/opt/homebrew/bin/python3 show_mcp_session.py
The first part of the output is the tools/list entry for the one write tool. The client turns this into a tool definition for the model; the annotations stay with the host.
tools/list entry for record_recommendation (inputSchema properties cut to their names):
{
"name": "record_recommendation",
"title": "Record a recommendation",
"description": "Store the agent's recommendation for the underwriter, who decides. WRITES one row with status awaiting_underwriter. Call it once, at the end, with the idempotency_key given in the request. It cannot approve, decline, bind or quote anything.",
"inputSchema": {
"type": "object",
"properties": [
"idempotency_key",
"recommendation",
"submission_id"
],
"required": [
"submission_id",
"recommendation",
"idempotency_key"
],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
The second part is the session. Messages 1 to 16 are the subject of this page; 17 to 24 are protocol errors that MCP on the wire explains.
1 client id 1 server/discover with _meta {}
2 server id 1 resultType complete: {"supportedVersions": ["2026-07-28"], "capabilities": {"tools": {"listChanged": false}, "resources": {}, "prompts": {}}}
3 client id 2 tools/list with _meta {}
4 server id 2 resultType complete: ["get_roof_assessment", "search_guidance", "find_similar_decisions", "check_eligibility", "record_recommendation"]
5 client id 3 tools/call with _meta {"name": "get_roof_assessment", "arguments": {"submission_id": "SUB-1004"}}
6 server id 3 resultType complete: {"isError": false, "content": ["text", "resource_link"], "structuredContent.ok": true}
7 client id 4 tools/call with _meta {"name": "get_roof_assessment", "arguments": {"submission_id": 1004}}
8 server id 4 resultType complete: {"isError": true, "content": ["text"], "structuredContent.ok": false}
9 client id 5 tools/call with _meta {"name": "get_roof_report", "arguments": {"submission_id": "SUB-1004"}}
10 server id 5 error -32602: Unknown tool: get_roof_report
11 client id 6 resources/list with _meta {}
12 server id 6 resultType complete: ["uw://roof-assessments/SUB-1004"]
13 client id 7 resources/read with _meta {"uri": "uw://roof-assessments/SUB-1004"}
14 server id 7 resultType complete: {"uri": "uw://roof-assessments/SUB-1004", "mimeType": "application/json"}
15 client id 8 prompts/list with _meta {}
16 server id 8 resultType complete: ["assess_submission"]
17 client id 9 tools/delete with _meta {"name": "record_recommendation"}
18 server id 9 error -32601: Method not found
19 client id 10 tools/list with _meta {}
20 server id 10 error -32022: Unsupported protocol version
21 client id 11 tools/list NO _meta {}
22 server id 11 error -32602: Invalid params: _meta must carry io.modelcontextprotocol/protocolVersi
23 client id 12 initialize NO _meta {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "uw-tools-tea ...
24 server id 12 error -32601: Method not found: this server speaks MCP 2026-07-28 only (no initializ
Read it as the default case UW-004 would use it. Messages 1 and 2: the client learns the server speaks 2026-07-28 and offers tools, resources and prompts. Messages 3 and 4: the client fetches the five definitions, in the same order every time, which the specification recommends so that clients and prompt caches can rely on the list. Messages 5 and 6: the model proposed get_roof_assessment for SUB-1004, the host's client sent it, and the server's adapter ran it. The result carries the envelope twice, as text in content and as structuredContent, plus a resource_link to the full report.
Messages 13 and 14 read that report as a resource, with no model involved: the host decided to fetch it. Messages 15 and 16 list the prompt a person could pick. Every request, from the first to the last that succeeded, carried _meta, and every successful answer carried resultType: "complete".
Diagram: One tool call through MCP · the model proposes, the server's adapter executes
Time runs down the page, for the default case UW-004 over the example's MCP-style server (a teaching subset of revision 2026-07-28). The host turns the server's list into definitions for the model, the model writes a proposal, the client sends it, and the server's adapter validates, authorizes and runs it before anything comes back.
- Host + client to MCP server: tools/list. Every request carries the protocol version and client capabilities in _meta.
- MCP server to Host + client: five definitions + annotations. In a fixed order, so the host can cache the list.
- Host + client to Model: tool definitions. Name, description and input schema; the annotations stay with the host.
- Model to Host + client: request: get_roof_assessment SUB-1004. A proposal, not an execution.
- Host + client to MCP server: tools/call. The client sends the proposal as a protocol request.
- MCP server to Host + client: result: envelope, isError false. The adapter validated, authorized and ran it: roof age 22, EV-ROOF-0412, a resource link.
- Host + client to Model: tool result. The model reads the envelope and continues.
The sequence adds the actors the transcript cannot show. The host gives the model the definitions it got from tools/list. The model writes a request, which is a proposal. The client sends it as tools/call, the server's adapter validates, authorizes and executes, and the result travels back the same way until the model reads it.
The lab replays the 24 recorded messages one at a time and marks who sent each. The table after it holds the same information.
| # | Sender | Method | What it shows |
|---|---|---|---|
| 1, 2 | client, server | server/discover | Versions, capabilities, server info; every request carries _meta with the protocol version |
| 3, 4 | client, server | tools/list | The five definitions with inputSchema and annotations |
| 5, 6 | client, server | tools/call | A call the model proposed; the result has content, structuredContent (the envelope), isError false |
| 7, 8 | client, server | tools/call | Wrong type (UW-T01): a tool execution error, isError true |
| 9, 10 | client, server | tools/call | Unknown tool (UW-T02): JSON-RPC error -32602 |
| 11 to 16 | client, server | resources/list, resources/read, prompts/list | Resources are application-controlled; prompts are user-controlled |
| 17, 18 | client, server | tools/delete | Unknown method: -32601 |
| 19 to 22 | client, server | tools/list | Unsupported version: -32022; missing _meta: -32602 |
| 23, 24 | client, server | initialize | A legacy 2025-11-25 client: -32601, the server names the version it supports |
Two kinds of error#
Messages 7 to 10 show the line MCP draws between two failures. The specification read on 2026-11-17 calls them protocol errors and tool execution errors.
A protocol error means the request itself is wrong: an unknown tool, a malformed request, a server failure. It comes back as a JSON-RPC error with a code and no result. This site's own case UW-T02 asks for get_roof_report, which does not exist, and gets -32602 with the message "Unknown tool: get_roof_report". The specification says clients MAY pass protocol errors to the model, and that these are less likely to lead to recovery.
A tool execution error means the request was well formed and the tool could not do its job: an API failure, an input that fails validation, a business rule. It comes back as a normal result with isError: true, so the model can read it and correct itself, and the specification says clients SHOULD pass it to the model. This site's own case UW-T01 sends submission_id as the number 1004; the result carries the invalid_arguments envelope with the failing path, and the model fixes the type on its next request.
It is tempting to treat the second as the first, because JSON-RPC defines -32602 "Invalid params" for exactly this. The specification chooses otherwise, and the reason is the reader. A JSON-RPC error may never reach the model; a result with isError does. Results shows how the example's envelope maps onto both channels.
What MCP does not do#
The protocol carries requests and results between programs that agree on a format. A list of what it leaves to you is as useful as a list of what it does, because each item is a place where a team might assume the protocol has it covered.
It does not validate business rules. MCP requires an inputSchema and says servers MUST validate tool inputs, but which roof ages are plausible, or whether a recommendation may be stored twice, is your code. In the example, the strict schema and the idempotency key live in the adapter behind tools/call, not in the protocol.
It does not authorize inside a tool. The specification says MCP itself cannot enforce its security principles at the protocol level. Who may call record_recommendation is decided by the adapter's scope check: started with UW_TOOLS_CALLER set to assessment-agent, the same server refuses the write with not_authorized, this site's own case UW-T03. For a remote server, OAuth tells the server who is calling; the scope check is still yours. MCP on the wire covers that path.
It does not make annotations true. A server may label a tool read-only; the MCP tools page read on 2026-11-17 says clients MUST treat annotations as untrusted unless they come from trusted servers. Discovery explains how the example keeps hints apart from permissions.
And it does not decide. No message in the protocol approves a submission. In the example, no tool does either: record_recommendation stores a recommendation with requires_human fixed to true and status awaiting_underwriter. The model recommends; a person decides, in the underwriter cockpit, through the cockpit's own code path.
What this is not. MCP connects an application to the tools, resources and prompts a server offers. When one agent hands a whole task to another agent and waits for its result, that is agent-to-agent communication, a different protocol with different concerns, and it belongs to https://a2a.sammuthu.com.
In a coding agent. A coding agent's host often connects several MCP servers at once: one for the repository withread_file,search_codeandedit_file, one for the issue tracker, one for continuous integration withrun_tests. Each runs behind its own client, so the tracker server never sees the source the repository server returned. The host, not the protocol, decides thatgit_pushandopen_pull_requestneed a person's approval. Diff to Deploy follows such a change from a coding agent to production.
How the SDKs express it#
The example's server is about two hundred lines of standard-library Python, written to show the messages. Real servers use an MCP SDK, which handles the message format, the metadata on each request and the transports, and lets a tool be declared as a decorated function. The SDKs moved with the stateless revision; for example, the Python SDK's v2 renamed its high-level server class FastMCP to MCPServer, as its "What's new" page says (read on 2026-11-17). Frameworks describes each SDK from its own documentation. Whatever the SDK, the body behind a tool still needs the adapter: validation, authorization, timeouts and an envelope the model can read.
Where the trust boundaries areThe host is the policy point; a server sees only its calls; self-reported names prove nothing
MCP's shape puts policy in the host. The architecture page read on 2026-11-17 lists the host's duties: it controls client permissions and lifecycle, enforces security policies and consent, handles user authorization decisions, and aggregates context across clients. Servers are meant to be easy to build and narrow in what they see.
That gives three boundaries to defend. Between the host and each server: the host must not forward the whole conversation, and a server must not be able to read another server's results. Between the server's claims and the host's decisions: tool annotations, instructions in the discovery result and the server's self-reported serverInfo are text written by the server; the specification says clients SHOULD NOT rely on serverInfo for security decisions and MUST treat annotations from untrusted servers as untrusted. And between the model's proposal and the server's execution: the host may show a person the inputs before sending a call, and the server must still validate and authorize as if the host had not.
Apply that to the cockpit. If it connects a third-party property-data server beside the underwriting server, that server's tool descriptions and results enter the model's context. A description that says "always call this tool before recording a recommendation" is an instruction from a stranger. The host's job is to decide which servers may be connected for which users, and the underwriting server's job is to refuse any write that its own checks do not allow, whatever the model was told.
A catalog per caller, not per connectiontools/list may vary by authorization, must not vary by connection; deterministic order and caching
The tools page read on 2026-11-17 is precise about what the answer to tools/list may depend on. It MUST NOT vary per connection or as a side effect of earlier requests on the connection. It MAY vary by the authorization presented on the request, for example returning only the tools the caller's scopes permit, because credentials are per-request input, not connection state.
That is Registry.definitions(scopes) from Discovery moved into the server. The example's server does not do it yet: its tools_list returns all five tools to every caller and leaves the refusal to the adapter at call time. A production version would filter the list by the caller's scopes, so the assessment agent's host never offers record_recommendation to its model, and would keep the call-time check as well.
Two operational rules come with it. Return tools in a deterministic order, which the specification recommends because it lets clients cache the list and improves prompt cache hits when tools are part of the model's context. And honor the freshness fields: in revision 2026-07-28 list results carry ttlMs and cacheScope. The example's server answers tools/list with ttlMs 300000 and cacheScope "public", which would be wrong for a list filtered by scopes: a list that depends on the caller must not be cached as public.
When MCP is worth it, and when a library is betterA protocol boundary buys reuse and isolation and costs a process, a version and a failure mode
MCP pays off when several hosts need the same tools, when the tools belong to a different team than the agent, when they must run with credentials the agent's process should not hold, or when an application should accept tools it was not built with. The insurance example has the first three: three hosts, a platform team that owns the provider integration, and provider credentials that belong in one place.
It costs something in every case. There is another process to deploy and watch, a protocol revision to keep in step across hosts and servers, a new failure mode (the server is down or slow, which Reliability treats), and for remote servers an authorization flow. Every call crosses a boundary that a function call did not.
When one application owns its tools and nobody else needs them, plain code is better: a registry and an adapter in the same process, as in the example's loop.py, called with no protocol at all. Moving to MCP later is mostly mechanical if the registry, the definitions and the adapter were already separate from the loop. Keep them separate from the start, and the protocol becomes a deployment choice rather than a rewrite.
Asking the user mid-call without a server requestinput_required results, requestState, and why the state must be signed
Suppose a future version of record_recommendation needs a person's confirmation before it stores a recommendation to escalate. Under the earlier revision, the server would have sent an elicitation request to the client in the middle of the call. In revision 2026-07-28, as documented on 2026-11-17 on the multi round-trip requests page, servers no longer send requests to clients; the old pattern is no longer supported.
Instead the server answers the tools/call with resultType: "input_required" and inputRequests, a map of what it needs (for example an elicitation/create with a form), plus an optional opaque requestState. The client asks the person, then retries the original call with a new JSON-RPC id, the answers in inputResponses, and the requestState echoed back unchanged. Only tools/call, resources/read and prompts/get may answer this way. The retry is a complete, independent request, so any server instance can handle it.
The security consequence is stated plainly in the specification: requestState passes through the client and MUST be treated as attacker-controlled. If it influences authorization or business logic, the server MUST protect its integrity, for example with an HMAC, and SHOULD bind it to the authenticated principal, a short expiry and the originating request. For the example, a state that says "the underwriter confirmed escalation for SUB-1004" is worthless unless the server can prove it wrote that state itself, for that caller, for that call, a minute ago. Even then the integrity check does not make it single-use; a write that must happen once still needs the idempotency key.
Checklist for Monday#
| Check | Why |
|---|---|
| Tools that more than one application needs live in one server with one adapter | One definition and one fix instead of three drifting copies |
| Every message names who acts: the model proposes, the host's client sends, the server's adapter executes | "The model calls the server" hides where the checks are |
| Resources are used for data the application decides to attach; tools for actions the model may propose | Different controllers, different risks |
Validation failures and business-rule failures are results with isError true; unknown tools and malformed requests are JSON-RPC errors | The model can only correct what it is shown |
The server checks scopes inside the adapter on every call; annotations and serverInfo decide nothing | MCP cannot enforce security at the protocol level |
tools/list is filtered by the caller's authorization when it differs per caller, and is then not cached as public | The list may vary by authorization, never by connection |
| No tool, resource or prompt approves, declines or binds | The model recommends; a person decides |
In one breath#
MCP takes tools out of the application that calls them: a server offers tools, resources and prompts; each host runs one client per server; all messages are JSON-RPC, and in revision 2026-07-28 every request carries its own version and capabilities. Tools are proposed by the model, resources are attached by the application and prompts are picked by a person, and a server reports a bad call as a result the model can read, but an unknown tool as a protocol error. The protocol moves requests; validation, authorization and every decision stay in your code.
You can now put the underwriting tools behind one server, read every message of a session, and say which side is responsible for which check. What this page took for granted is the wire itself: a pipe on a laptop is not an HTTP endpoint behind a load balancer, and a remote server has to learn who is calling before it runs a write. That is MCP on the wire.