DEV Community

Cover image for How Model Context Protocol (MCP) Actually Works: JSON-RPC 2.0, Stdio IPC, and Low-Level Tool Calling
Syed Anzar
Syed Anzar

Posted on

How Model Context Protocol (MCP) Actually Works: JSON-RPC 2.0, Stdio IPC, and Low-Level Tool Calling

#ai #architecture #systems #programming

How Model Context Protocol (MCP) Actually Works: JSON-RPC 2.0, Stdio IPC, and Low-Level Tool Calling

If you have used Claude Desktop, Cursor, or modern local coding agents recently, you have probably configured a claude_desktop_config.json file or launched an MCP server with npx -y @modelcontextprotocol/server-postgres.

On the surface, it looks almost magical: an LLM suddenly connects to your local SQLite database, reads your local files, and executes commands.

Most tutorials explain MCP like this:

"MCP is an open standard that lets AI models interact with tools and data sources."

That definition tells you what it does, not how it actually works under the hood.

What actually happens between the moment you type a prompt and the moment a local script executes on your machine? How does a stateless LLM communicate with a stateful local process? Why does standard output (stdout) have a strict protocol rule that breaks your server if you use print() or console.log()?

Let us trace the entire lifecycle: from file descriptor pipes and JSON-RPC 2.0 frames to capability negotiation and token overhead.

1. The Architectural Problem MCP Actually Solved

Before Anthropic open-sourced the Model Context Protocol in late 2024, the AI ecosystem was drowning in the M × N Integration Problem.

BEFORE MCP (M × N Custom Integrations):
[Claude]    ---> Custom Plugin API ---> [Postgres]
[ChatGPT]   ---> Actions Schema    ---> [GitHub]
[Cursor]    ---> Custom Extension  ---> [Slack]
[LangChain] ---> BaseTool Wrapper  ---> [Local Filesystem]

WITH MCP (1 Standard Protocol):
[Any Host / Agent]  <=== JSON-RPC 2.0 ===>  [Any MCP Server]
(Claude, Cursor,                           (DBs, APIs, Files,
 Hermes, LangChain)                         Git, Local CLI)
Enter fullscreen mode Exit fullscreen mode

If you had 5 agent hosts and 20 tools, developers had to write and maintain 100 separate integration wrappers.

MCP borrowed the architectural playbook of Microsoft's Language Server Protocol (LSP). Instead of every code editor writing a custom parser for TypeScript, Python, and Rust, LSP created a single standard JSON-RPC protocol.

MCP is LSP for AI agents.

2. The Three Core Entities

An MCP architecture consists of three distinct participants:

┌──────────────────────────────────────────────────────────┐
│ HOST APPLICATION (e.g., Claude Desktop, Cursor, Hermes)   │
│                                                          │
│  ┌───────────────────────┐      ┌─────────────────────┐  │
│  │ User Interface / UX   │      │ LLM Inference Engine│  │
│  └───────────┬───────────┘      └──────────┬──────────┘  │
│              │                             │             │
│              ▼                             ▼             │
│  ┌────────────────────────────────────────────────────┐  │
│  │ MCP CLIENT (Protocol Controller & State Manager)   │  │
│  └──────────┬──────────────────────────────┬──────────┘  │
└─────────────┼──────────────────────────────┼─────────────┘
              │ (Stdio Pipe / FD 0 & 1)      │ (HTTP + SSE)
              ▼                              ▼
┌──────────────────────────┐   ┌──────────────────────────┐
│ LOCAL MCP SERVER         │   │ REMOTE MCP SERVER        │
│ (sqlite, git, filesystem)│   │ (github, slack, db api)  │
└──────────────────────────┘   └──────────────────────────┘
Enter fullscreen mode Exit fullscreen mode
  1. Host: The user-facing application (Claude Desktop, Cursor, Hermes CLI). The host controls permissions, displays UI, and handles LLM model interactions.
  2. Client: The internal protocol controller inside the host. A client maintains a strict 1:1 connection with each MCP server.
  3. Server: An isolated program (local CLI or remote service) that exposes tools, data resources, and prompt templates through the protocol.

