MCP Technical Specification

Complete technical documentation of the Model Context Protocol: JSON-RPC 2.0, transport layer and implementation reference.

Protocol Specification

The Model Context Protocol (MCP) is an open protocol based on JSON-RPC 2.0 that defines how MCP clients and servers communicate. The specification defines messages, methods, data types and expected behaviors.

JSON-RPC 2.0

Standard JSON-based communication protocol for remote procedure calls.

Transport Layer

Support for multiple transports: stdio, SSE and WebSocket depending on use case.

Data Types

Strict JSON Schema schemas for resources, tools, prompts and messages.

JSON-RPC 2.0

MCP uses JSON-RPC 2.0 as the communication protocol. All messages follow the standard JSON-RPC format.

JSON-RPC Message Structure

All MCP messages follow the standard JSON-RPC 2.0 format

Request

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1,
  "params": {
    // Parámetros específicos del método
  }
}

Required fields:

jsonrpc: jsonrpc: Always "2.0"
method: method: Name of the method to invoke
id: id: Unique identifier (number or string)
params: params: Method parameters (optional)

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    // Resultado del método
  }
}

Required fields:

jsonrpc: jsonrpc: Always "2.0"
id: id: Same ID as the request
result: result: Successful result (or error if it fails)

Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      // Información adicional del error
    }
  }
}

Initialization

initialize

Client → Server

Initializes the connection between client and server

Parameters:

{
  "protocolVersion": "string",
  "capabilities": "object",
  "clientInfo": "object"
}

Response:

{
  "protocolVersion": "string",
  "capabilities": "object",
  "serverInfo": "object"
}

initialized

Server → Client

Notification that initialization is complete

Resources

resources/list

Client → Server

Lists all available resources

Response:

{
  "resources": "Resource[]"
}

resources/read

Client → Server

Reads the content of a specific resource

Parameters:

{
  "uri": "string"
}

Response:

{
  "contents": "Content[]"
}

resources/search

Client → Server

Searches for resources matching a query

Parameters:

{
  "query": "string"
}

Response:

{
  "resources": "Resource[]"
}

Tools

tools/list

Client → Server

Lists all available tools

Response:

{
  "tools": "Tool[]"
}

tools/call

Client → Server

Executes a specific tool

Parameters:

{
  "name": "string",
  "arguments": "object"
}

Response:

{
  "content": "Content[]",
  "isError": "boolean"
}

Prompts

prompts/list

Client → Server

Lists all available prompts

Response:

{
  "prompts": "Prompt[]"
}

prompts/get

Client → Server

Gets a specific prompt with its arguments

Parameters:

{
  "name": "string",
  "arguments": "object"
}

Response:

{
  "messages": "Message[]",
  "description": "string"
}

Transport Layer

MCP supports multiple transport mechanisms to adapt to different use cases and environments.

stdio

Communication through standard input/output. Ideal for local processes.

Use case:

Local servers, integration with desktop applications

Example:

Claude Desktop runs MCP servers as child processes using stdio

Advantages:

•Simple and straightforward
•No network overhead
•Secure for local processes
•Universal support

Limitations:

•Only for local processes
•Does not allow remote communication
•Limited to a single client

SSE (Server-Sent Events)

Unidirectional communication from server to client over HTTP. Useful for notifications.

Use case:

Remote servers, real-time notifications

Example:

MCP server running on a remote server sending updates

Advantages:

•Allows remote communication
•Real-time notifications
•Compatible with standard HTTP
•Automatic reconnection

Limitations:

•Unidirectional only (server → client)
•Requires HTTP/HTTPS
•More complex than stdio

WebSocket

Bidirectional real-time communication over TCP. For interactive applications.

Use case:

Web applications, bidirectional real-time communication

Example:

Web client connecting to a remote MCP server

Advantages:

•Bidirectional communication
•Low latency
•Efficient for multiple messages
•Support for subprotocols

Limitations:

•Requires WebSocket server
•More complex to implement
•Protocol overhead

Technical Reference

Data types, schemas and structures used in the MCP protocol.

Main Data Types

Resource

{
  "uri": "string",
  "name": "string",
  "description": "string",
  "mimeType": "string"
}

Tool

{
  "name": "string",
  "description": "string",
  "inputSchema": {
    "type": "object",
    "properties": {...}
  }
}

Prompt

{
  "name": "string",
  "description": "string",
  "arguments": [
    {
      "name": "string",
      "description": "string",
      "required": boolean
    }
  ]
}

JSON-RPC Error Codes

-32700

Parse error - Invalid JSON

-32600

Invalid Request - Invalid structure

-32601

Method not found - Method does not exist

-32602

Invalid params - Invalid parameters

-32603

Internal error - Server internal error

-32000 a -32099

Server error - Server-specific errors

Complete Example: Communication Flow

Complete sequence of JSON-RPC messages to initialize and use an MCP server

1. Initialization

Client → Server

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "id": 1,
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "claude-desktop",
      "version": "1.0.0"
    }
  }
}

Server → Client

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "resources": {},
      "tools": {}
    },
    "serverInfo": {
      "name": "file-server",
      "version": "0.1.0"
    }
  }
}

2. List Tools

Client → Server

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

Server → Client

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "read_file",
        "description": "Lee un archivo",
        "inputSchema": {
          "type": "object",
          "properties": {
            "path": {"type": "string"}
          }
        }
      }
    ]
  }
}

Need more details?

Explore the architecture, resources, tools and practical implementation examples.

View Architecture View Resources View Tools