MCP Cheat Sheet

┌──────────────── Host (Claude Desktop / Claude Code / your app) ────────────────┐
│                                                                                │
│   ┌─────────────┐    1:1     ┌─────────────┐        ┌─────────────┐            │
│   │ MCP Client  │◄──────────►│ MCP Server  │        │ MCP Server  │            │
│   │ (per server)│  JSON-RPC  │  github     │        │  postgres   │            │
│   └─────────────┘            └─────────────┘        └─────────────┘            │
│         ▲                    transport: stdio        transport: Streamable HTTP │
│         │                    (local subprocess)      (remote, OAuth 2.1)        │
│      Claude model ── sees tools/resources/prompts exposed by all servers        │
└────────────────────────────────────────────────────────────────────────────────┘

client ──initialize (protocolVersion, capabilities, clientInfo)──► server
client ◄──result (capabilities, serverInfo)────────────────────── server
client ──notifications/initialized──────────────────────────────► server
client ──tools/list ──► server      client ──resources/list ──► server
client ──tools/call {name, arguments} ──► server ──► result {content[], isError}

// client → server
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
  "protocolVersion": "2025-06-18",
  "capabilities": { "roots": { "listChanged": true }, "sampling": {} },
  "clientInfo": { "name": "claude-code", "version": "2.1.0" } } }

// server → client
{ "jsonrpc": "2.0", "id": 1, "result": {
  "protocolVersion": "2025-06-18",
  "capabilities": {
    "tools": { "listChanged": true },
    "resources": { "subscribe": true, "listChanged": true },
    "prompts": { "listChanged": true },
    "logging": {} },
  "serverInfo": { "name": "orders", "version": "1.4.0" } } }

// client → server (handshake complete)
{ "jsonrpc": "2.0", "method": "notifications/initialized" }

// list
{ "jsonrpc": "2.0", "id": 2, "method": "resources/list" }
{ "jsonrpc": "2.0", "id": 2, "result": { "resources": [
  { "uri": "orders://schema", "name": "Orders schema", "mimeType": "text/sql" },
  { "uri": "orders://policy/refunds", "name": "Refund policy", "mimeType": "text/markdown" } ] } }

// read
{ "jsonrpc": "2.0", "id": 3, "method": "resources/read", "params": { "uri": "orders://schema" } }
{ "jsonrpc": "2.0", "id": 3, "result": { "contents": [
  { "uri": "orders://schema", "mimeType": "text/sql", "text": "CREATE TABLE orders (…)" } ] } }

{ "jsonrpc": "2.0", "id": 4, "method": "prompts/get",
  "params": { "name": "triage", "arguments": { "order_id": "ORD-12345" } } }
{ "jsonrpc": "2.0", "id": 4, "result": { "messages": [
  { "role": "user", "content": { "type": "text",
    "text": "Triage order ORD-12345: check status, delays and next action." } } ] } }

// server → client
{ "jsonrpc": "2.0", "id": 5, "method": "sampling/createMessage", "params": {
  "messages": [{ "role": "user", "content": { "type": "text", "text": "Summarise: <500 rows>" } }],
  "maxTokens": 300, "modelPreferences": { "intelligencePriority": 0.3, "speedPriority": 0.8 } } }

// client → server (after the host runs its model, with user approval)
{ "jsonrpc": "2.0", "id": 5, "result": {
  "role": "assistant", "content": { "type": "text", "text": "12 orders delayed, avg 3 days…" },
  "model": "claude-haiku-4-5", "stopReason": "endTurn" } }

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders")

@mcp.tool()
def get_order(order_id: str) -> dict:
    """Look up one order by ID. Read-only."""
    return db.fetch_order(order_id)

if __name__ == "__main__":
    # Serves POST /mcp with streaming responses; put OAuth 2.1 in front (reverse proxy / gateway)
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8080, path="/mcp")

Client                         Reverse proxy / gateway            MCP server
  │  POST /mcp  (Bearer token)      │                                 │
  ├────────────────────────────────►  validate token, scopes         │
  │                                 ├────────────────────────────────► initialize / tools/call
  │                                 │                                 │
  │  ◄─────── streamed JSON-RPC responses (chunked) ─────────────────┤

┌── Host (MCP client) ──┐         ┌── Authorization server ──┐      ┌── MCP server ──┐
│ 1. discover metadata  │────────►│  /.well-known/oauth-*    │      │  (resource)    │
│ 2. PKCE: code_verifier│         │                          │      │                │
│    + code_challenge   │         │                          │      │                │
│ 3. authorize (browser)│────────►│  user logs in, consents  │      │                │
│ 4. redirect w/ code   │◄────────│  auth code               │      │                │
│ 5. token (code +      │────────►│  /token                  │      │                │
│    code_verifier)     │◄────────│  access + refresh token  │      │                │
│ 6. call with Bearer   │───────────────────────────────────┼─────►│ validate scope │
│ 7. refresh on expiry  │────────►│  /token (refresh_token)  │      │                │
└───────────────────────┘         └──────────────────────────┘      └────────────────┘

// Protocol / JSON-RPC error (method missing, bad params)
{ "jsonrpc": "2.0", "id": 7, "error": { "code": -32602, "message": "Invalid params: order_id required" } }

// Tool execution error (call succeeded, tool failed) — isError on the result
{ "jsonrpc": "2.0", "id": 8, "result": {
  "isError": true,
  "content": [{ "type": "text", "text": "{\"category\":\"not_found\",\"retryable\":false,\"message\":\"No order ORD-999\"}" }] } }