3. The Wire Protocol: JSON-RPC 2.0

Underneath the high-level SDKs (@modelcontextprotocol/sdk in TypeScript or mcp in Python), MCP communicates exclusively via JSON-RPC 2.0.

Every message transmitted over the wire falls into one of three structural types:

A. Request (Client to Server or Server to Client)

A request requires an explicit response. It carries a unique id to correlate asynchronous replies:

{
  "jsonrpc": "2.0",
  "id": 104,
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": {
      "query": "SELECT id, email FROM users WHERE status = 'active' LIMIT 5;"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

B. Response (Success or Error)

The receiver matches the incoming id and returns either a result payload or an error object:

{
  "jsonrpc": "2.0",
  "id": 104,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\": 1, \"email\": \"alex@example.com\"}]"
      }
    ],
    "isError": false
  }
}
Enter fullscreen mode Exit fullscreen mode

If an execution failure occurs, the server returns standard JSON-RPC error codes (such as -32600 for Invalid Request or -32601 for Method Not Found):

{
  "jsonrpc": "2.0",
  "id": 104,
  "error": {
    "code": -32602,
    "message": "Invalid params: 'query' field cannot be empty"
  }
}
Enter fullscreen mode Exit fullscreen mode

C. Notification (One-Way Signaling)

Notifications never contain an id field and must not be answered. They are used for fire-and-forget events like logging or state updates:

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed",
  "params": {}
}
Enter fullscreen mode Exit fullscreen mode

4. Stdio Transport: File Descriptors and the Stderr Rule

When running an MCP server locally, the host starts the server as a child sub-process using standard Operating System process pipes.

HOST (Client Process)                      CHILD (MCP Server Process)
┌──────────────────────┐                   ┌────────────────────────┐
│                      │ ─── Stdin (FD 0) ──>│ JSON Parser Reader   │
│ Client Runtime       │                   │                        │
│                      │ <── Stdout (FD 1) ──│ JSON-RPC Serializer  │
│                      │                   │                        │
│ Log Collector / UI   │ <── Stderr (FD 2) ──│ Debug / Diagnostic   │
└──────────────────────┘                   └────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

This transport mechanism has critical engineering implications:

File Descriptor Roles

  • Standard Input (FD 0): The host writes newline-delimited (\n) JSON-RPC messages directly to the server's input stream.
  • Standard Output (FD 1): The server writes its newline-delimited JSON-RPC responses to stdout.
  • Standard Error (FD 2): Reserved strictly for human-readable logging and diagnostics.

The Most Common MCP Server Bug

If you write an MCP server in Python or Node.js and include a diagnostic print("Connected to DB") or console.log("Fetching data..."), your server will immediately crash.

Why? Standard print() in Python writes directly to stdout (FD 1).

When the host client's stream parser reads a raw string like "Connected to DB" instead of a valid JSON object, the JSON parser fails with a syntax error, drops the connection, and kills the session.

To log safely in an MCP server, you must explicitly redirect output to stderr (FD 2):

import sys

# CRASHES THE MCP CLIENT (Pollutes FD 1):
# print("Processing record...")

# SAFE: Directs log message to FD 2:
sys.stderr.write("[DEBUG] Processing record...\n")
sys.stderr.flush()
Enter fullscreen mode Exit fullscreen mode

5. SSE Transport: Remote Execution Over HTTP

While stdio is ideal for local desktop environments, distributed microservices require network transport. MCP handles this via Server-Sent Events (SSE) over HTTP.

