# MCP from the wire up

By @omar · Published Nov 2, 2026 · From the roadmap [Building AI Agents: tools, memory and evals](https://ornix.io/u/omar/building-ai-agents)

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.

```mermaid
%% ornix:id=mcp00001
flowchart LR
    U["User"] --> H["Host app (your agent)"]
    H --> C1["Client 1"]
    H --> C2["Client 2"]
    C1 -- "stdio" --> S1["Local server: files"]
    C2 -- "Streamable HTTP" --> S2["Remote server: tickets"]
    S1 --> T1["tools / resources / prompts"]
    S2 --> T2["tools / resources / prompts"]
```

## 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.

```json
{"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

```python
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?

---

Roadmap: https://ornix.io/u/omar/building-ai-agents (Markdown: https://ornix.io/u/omar/building-ai-agents.md)

Canonical page: https://ornix.io/u/omar/building-ai-agents/mcp-from-the-wire-up
