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

Que é o MCP de Amigo Invisible?

O servidor MCP (Model Context Protocol) de Amigo Invisible permite que calquera asistente de IA —como ChatGPT, Claude ou Gemini— cree sorteos de intercambio de agasallos de forma programática usando linguaxe natural. En vez de encher formularios web, os usuarios simplemente lle din á IA quen participa, e a IA comunícase co noso servidor para xerar o sorteo automaticamente.

O servidor implementa JSON-RPC 2.0 sobre HTTPS, seguindo a especificación MCP (versión 2025-06-18). Expón tres ferramentas públicas: create_draw, send_invitations_email e get_group_share_message.

Endpoint e Protocolo

As peticións envíanse mediante JSON-RPC 2.0 sobre HTTPS. Versión do protocolo: 2025-06-18.

Este servidor expón dúas canles no mesmo dominio: POST /mcp — a canle por defecto co conxunto completo de ferramentas, para asistentes como Claude; e POST /openai/mcp — a canle compatible con OpenAI que usa a app de ChatGPT, que expón só as tres ferramentas públicas documentadas máis abaixo. As dúas falan o mesmo protocolo JSON-RPC 2.0.

Handshake (Inicialización)

Todo cliente MCP debe completar un handshake de inicialización antes de invocar ferramentas. Tras recibir a resposta, o cliente debe enviar unha notificación notifications/initialized (sen campo id).

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

Tras a resposta de initialize, hai que enviar: { "jsonrpc": "2.0", "method": "notifications/initialized" } — o servidor responde 202 Accepted co body baleiro.

create_draw — Esquema JSON

A ferramenta principal é create_draw. Crea un sorteo de intercambio de agasallos con N participantes (mínimo 3), emparellándoos aleatoriamente respectando as exclusións, e devolve un drawId e shareCode para operacións 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

Ferramentas dispoñibles

Fluxo de integración típico

Enrutamento por idioma e marca

O parámetro locale nos argumentos de cada ferramenta determina a marca e as plantillas utilizadas. Inclúeo sempre para obter os mellores resultados.

Xestión de erros

O servidor devolve erros a nivel de ferramenta con isError: true no resultado, distinguindo "a ferramenta fallou" de "a ferramenta non existe".