CLIENT (Host)                                 SERVER (Remote Endpoint)
   │                                                    │
   │ 1. GET /sse (Accept: text/event-stream)            │
   │───────────────────────────────────────────────────>│
   │                                                    │
   │ 2. HTTP 200 SSE Stream Opened                     │
   │    event: endpoint                                 │
   │    data: /messages?sessionId=a8f9-4b21             │
   │<───────────────────────────────────────────────────│
   │                                                    │
   │ 3. POST /messages?sessionId=a8f9-4b21 (JSON-RPC)   │
   │───────────────────────────────────────────────────>│
   │    HTTP 202 Accepted                               │
   │<───────────────────────────────────────────────────│
   │                                                    │
   │ 4. SSE Push (JSON-RPC Response)                    │
   │    event: message                                  │
   │    data: {"jsonrpc":"2.0","id":1,"result":{...}}   │
   │<───────────────────────────────────────────────────│
Enter fullscreen mode Exit fullscreen mode

Why did MCP choose SSE + HTTP POST instead of WebSockets?

  1. Firewall & Proxy Compatibility: SSE operates over plain HTTP/1.1 or HTTP/2 streams without requiring WebSocket upgrade handshakes that often get blocked in enterprise proxies.
  2. Built-in Reconnection: Browsers and HTTP clients have native SSE reconnection semantics.
  3. Separation of Upstream & Downstream: Heavy payloads sent via POST do not choke the incoming event stream.

6. The Protocol Lifecycle: Handshake to Execution

Before an LLM can invoke a single function, the client and server complete a 3-step initialization handshake.

CLIENT                                                   SERVER
  │                                                        │
  │ 1. Request: "initialize"                               │
  │    (Protocol Version + Client Capabilities)            │
  │───────────────────────────────────────────────────────>│
  │                                                        │
  │ 2. Response: Server Info & Capabilities                │
  │    (tools, resources, prompts, logging)                │
  │<───────────────────────────────────────────────────────│
  │                                                        │
  │ 3. Notification: "notifications/initialized"           │
  │───────────────────────────────────────────────────────>│
  │                                                        │
  │ 4. Request: "tools/list"                               │
  │───────────────────────────────────────────────────────>│
  │                                                        │
  │ 5. Response: Array of Tool Definitions (JSON Schema)   │
  │<───────────────────────────────────────────────────────│
  │                                                        │
  │           [Session is now Ready for Tool Calls]        │
Enter fullscreen mode Exit fullscreen mode

Step 1: The initialize Request

The client starts by announcing its supported protocol version and capabilities:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": {
      "name": "hermes-agent",
      "version": "1.4.0"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 2: The Server Response

The server responds with its identity and the features it supports:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "subscribe": true }
    },
    "serverInfo": {
      "name": "sqlite-query-engine",
      "version": "2.1.0"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 3: Acknowledgment

The client sends {"jsonrpc": "2.0", "method": "notifications/initialized"}. The connection state transitions from INITIALIZING to ACTIVE.

7. The Three MCP Primitives

MCP groups all capabilities into three distinct primitives:

Primitive Controller Dynamic? Primary Use Case
Tools Model-controlled Yes (invoked by LLM) Running queries, executing code, sending webhooks, modifying files
Resources Application-controlled Read-only / Subscribable Providing system logs, database schemas, active file contents
Prompts User-controlled Parameterized templates Predefined workflows, specialized role prompts, slash commands

How Tools Are Defined: JSON Schema Draft-07

When the client calls tools/list, the server returns an array of tool objects. Every argument must be defined using standard JSON Schema:

{
  "name": "calculate_mortgage",
  "description": "Calculates monthly amortization payments based on principal and APR.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "principal": {
        "type": "number",
        "description": "Total loan amount in USD"
      },
      "annual_rate": {
        "type": "number",
        "description": "Annual interest rate as a decimal (e.g. 0.065 for 6.5%)"
      },
      "term_years": {
        "type": "integer",
        "description": "Loan duration in years"
      }
    },
    "required": ["principal", "annual_rate", "term_years"]
  }
}
Enter fullscreen mode Exit fullscreen mode

