Documentación Técnica: Integración MCP con IA

¿Qué es el MCP de Amigo Secreto?

El servidor MCP (Model Context Protocol) de Amigo Secreto permite que cualquier asistente de IA —como ChatGPT, Claude o Gemini— cree sorteos de intercambio de regalos programáticamente usando lenguaje natural. En lugar de rellenar formularios web, los usuarios simplemente dicen a la IA quiénes participan, y la IA se comunica con nuestro servidor para generar el sorteo automáticamente.

El servidor implementa JSON-RPC 2.0 sobre HTTPS, siguiendo la especificación MCP (versión 2025-06-18). Expone tres herramientas públicas: create_draw, send_invitations_email y get_group_share_message.

Endpoint y Protocolo

Las peticiones se envían mediante JSON-RPC 2.0 sobre HTTPS. Versión del protocolo: 2025-06-18.

Este servidor expone tres canales en el mismo dominio: POST /mcp — el canal por defecto con el conjunto completo de herramientas; POST /openai/mcp — el canal que usa la app de ChatGPT; y POST /claude/mcp — el conector de Claude (ver la sección de Claude más abajo). Los dos últimos exponen solo las tres herramientas públicas documentadas más abajo. Todos hablan el mismo protocolo JSON-RPC 2.0.

Handshake (Inicialización)

Todo cliente MCP debe completar un handshake de inicialización antes de invocar herramientas. Tras recibir la respuesta, el cliente debe enviar una notificación notifications/initialized (sin campo id).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "mi-cliente",
      "version": "1.0.0"
    }
  }
}

Tras la respuesta de initialize, enviar: { "jsonrpc": "2.0", "method": "notifications/initialized" } — el servidor responde 202 Accepted con body vacío.

create_draw — Esquema JSON

La herramienta principal es create_draw. Crea un sorteo de intercambio de regalos con N participantes (mínimo 3), emparejándolos aleatoriamente respetando las exclusiones, y devuelve un drawId y shareCode para operaciones posteriores.

{
  "type": "object",
  "required": ["date", "participants"],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "Fecha del sorteo, YYYY-MM-DD. Hoy o futuro."
    },
    "participants": {
      "type": "array",
      "minItems": 3,
      "description": "Mínimo 3 participantes. El primero se trata como organizador.",
      "items": {
        "type": "object",
        "required": ["name", "email"],
        "properties": {
          "name": { "type": "string", "maxLength": 255 },
          "email": { "type": "string", "format": "email" },
          "exclusions": {
            "type": "array",
            "items": { "type": "string", "format": "email" },
            "description": "Emails de participantes con los que NO debe emparejarse."
          }
        }
      }
    },
    "drawName": {
      "type": "string",
      "maxLength": 255,
      "description": "Opcional. Si se omite, se genera un default como \"Amigo Invisible 2026\"."
    },
    "price": {
      "type": "string",
      "description": "Presupuesto del regalo, texto libre. Ejemplos: \"20€\", \"$25\"."
    },
    "message": {
      "type": "string",
      "description": "Cuerpo del email de invitación. Si se omite, se usa un default localizado."
    },
    "locale": {
      "type": "string",
      "description": "Tag BCP 47 del idioma. Ej: \"es-ES\", \"es-MX\", \"en-GB\". Determina la marca y las plantillas."
    }
  }
}

Referencia de campos

Herramientas disponibles

Flujo de integración típico

Enrutamiento por idioma y marca

El parámetro locale en los argumentos de cada herramienta determina la marca y las plantillas utilizadas. Inclúyelo siempre para obtener los mejores resultados.

Gestión de errores

El servidor devuelve errores a nivel de herramienta con isError: true en el resultado, distinguiendo "la herramienta falló" de "la herramienta no existe".