Live Demo Setup

Claude Desktop's own native logging — corrected against a real captured log, no jq required.

Add Filesystem to Claude Desktop:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/folder"]
    }
  }
}

Watch every connected server live (macOS):

tail -n0 -f "$HOME/Library/Logs/Claude"/mcp-server-*.log | awk '
/Message from client:/ {
  t = substr($1, 12, 8); srv = $2; gsub(/[\[\]]/, "", srv);
  sub(/^.*Message from client: /, ""); sub(/ \{ metadata:.*$/, "");
  printf "\033[1;33m%s [%s] CLIENT -> SERVER\033[0m  %s\n", t, srv, $0; next
}
/Message from server:/ {
  t = substr($1, 12, 8); srv = $2; gsub(/[\[\]]/, "", srv);
  sub(/^.*Message from server: /, ""); sub(/ \{ metadata:.*$/, "");
  printf "\033[1;36m%s [%s] SERVER -> CLIENT\033[0m  %s\n", t, srv, $0; next
}
'

No jq needed — pure awk, works with macOS's built-in version. Watches every connected server at once and tags each line with which one it came from.

No log-tailing setup at all? MCP Inspector (npx @modelcontextprotocol/inspector) shows the same traffic in a browser, with full JSON bodies.

Real Servers Reference

Servers you can actually connect to today, verified current.

Local (stdio)

Remote (HTTP)

"DeepWiki publishes both the old SSE URL and the new Streamable HTTP URL for the same service — point at both, and you're watching the transport migration this course describes, live, on a real production system."

JSON-RPC Basics

Every message — in either direction — shares one shape.

{ "jsonrpc": "2.0", "id": 1, "method": "search_recipes", "params": { "tag": "quick" } }

{ "jsonrpc": "2.0", "id": 1, "result": ["Weeknight Pasta", "Five-Minute Salsa"] }

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32601, "message": "Method not found" } }

"JSON-RPC isn't MCP's invention — it's MCP borrowing a format that was already simple, already two-way, and already boring in the best possible sense."

The Handshake

Three steps, every time — plus the two rules that protect them.

{
  "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "roots": { "listChanged": true } },
    "clientInfo": { "name": "RecipeBoxDesktopClient", "version": "1.0.0" }
  }
}

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "tools": { "listChanged": true } },
    "serverInfo": { "name": "RecipeBox", "version": "1.0.0" }
  }
}

{ "jsonrpc": "2.0", "method": "notifications/initialized" }

Version Negotiation

What actually happens when client and server don't agree the first time.

{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "...": "..." } }

{ "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2024-11-05", "...": "..." } }

What the client does next:

SUPPORTED_PROTOCOL_VERSIONS = ["2025-11-25", "2024-11-05"]

if server_version in SUPPORTED_PROTOCOL_VERSIONS:
    send_initialized_notification()   # proceed
else:
    disconnect()                      # no further communication

"Version negotiation isn't a retry loop. It's exactly one counter-offer, checked exactly once, with disconnect as the only fallback."

Capability Negotiation

Both sides declare exactly what they're each capable of — an honest menu, both ways.

{ "jsonrpc": "2.0", "id": 99, "method": "prompts/list" }

{ "jsonrpc": "2.0", "id": 99, "error": { "code": -32601, "message": "Method not found" } }

"Capability negotiation is both sides handing over an honest menu before anyone orders."

Discovery & Calling

Discovery fires automatically the instant the handshake completes — before the user even asks a question.

Part 1 — Discovery

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

{ "jsonrpc": "2.0", "id": 2, "result": { "tools": [
  { "name": "list_recipes" }, { "name": "get_recipe" }, { "name": "search_recipes" }
]}}

Part 2 — Calling

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "search_recipes", "arguments": { "tag": "quick" } } }

{ "jsonrpc": "2.0", "id": 3, "result": { "content": [{ "type": "text", "text": "Weeknight Pasta, Five-Minute Salsa" }] } }

"Discovery isn't something you triggered. It's something that already happened, quietly, the moment the handshake finished."

Transport Layer

The road every message above actually travelled on.

python3 -c "
import subprocess, json
proc = subprocess.Popen(['python3','server.py'], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
proc.stdin.write(json.dumps({'jsonrpc':'2.0','id':1,'method':'initialize',
    'params':{'protocolVersion':'2025-11-25','capabilities':{},'clientInfo':{'name':'x','version':'1'}}}) + '\n')
proc.stdin.flush()
print(proc.stdout.readline())
"

Shutdown

The one phase with no message format of its own.

"Shutdown has no goodbye message of its own. The transport closing IS the goodbye."

Pings

Checking whether anyone's still there.

{ "jsonrpc": "2.0", "id": 42, "method": "ping" }

{ "jsonrpc": "2.0", "id": 42, "result": {} }

"A ping carries no information at all. That's the whole point — a knock on the door, not a conversation."

Error Handling

When it happens, and what it looks like.

{ "jsonrpc": "2.0", "id": 4, "error": {
  "code": -32602, "message": "Unsupported protocol version",
  "data": { "supported": ["2025-11-25"], "requested": "1.0.0" }
}}

"An error isn't a crash. It's the exact same message envelope as a success, just carrying different news."

Timeouts

• Every sent request should have a timeout
• Hit with no response → send a cancellation notification, stop waiting
• A progress notification may reset the clock — a hard maximum should still apply

"A timeout isn't giving up. It's refusing to wait forever for an answer that might genuinely never come."

Cancellation

{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": { "name": "search_recipes", "arguments": { "tag": "sunday" },
              "_meta": { "progressToken": "tok-7" } } }

{ "jsonrpc": "2.0", "method": "notifications/cancelled",
  "params": { "requestId": "7", "reason": "Timeout exceeded (30s)" } }

No id — a notification referencing the original request by its requestId.

"Cancellation doesn't ask permission. It announces a decision that's already been made."

Progress Notifications

Let the client know a long-running request is still alive.

{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": { "name": "search_recipes", "arguments": { "tag": "sunday" },
              "_meta": { "progressToken": "tok-7" } } }

{ "jsonrpc": "2.0", "method": "notifications/progress",
  "params": { "progressToken": "tok-7", "progress": 60, "total": 100,
              "message": "Searching 60 of 100 recipes" } }

"Progress notifications are how a slow answer stays honest instead of just going quiet."