Official Technical ReferenceJSON-RPC 2.0

Model Context Protocol Specification

The comprehensive architectural breakdown of MCP: connection lifecycles, JSON-RPC 2.0 wire framing, primitives (Tools, Resources, Prompts, Roots, Sampling), and enterprise sandboxing policies.

Interactive Playground Config Generator Agent Skills

Spec Highlights

Base ProtocolJSON-RPC 2.0

TransportsSTDIO / SSE

Schema StandardDraft-07 JSON

Release Version2024-11-05

Live Wire Inspector

JSON-RPC 2.0 Protocol Payloads

initialize (Handshake)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {}
    },
    "clientInfo": {
      "name": "ClaudeDesktop",
      "version": "0.8.2"
    }
  }
}

Section 01

Core Protocol Primitives

The 5 essential capabilities negotiated between hosts and servers.

Executable FunctionsModel-Controlled

Tools

Functions exposed by the server that AI models can discover and invoke with validated JSON arguments.

Lifecycle Behavior:Discovered via tools/list, invoked via tools/call. Server returns formatted content (text, image, resource) with an optional isError flag.

Context URIsApplication-Controlled

Resources

Read-only context data (files, database schemas, API specs, log streams) exposed via standard URI templates.

Lifecycle Behavior:Clients query resources/list, read contents with resources/read, and subscribe to real-time changes with resources/subscribe.

Slash CommandsUser-Controlled

Prompts

Pre-engineered prompt templates and workflows registered by servers to standardize complex multi-step reasoning tasks.

Lifecycle Behavior:Discovered via prompts/list, retrieved with arguments via prompts/get. Host clients surface these as slash commands in chat UI.

Filesystem BoundariesHost-Controlled

Roots

Defines the explicit filesystem boundaries and workspace folders that the server is permitted to access.

Lifecycle Behavior:Server requests roots/list from client; client sends notifications/roots/list_changed when workspace changes occur.

Reverse LLM CompletionServer-Initiated

Dynamic Sampling

Enables an MCP server to request LLM generations back through the client, allowing nested agentic intelligence.

Lifecycle Behavior:Server dispatches sampling/createMessage with messages and temperature. Host client prompts user or auto-approves generation.

Section 02

Transports & Wire Formats

Comparing process-isolated local transports with remote streaming connections.

STDIO (Standard I/O)

Local Subprocess

Latency< 1ms

SecurityProcess Sandbox

The host spawns the server as a child process. Messages are sent via newline-delimited UTF-8 JSON-RPC strings over STDIN and STDOUT.

Key Operational Rules:

STDOUT is exclusively reserved for valid JSON-RPC frames.
Server debug logs must be routed to STDERR.
Process lifecycle is strictly tied to host application session.

SSE (Server-Sent Events) + HTTP POST

Remote / Cloud

Latency10 - 80ms

SecurityTLS + Bearer Tokens

Server streams events to client via HTTP GET /sse, while client posts JSON-RPC payloads via HTTP POST to the returned endpoint URI.

Key Operational Rules:

Initial GET /sse handshake returns endpoint URI event with session ID.
Requires keep-alive ping comments every 15-30s to prevent reverse proxy drop.
Supports multi-client concurrent connections over HTTP/2 or HTTP/1.1.

Streamable HTTP / WebSockets

High Performance

Latency5 - 30ms

SecurityBidirectional Stream

Modern streaming transport utilizing full-duplex HTTP streaming or WebSocket frames for microservice architectures.

Key Operational Rules:

Optimized for Kubernetes clusters and container meshes.
Supports binary multiplexing and zero-copy JSON parsing.

Section 03

State Machine & Handshake Lifecycle

Sequential handshake from initialization through normal operations to teardown.

Initialize Request

Client -> Serverinitialize

Negotiates protocol version, declares host capabilities (roots, sampling), and shares client info.

Initialize Response

Server -> Clientresult

Server acknowledges protocol version, returns server capabilities (tools, resources, prompts), and server info.

Initialized Notification

Client -> Servernotifications/initialized

Handshake completed. Server is now permitted to send notifications and handle operational requests.

Operational Phase

Bidirectionaltools/call, resources/read, ...

Model executes tools, reads resources, triggers prompts, and exchanges heartbeats via ping.

Teardown

Client / Serverclose / SIGTERM

Graceful termination of subprocess pipes or SSE streaming connections.

Section 04

Enterprise Security & Sandboxing Matrix

Safeguards protecting against arbitrary code execution, credential leakage, and SSRF.

Explicit Roots Boundary

Filesystem servers MUST strictly enforce path scoping within roots/list boundaries to prevent directory traversal attacks (e.g. ../../etc/passwd).

Confirmation Gates for Destructive Actions

Host clients should render interactive user confirmation prompts before executing mutating tools (e.g. DB DELETE, Git Push, Shell exec).

Environment Variable Isolation

Pass only declared server credentials in the env block; never leak host system parent environment variables.

SSRF & Network Egress Restrictions

Fetch and web scraping servers should block internal private IP ranges (127.0.0.1, 10.0.0.0/8, 169.254.169.254) to prevent metadata service exploits.