Understanding the MCP Specification

A technical overview of the MCP specification including JSON-RPC 2.0 messaging, protocol versions, and capability negotiation.

title: "Understanding the MCP Specification" description: "A technical overview of the MCP specification including JSON-RPC 2.0 messaging, protocol versions, and capability negotiation." order: 10 keywords:

• MCP specification
• MCP spec
• MCP JSON-RPC
• MCP protocol
• MCP message types
• MCP capability negotiation date: "2026-04-01"

What is the MCP Specification?

The specification is the source of truth for anyone building MCP tools — whether you are using mcp-framework, the official @modelcontextprotocol/sdk, or implementing the protocol from scratch in any language. Understanding the specification helps you build more robust servers and debug protocol-level issues.

JSON-RPC 2.0 Foundation

MCP is built on JSON-RPC 2.0, a lightweight remote procedure call protocol that uses JSON for message encoding. This choice provides several advantages:

• Language-agnostic — JSON is universally supported across programming languages
• Simple — The message format is straightforward and easy to debug
• Proven — JSON-RPC 2.0 is a mature, well-understood standard
• Extensible — Custom methods and parameters are added without modifying the base protocol

JSON-RPC 2.0 Message Structure

Every MCP message follows the JSON-RPC 2.0 format:

Request Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_documents",
    "arguments": {
      "query": "MCP specification",
      "limit": 5
    }
  }
}

Successful Response Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 5 documents matching 'MCP specification'..."
      }
    ]
  }
}

Error Response Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: 'limit' must be a positive integer"
  }
}

Protocol Lifecycle

The specification defines a strict lifecycle for MCP sessions:

1. Initialization

The session begins with the initialize request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": {
      "name": "claude-desktop",
      "version": "1.5.0"
    }
  }
}

The server responds with its own capabilities and information:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "subscribe": true, "listChanged": true },
      "prompts": { "listChanged": true },
      "logging": {}
    },
    "serverInfo": {
      "name": "my-mcp-server",
      "version": "1.0.0"
    }
  }
}

After receiving the initialize response, the client sends the initialized notification to signal that it is ready:

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

2. Operation

After initialization, the client and server exchange messages according to the negotiated capabilities. The specification defines methods for each primitive:

3. Shutdown

The session ends when either side closes the connection. The specification does not define a formal shutdown handshake — the transport connection is simply closed.

Protocol Versioning

The MCP specification uses date-based versioning (e.g., 2025-03-26). This approach makes it clear when a version was published and simplifies version comparison.

Version Negotiation

During initialization, the client sends its supported protocol version. The server responds with the version it will use for the session. The specification requires:

1. The client sends the latest version it supports
2. The server responds with a version it supports that is compatible with the client's version
3. If no compatible version exists, the server returns an error and the connection is terminated

Capability Negotiation Details

The specification defines which capabilities clients and servers can declare:

Server Capabilities

{
  "capabilities": {
    "tools": {
      "listChanged": true
    },
    "resources": {
      "subscribe": true,
      "listChanged": true
    },
    "prompts": {
      "listChanged": true
    },
    "logging": {}
  }
}

• tools — Server exposes callable tools. listChanged means the server may notify when the tool list changes.
• resources — Server exposes readable resources. subscribe enables resource change subscriptions. listChanged enables list change notifications.
• prompts — Server exposes prompt templates. listChanged enables list change notifications.
• logging — Server can send log messages to the client.

Client Capabilities

{
  "capabilities": {
    "roots": {
      "listChanged": true
    },
    "sampling": {}
  }
}

• roots — Client can provide filesystem root URIs to the server. listChanged means the client may notify when roots change.
• sampling — Client supports the server requesting LLM completions (advanced feature).

Tool Definition Schema

The specification defines how tools are described:

{
  "name": "search_documents",
  "description": "Search the document repository by keyword or semantic query",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of results",
        "default": 10
      },
      "type": {
        "type": "string",
        "enum": ["keyword", "semantic"],
        "description": "Search type"
      }
    },
    "required": ["query"]
  }
}

The inputSchema uses JSON Schema to describe the tool's expected input. This schema is used by AI models to understand how to call the tool and by servers to validate incoming arguments.

Content Types in the Specification

The specification defines structured content types for tool results and resource data:

Text Content

{
  "type": "text",
  "text": "This is plain text or markdown content"
}

Image Content

{
  "type": "image",
  "data": "base64-encoded-image-data",
  "mimeType": "image/png"
}

Resource Content (Embedded)

{
  "type": "resource",
  "resource": {
    "uri": "file:///project/data.json",
    "text": "{\"key\": \"value\"}",
    "mimeType": "application/json"
  }
}

Error Codes

The specification extends standard JSON-RPC 2.0 error codes with MCP-specific codes:

Servers should also return meaningful error messages when tool calls fail, using the result with isError: true:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Database connection timed out after 30 seconds"
    }
  ],
  "isError": true
}

Transport Specifications

The specification defines requirements for each transport:

stdio

• Messages are delimited by newlines
• Each message is a single JSON-RPC 2.0 message on one line
• Server must read from stdin and write to stdout
• stderr is reserved for logging (not protocol messages)

Streamable HTTP

• Single endpoint (e.g., /mcp) accepts POST requests
• Each POST body contains a JSON-RPC 2.0 message
• Server may respond with a direct JSON response or upgrade to SSE for streaming
• Session management via Mcp-Session-Id header
• Optional GET endpoint for server-initiated notifications

SSE (Legacy)

• Two endpoints: GET for SSE stream, POST for client messages
• Server sends endpoint event with the POST URL
• Messages flow as SSE events with JSON-RPC 2.0 payloads

For implementation details, see MCP Transport Protocols.

Reading and Following the Specification

The MCP specification is available at spec.modelcontextprotocol.io. When building MCP servers:

1. Use a framework — mcp-framework and the official SDK implement the specification for you, handling protocol details correctly
2. Reference the spec for edge cases — When you encounter unexpected behavior, the specification is the authoritative answer
3. Track specification changes — Subscribe to the specification repository on GitHub to stay informed about protocol updates
4. Test against multiple clients — Different clients may implement the specification differently; testing ensures compatibility