MCP from the wire up
MCP is an open protocol that lets any AI application talk to any tool server through one interface. If you can read JSON-RPC, you can read the whole thing. This note shows the messages themselves, so a framework never has to be magic.
The problem it solves
Without a standard, $M$ applications and $N$ systems need $M \times N$ custom integrations. With a standard, each application implements the client once and each system implements the server once: $M + N$. Five apps and eight systems is 40 integrations or 13.
Roles and primitives
- Host: the app the user runs (an IDE, a chat app, your own agent). It creates one client connection per server.
- Server: a program that exposes capabilities.
A server can offer three things, and the difference is who decides when to use it:
- Tools: functions the model can call (search, create a ticket). Model-controlled.
- Resources: read-only data the application attaches (a file, a schema). Application-controlled.
- Prompts: templates the user picks (a slash command). User-controlled.
Most servers are only tools, and that is fine.
On the wire
Every message is JSON-RPC 2.0: a request has an id and a method, a response echoes the id with a result or an error, and a notification has no id. Two transports matter. stdio runs the server as a child process; messages are one JSON object per line on stdin and stdout, which is why a stdio server must never print to stdout (a stray print corrupts the stream; log to stderr). Streamable HTTP carries the same messages as POST requests to one endpoint, with authorization through OAuth.
The protocol has changed shape recently. Through the 2025 revisions a connection began with an initialize handshake and sometimes an Mcp-Session-Id. The 2026-07-28 revision made MCP stateless: no handshake, no protocol-level sessions, and every request carries its own version and capabilities in _meta. A server must answer server/discover, results carry a resultType, and list results carry cache hints. Servers that need state across calls hand the model an explicit handle and take it back as an ordinary tool argument. Official SDKs bridge old and new for a while, so read the revision your SDK targets.
{"jsonrpc": "2.0", "id": 1, "method": "tools/list",
"params": {"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {"name": "my-agent", "version": "0.1.0"},
"io.modelcontextprotocol/clientCapabilities": {}}}}
{"jsonrpc": "2.0", "id": 1, "result": {
"resultType": "complete",
"tools": [{"name": "search_notes",
"description": "Full-text search over my notes. Returns up to 10 matches.",
"inputSchema": {"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"]}}],
"ttlMs": 300000, "cacheScope": "public"}}
{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {"name": "search_notes", "arguments": {"query": "retrieval"},
"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {"name": "my-agent", "version": "0.1.0"},
"io.modelcontextprotocol/clientCapabilities": {}}}}
{"jsonrpc": "2.0", "id": 2, "result": {
"resultType": "complete",
"content": [{"type": "text", "text": "3 matches: week-4.md, rag-notes.md, ..."}],
"isError": false}}
That is the whole loop between an agent and a server: list the tools, hand the descriptions to the model as tool schemas, and when the model asks, send tools/call and return content. The model never speaks MCP. Your host translates.
A server in a dozen lines
from mcp.server import MCPServer
mcp = MCPServer("notes")
@mcp.tool()
def search_notes(query: str) -> str:
"""Full-text search over my notes. Returns up to 10 matches as 'path: snippet' lines.
Args:
query: Keywords, for example 'retrieval hybrid'
"""
hits = index.search(query, limit=10)
return "\n".join(f"{h.path}: {h.snippet}" for h in hits) or "No matches. Try broader keywords."
if __name__ == "__main__":
mcp.run(transport="stdio")
The SDK turns the type hints and docstring into the tool's inputSchema and description. In current 2.x releases of the Python SDK the class is MCPServer; older 1.x releases call it FastMCP. Everything in the tool-design note applies: the docstring is the interface the model sees.
Security you must not skip
- Tool descriptions and results are untrusted input. A malicious or compromised server can put instructions in a description. Connect only servers you trust, and show the user what a tool does before it runs.
- Least privilege. A stdio server runs as you. Give it a narrow directory, a read-only token, a container.
- Annotations are hints, not guarantees. The spec itself says to treat them as untrusted unless the server is trusted.
- Humans in the loop for anything that writes, spends or sends.
- Roots, sampling and logging are deprecated in the newest revision; do not build new work on them.
Common mistakes
- Printing to stdout from a stdio server.
- Exposing forty tools from one server and burying the model in schemas.
- Returning 100,000 characters from a tool. Paginate, as in the tool-design note.
- Assuming the server remembers the last call. Under the newest spec, pass explicit handles.
- Testing only inside a chat app. Use the Inspector to see the raw messages and replay calls.
Check yourself
- Who decides when a tool, a resource and a prompt is used?
- What changed in the 2026-07-28 revision, and why does it help servers run behind load balancers?
- Why can a stdio server not use
print? - What belongs in
inputSchema, and what in the description?