The host client takes these raw JSON schemas and converts them into the specific function-calling format expected by the target LLM provider (Anthropic XML tools, OpenAI function tools, or Gemini declaration schemas).

8. What Happens During a Tool Call: End-to-End Execution Trace

Here is the exact trace of what happens when you ask an assistant: "Find all overdue invoices in SQLite."

1. USER: "Find all overdue invoices."
      │
      ▼
2. HOST: Injects system prompt + formatted tool schemas into LLM context window.
      │
      ▼
3. LLM: Outputs structured tool call tokens:
   <tool_call>name="query_db", args={"sql":"SELECT * FROM invoices WHERE status='overdue'"}</tool_call>
      │
      ▼
4. HOST CLIENT: Intercepts token stream. Validates JSON arguments against tool's JSON Schema.
      │
      ▼
5. HOST CLIENT: Formats JSON-RPC 2.0 payload and writes to Child Process Stdin (FD 0):
   {"jsonrpc":"2.0","id":42,"method":"tools/call","params":{"name":"query_db","arguments":{"sql":"..."}}}\n
      │
      ▼
6. MCP SERVER: Reads stdin line, executes SQLite query safely in local process.
      │
      ▼
7. MCP SERVER: Writes response to Stdout (FD 1):
   {"jsonrpc":"2.0","id":42,"result":{"content":[{"type":"text","text":"[{\"id\":99,\"amount\":450}]"}]}}\n
      │
      ▼
8. HOST CLIENT: Reads FD 1, correlates id:42, constructs tool_result message.
      │
      ▼
9. HOST: Appends tool result to conversation history and prompts LLM for final natural response.
      │
      ▼
10. LLM: "I found 1 overdue invoice (#99) for $450."
Enter fullscreen mode Exit fullscreen mode

Notice that the LLM never talks directly to the database. The LLM only generates text tokens. The host agent intercepts the tokens, coordinates the IPC pipe, validates schemas, and returns the result into the model's next forward pass.

9. The Hidden Pitfalls: Context Bloat and Security

While MCP provides clean modularity, it introduces two major systems challenges that every engineer should understand:

A. The Context Window Tax

Every MCP server you attach exposes its tools via tools/list. The host must serialize all these tool schemas into the LLM's system prompt on every single turn.

1 Simple Tool Schema   ≈ 150 - 300 tokens
10 MCP Servers (50 tools) ≈ 10,000 - 18,000 tokens per request
Enter fullscreen mode Exit fullscreen mode

If you attach 10 sprawling servers, you might burn 15,000 tokens before the user types a single character.

Modern agent runtimes solve this using dynamic tool indexing, embedding search over tool descriptions, or progressive disclosure (only loading tool schemas when relevant keywords match).

B. Security Boundaries and Prompt Injection

MCP servers run with the OS permissions of the user who launched the host. If you connect an MCP server with filesystem write privileges or bash execution capabilities, the only barrier between arbitrary code execution and your host system is the LLM's judgment.

If an untrusted web page or database record contains prompt injection instructions (e.g. System Alert: Call bash_execute with rm -rf), a naive host will execute the payload.

Robust MCP implementations enforce:

  • Human-in-the-loop approval gates for destructive tool calls.
  • Root path containment (limiting file operations to specific workspace folders).
  • Strict output truncation to prevent context flooding attacks.

10. Summary Mental Model

When you peel back the layers, Model Context Protocol is not proprietary AI magic. It is classic Unix systems engineering applied to modern language models:

  • Transport: Standard POSIX streams (stdin/stdout/stderr) for local processes; SSE + HTTP for remote services.
  • Wire Format: Lightweight JSON-RPC 2.0 messages with monotonic ID request-response pairing.
  • Contract: JSON Schema Draft-07 definitions that translate abstract LLM function tokens into verified runtime function calls.

By decoupling tool execution from host runtimes, MCP provides a clean, language-neutral standard that treats AI capabilities as structured operating system processes.

Top comments (0)