Especificación Técnica MCP

Documentación técnica completa del Model Context Protocol: JSON-RPC 2.0, transport layer y referencia de implementación.

Especificación del Protocolo

El Model Context Protocol (MCP) es un protocolo abierto basado en JSON-RPC 2.0 que define cómo los clientes y servidores MCP se comunican. La especificación define los mensajes, métodos, tipos de datos y comportamientos esperados.

JSON-RPC 2.0

Protocolo de comunicación estándar basado en JSON para llamadas a procedimientos remotos.

Transport Layer

Soporte para múltiples transportes: stdio, SSE y WebSocket según el caso de uso.

Tipos de Datos

Esquemas JSON Schema estrictos para recursos, herramientas, prompts y mensajes.

JSON-RPC 2.0

MCP utiliza JSON-RPC 2.0 como protocolo de comunicación. Todos los mensajes siguen el formato estándar JSON-RPC.

Estructura de Mensajes JSON-RPC

Todos los mensajes MCP siguen el formato JSON-RPC 2.0 estándar

Request (Solicitud)

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

Campos requeridos:

  • jsonrpc: jsonrpc: Siempre "2.0"
  • method: method: Nombre del método a invocar
  • id: id: Identificador único (número o string)
  • params: params: Parámetros del método (opcional)

Response (Respuesta)

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

Campos requeridos:

  • jsonrpc: jsonrpc: Siempre "2.0"
  • id: id: Mismo ID de la solicitud
  • result: result: Resultado exitoso (o error si falla)

Error Response

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

Inicialización

initialize

Client → Server

Inicializa la conexión entre cliente y servidor

Parámetros:
{
  "protocolVersion": "string",
  "capabilities": "object",
  "clientInfo": "object"
}
Respuesta:
{
  "protocolVersion": "string",
  "capabilities": "object",
  "serverInfo": "object"
}

initialized

Server → Client

Notificación de que la inicialización está completa

Recursos

resources/list

Client → Server

Lista todos los recursos disponibles

Respuesta:
{
  "resources": "Resource[]"
}

resources/read

Client → Server

Lee el contenido de un recurso específico

Parámetros:
{
  "uri": "string"
}
Respuesta:
{
  "contents": "Content[]"
}

resources/search

Client → Server

Busca recursos que coincidan con una consulta

Parámetros:
{
  "query": "string"
}
Respuesta:
{
  "resources": "Resource[]"
}

Herramientas

tools/list

Client → Server

Lista todas las herramientas disponibles

Respuesta:
{
  "tools": "Tool[]"
}

tools/call

Client → Server

Ejecuta una herramienta específica

Parámetros:
{
  "name": "string",
  "arguments": "object"
}
Respuesta:
{
  "content": "Content[]",
  "isError": "boolean"
}

Prompts

prompts/list

Client → Server

Lista todos los prompts disponibles

Respuesta:
{
  "prompts": "Prompt[]"
}

prompts/get

Client → Server

Obtiene un prompt específico con sus argumentos

Parámetros:
{
  "name": "string",
  "arguments": "object"
}
Respuesta:
{
  "messages": "Message[]",
  "description": "string"
}

Transport Layer

MCP soporta múltiples mecanismos de transporte para adaptarse a diferentes casos de uso y entornos.

stdio

Comunicación a través de entrada/salida estándar. Ideal para procesos locales.

Caso de uso:

Servidores locales, integración con aplicaciones de escritorio

Ejemplo:

Claude Desktop ejecuta servidores MCP como procesos hijos usando stdio

Ventajas:

  • •Simple y directo
  • •Sin overhead de red
  • •Seguro para procesos locales
  • •Soporte universal

Limitaciones:

  • •Solo para procesos locales
  • •No permite comunicación remota
  • •Limitado a un solo cliente

SSE (Server-Sent Events)

Comunicación unidireccional del servidor al cliente sobre HTTP. Útil para notificaciones.

Caso de uso:

Servidores remotos, notificaciones en tiempo real

Ejemplo:

Servidor MCP ejecutándose en un servidor remoto que envía actualizaciones

Ventajas:

  • •Permite comunicación remota
  • •Notificaciones en tiempo real
  • •Compatible con HTTP estándar
  • •Reconexión automática

Limitaciones:

  • •Solo unidireccional (servidor → cliente)
  • •Requiere HTTP/HTTPS
  • •Más complejo que stdio

WebSocket

Comunicación bidireccional en tiempo real sobre TCP. Para aplicaciones interactivas.

Caso de uso:

Aplicaciones web, comunicación bidireccional en tiempo real

Ejemplo:

Cliente web conectándose a un servidor MCP remoto

Ventajas:

  • •Comunicación bidireccional
  • •Baja latencia
  • •Eficiente para múltiples mensajes
  • •Soporte para subprotocolos

Limitaciones:

  • •Requiere servidor WebSocket
  • •Más complejo de implementar
  • •Overhead de protocolo

Referencia Técnica

Tipos de datos, esquemas y estructuras utilizadas en el protocolo MCP.

Tipos de Datos Principales

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
    }
  ]
}

Códigos de Error JSON-RPC

-32700

Parse error - JSON inválido

-32600

Invalid Request - Estructura inválida

-32601

Method not found - Método no existe

-32602

Invalid params - Parámetros inválidos

-32603

Internal error - Error interno del servidor

-32000 a -32099

Server error - Errores específicos del servidor

Ejemplo Completo: Flujo de Comunicación

Secuencia completa de mensajes JSON-RPC para inicializar y usar un servidor MCP

1. Inicialización

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. Listar Herramientas

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"}
          }
        }
      }
    ]
  }
}

¿Necesitas más detalles?

Explora la arquitectura, recursos, herramientas y ejemplos prácticos de implementación.

Ver ArquitecturaVer RecursosVer Herramientas