Guía de Integración MCP de RubiConnect

2.1 Conector Integrado de Claude (App de Escritorio y Claude.ai Web) — Recomendado

Tanto si utilizas la Aplicación Claude Desktop en macOS/Windows como Claude.ai en tu navegador web, Anthropic ofrece una interfaz integrada de conectores visuales basada en OAuth 2.0 con PKCE. Esta es la forma más rápida y sencilla de conectar RubiConnect a Claude sin necesidad de usar el terminal.

1. En Claude Desktop o Claude.ai, navega a Settings > Connectors (o selecciona Add Custom Connector).
2. Introduce la URL del servidor:

   https://console.rubiconnect.com/api/mcp

1. Cuando aparezca el modal del conector OAuth:
   • Client ID: Pega tu Clave de API de RubiConnect (ej. rc_live_...).
   • Client Secret: Déjalo en blanco o vacío (RubiConnect utiliza RFC 7636 PKCE, el cual no requiere un secreto estático).
2. Claude abrirá tu navegador web en el puente de autorización de RubiConnect (/es/authorize), validará tu clave de API y completará el handshake automáticamente.
3. Las 16 herramientas de mensajería, campañas, plantillas y analítica estarán disponibles de inmediato en tus sesiones de Claude.

2.2 OpenAI Custom GPTs y Plataformas Empresariales de Agentes

Para conectar RubiConnect a ChatGPT Custom GPTs u orquestadores empresariales (como Flowise, LangChain o Zapier Central):

1. En el Editor de GPT, navega a Actions > Create new action.
2. En Authentication, selecciona OAuth:
   • Client ID: Introduce tu Clave de API de RubiConnect (rc_live_...).
   • Client Secret: Cualquier valor ficticio (o déjalo vacío si es compatible).
   • Authorization URL: https://console.rubiconnect.com/es/authorize
   • Token URL: https://console.rubiconnect.com/api/oauth/token
   • Scope: mcp (o déjalo vacío).
   • Token Exchange Method: POST request (Basic or Body)
3. Importa las definiciones de herramientas MCP desde https://console.rubiconnect.com/api/mcp o copia el esquema OpenAPI.
4. Guarda y prueba la acción; ChatGPT se autenticará fluidamente mediante el puente OAuth de RubiConnect.

2.3 Archivo JSON de Claude Desktop (claude_desktop_config.json) — Puente Stdio Alternativo

Si eres desarrollador y prefieres configurar Claude Desktop manualmente editando el archivo claude_desktop_config.json en el disco (en lugar de utilizar la interfaz visual de Ajustes descrita en la Sección 2.1), Claude Desktop espera un subproceso local stdio. Dado que el servidor MCP de RubiConnect se aloja de forma remota como servicio HTTP SSE, la configuración manual mediante archivo requiere una herramienta de puente (como mcp-remote) para intermediar stdio hacia el endpoint remoto SSE.

Configuración Recomendada (mcp-remote)

Añade la siguiente configuración a tu archivo claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rubiconnect": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://console.rubiconnect.com/api/mcp",
        "--header",
        "Authorization:Bearer ${RUBI_API_KEY}"
      ],
      "env": {
        "RUBI_API_KEY": "rc_live_tu_clave_real_aqui"
      }
    }
  }
}

Nota de Sintaxis: El parámetro --header debe tener el formato exacto "Authorization:Bearer ${RUBI_API_KEY}" sin espacio después de los dos puntos.

Resolución de PATH en macOS GUI: La aplicación gráfica de Claude Desktop no hereda automáticamente las variables PATH de tu terminal (.zshrc o .bashrc). Si Claude muestra el error command not found: npx, sustituye "command": "npx" por la ruta absoluta de tu binario:

* Apple Silicon (M1/M2/M3/M4): "/opt/homebrew/bin/npx"

* Intel Mac: "/usr/local/bin/npx"

* Ejecuta which npx en tu terminal para confirmar la ubicación exacta.

Alternativa: Script Puente Node.js Empaquetado

Si prefieres no ejecutar mcp-remote vía npx en cada inicio, RubiConnect proporciona un script puente en el repositorio de la plataforma en scripts/claude-mcp-bridge.mjs:

{
  "mcpServers": {
    "rubiconnect": {
      "command": "node",
      "args": ["/ruta/absoluta/a/RubiConnect platform/scripts/claude-mcp-bridge.mjs"],
      "env": {
        "RUBI_API_KEY": "rc_live_tu_clave_real_aqui"
      }
    }
  }
}

2.4 Cursor IDE

Cursor admite nativamente servidores MCP remotos Server-Sent Events (SSE) sin requerir ningún puente local:

1. Abre Cursor y presiona Cmd + , (o Ctrl + ,) para abrir Preferencias.
2. Ve a Features > MCP.
3. Haz clic en + Add New MCP Server.
4. Rellena los datos de conexión:
   • Name: rubiconnect
   • Type: SSE
   • URL: https://console.rubiconnect.com/api/mcp
   • Headers: {"Authorization": "Bearer rc_live_tu_clave_real_aqui"} (o {"X-Rubi-Key": "rc_live_tu_clave_real_aqui"})
5. Cursor se conectará inmediatamente y mostrará un indicador verde junto a rubiconnect con las 16 herramientas registradas.

2.5 Conexión mediante SDK de Python

Utilizando la librería oficial de Python mcp:

import asyncio
from mcp import ClientSession
from mcp.client.sse import sse_client

async def main():
    headers = {"Authorization": "Bearer rc_live_tu_clave_real_aqui"}
    async with sse_client("https://console.rubiconnect.com/api/mcp", headers=headers) as (read_stream, write_stream):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            
            # Listar herramientas disponibles
            tools = await session.list_tools()
            print("Herramientas disponibles:", len(tools.tools))
            
            # Consultar agentes de mensajería activos
            result = await session.call_tool("list_agents", {})
            print("Agentes:", result.content[0].text)

asyncio.run(main())

2.6 Conexión mediante SDK de Node.js

Utilizando el paquete oficial de JavaScript @modelcontextprotocol/sdk:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

async function main() {
  const transport = new SSEClientTransport(
    new URL("https://console.rubiconnect.com/api/mcp"),
    {
      headers: {
        "Authorization": "Bearer rc_live_tu_clave_real_aqui"
      }
    }
  );

  const client = new Client({
    name: "rubiconnect-mcp-client",
    version: "1.0.0"
  }, {
    capabilities: {}
  });

  await client.connect(transport);

  // Listar herramientas
  const { tools } = await client.listTools();
  console.log(`Descubiertas ${tools.length} herramientas`);

  // Consultar lista de agentes
  const agentsResponse = await client.callTool({
    name: "list_agents",
    arguments: {}
  });
  console.log("Agentes:", agentsResponse.content[0].text);
}

main();

2.7 Integración con Google Gemini API (Function Calling)

Conecta las herramientas de RubiConnect a modelos Gemini mediante el SDK oficial @google/genai:

import { GoogleGenAI } from "@google/genai";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

async function main() {
  // 1. Conectar al Servidor MCP de RubiConnect
  const transport = new SSEClientTransport(
    new URL("https://console.rubiconnect.com/api/mcp"),
    {
      headers: {
        "Authorization": "Bearer rc_live_tu_clave_real_aqui"
      }
    }
  );
  const client = new Client({ name: "gemini-mcp-agent", version: "1.0.0" }, { capabilities: {} });
  await client.connect(transport);

  // 2. Cargar herramientas MCP
  const { tools } = await client.listTools();

  // 3. Convertir herramientas MCP en declaraciones de función para Gemini
  const geminiTools = tools.map((tool) => ({
    functionDeclarations: [{
      name: tool.name,
      description: tool.description,
      parameters: tool.inputSchema
    }]
  }));

  // 4. Consultar el modelo Gemini con function calling
  const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'Por favor, lista mis agentes de mensajería activos.',
    config: {
      tools: geminiTools
    }
  });

  // 5. Ejecutar la llamada a la herramienta recomendada por Gemini
  const call = response.functionCalls?.[0];
  if (call) {
    console.log(`Llamando a herramienta MCP: ${call.name}`);
    const result = await client.callTool({
      name: call.name,
      arguments: call.args
    });
    console.log("Resultado de ejecución MCP:", result.content[0].text);
  } else {
    console.log("Respuesta de Gemini:", response.text);
  }
}

main();

Sistema y Estado

get_server_status

Obtiene el estado de salud en tiempo real, los canales de mensajería admitidos y la versión del protocolo MCP del servidor RubiConnect.

• Esquema de entrada: object (sin parámetros)
• Formato de salida: Objeto de estado que contiene status, serverName, version, protocolVersion, supportedChannels y timestamp.

Identidades de Marca y Agentes

list_agents

Recupera los perfiles de agentes de mensajería activos (RCS y WhatsApp) registrados en la cuenta.

• Esquema de entrada: object (sin parámetros)
• Formato de salida: Array de perfiles de agentes con id, displayName, type y status.

get_agent_profile

Obtiene la configuración detallada, el estado de verificación y las capacidades de canal de un perfil de agente específico.

• Parámetros:
  • agentId (string, obligatorio): Identificador único del perfil de agente.
• Formato de salida: Objeto detallado del agente con metadatos de verificación de Sinch/Meta, webhooks y atributos de canal.

Mensajería y Conversaciones

check_capability

Verifica si el número de teléfono del destinatario es compatible con mensajería enriquecida (RCS o WhatsApp) en un agente específico.

• Parámetros:
  • recipient (string, obligatorio): Número de teléfono del destinatario en formato E.164.
  • agentId (string, obligatorio): Identificador del agente.
• Formato de salida: { capable: boolean, channel: "RCS"|"WHATSAPP", status: string }

send_message

Envía un mensaje a un destinatario individual O transmite una difusión masiva sin persistencia directamente desde una URL HTTPS con archivo CSV o JSONL a través de RCS y WhatsApp.

• Parámetros:
  • agentId (string, obligatorio): ID único del perfil de agente remitente.
  • recipient (string, condicional): Teléfono del destinatario en formato E.164 (para envío individual).
  • contactsUrl (string, condicional): URL HTTPS pre-firmada a un archivo CSV o JSONL para transmitir contactos con persistencia cero en base de datos.
  • urlFormat (string, opcional): Formato de contactsUrl ("csv" o "jsonl", por defecto "csv").
  • text (string, opcional): Contenido del mensaje de texto.
  • mediaUrl (string, opcional): URL pública del archivo multimedia a enviar.
  • templateId (string, opcional): ID de plantilla preconfigurada.
  • allowSmsFallback (boolean, opcional): Conmutar a SMS si el destinatario no dispone de RCS.
  • suggestions (array de objetos, opcional): Lista de botones interactivos (máximo 4). Cada objeto contiene:
  • type (string, obligatorio): "reply", "url", "phone" o "copy_code".
  • text (string, obligatorio): Etiqueta mostrada en el botón (máx. 25 caracteres).
  • value (string, opcional): Valor de la acción (URL, teléfono, código o carga útil para postback).
• Formato de salida: Objeto de estado que devuelve messageId (envío individual) o broadcastId y status: "streaming" (difusiones remotas).

get_inbox_messages

Recupera los mensajes recientes de la bandeja de entrada y los registros de chat de un perfil de agente.

• Parámetros:
  • agentId (string, obligatorio): Identificador del perfil de agente.
  • limit (number, opcional): Número de mensajes a devolver (máx. 100, por defecto 20).
• Formato de salida: Array de registros de mensajes con id, recipient, content, status y date.

get_conversation_history

Obtiene los mensajes recientes del historial de conversación para un número de teléfono de cliente específico.

• Parámetros:
  • recipient (string, obligatorio): Número de teléfono del cliente en formato E.164.
  • agentId (string, obligatorio): Identificador del perfil de agente.
  • limit (number, opcional): Número de turnos a devolver (por defecto 20).
• Formato de salida: Historial cronológico de interacciones con dirección del mensaje y estado de entrega.

Plantillas de Mensaje

list_templates

Recupera las plantillas de medios enriquecidos, tarjetas, carruseles y texto de un perfil de agente.

• Parámetros:
  • agentId (string, obligatorio): Identificador del perfil de agente.
• Formato de salida: Array de plantillas incluyendo orientación de tarjetas, altura de medios y botones interactivos.

get_template_detail

Obtiene la estructura detallada, orientación y acciones de botones de una plantilla específica.

• Parámetros:
  • templateId (string, obligatorio): Identificador de la plantilla.
  • agentId (string, obligatorio): Identificador del agente.
• Formato de salida: Entidad completa de la plantilla con estructuras de tarjetas y configuraciones de botones.

create_template

Crea una plantilla de mensaje en la biblioteca de la cuenta. Admite tarjetas enriquecidas (imagen, título, texto, botones), carruseles, medios y texto plano. Para WhatsApp, valida automáticamente las reglas de formato de Meta y las envía a revisión en la Meta Graph API.

• Parámetros:
  • name (string, obligatorio): Nombre único de la plantilla (minúsculas, números y guiones bajos).
  • text (string, obligatorio): Contenido del mensaje principal. Admite marcadores de posición como {{customer_name}}.
  • type (string, opcional): "card", "text", "media" o "carousel".
  • title (string, opcional): Titular en negrita para tarjetas.
  • mediaUrl (string, opcional): URL opcional de imagen, vídeo o documento.
  • cardOrientation (string, opcional): "VERTICAL" o "HORIZONTAL".
  • mediaHeight (string, opcional): "SHORT", "MEDIUM" o "TALL".
  • agentId (string, opcional): Agente asociado.
  • category (string, opcional): Categoría de Meta ("MARKETING", "UTILITY", "AUTHENTICATION").
  • language (string, opcional): Código de idioma para WhatsApp, ej. "es_ES", "en_US".
  • footer (string, opcional): Texto de pie de página opcional (máx. 60 caracteres).
  • submitToMeta (boolean, opcional): Para agentes WhatsApp: si se envía a revisión en Meta de inmediato (por defecto true).
  • suggestions (array de objetos, opcional): Botones interactivos (reply, url, phone, copy_code, flow).
• Formato de salida: Objeto de estado con success, templateId, metaTemplateName y metaStatus ("PENDING" o "APPROVED").

Campañas y Difusiones

list_campaigns

Lista las campañas de mensajería recientes con estado de entrega y métricas de rendimiento en tiempo real.

• Parámetros:
  • agentId (string, opcional): Filtrar campañas por perfil de agente remitente.
  • limit (number, opcional): Número máximo de campañas a devolver (por defecto 20, máx. 50).
• Formato de salida: Resumen de campañas con estadísticas en vivo.

get_campaign_status

Consulta el estado de entrega en tiempo real: mensajes enviados, entregados, leídos y fallidos de una campaña o difusión remota.

• Parámetros:
  • campaignId (string, obligatorio): Identificador único de la campaña.
  • agentId (string, opcional): Identificador del agente.
• Formato de salida: Objeto con id, name, status, recipientSource y stats: { sent, delivered, read, failed }.

get_campaign_performance

Recupera el rendimiento analítico detallado de una campaña, incluyendo tasa de entrega, tasa de lectura y clics de destinatarios.

• Parámetros:
  • campaignId (string, obligatorio): Identificador de la campaña.
  • agentId (string, opcional): Identificador del agente.
• Formato de salida: Porcentajes de rendimiento y analítica de interacción.

create_campaign

Crea y despacha una campaña de mensajería masiva orientada a contactos guardados o transmitida en tiempo real desde una URL HTTPS con archivo CSV/JSONL con persistencia cero en base de datos.

• Parámetros:
  • name (string, obligatorio): Nombre descriptivo de la campaña.
  • agentId (string, obligatorio): ID del agente remitente.
  • recipients (array de strings, opcional): Lista de números de teléfono destinatarios.
  • contactsUrl (string, condicional): URL HTTPS pre-firmada con archivo CSV/JSONL para transmitir contactos.
  • urlFormat (string, opcional): Formato de archivo ("csv" o "jsonl").
  • recipientSource (string, opcional): Fuente de audiencia ("contacts" o "remote_url").
  • contactListName (string, opcional): Nombre de lista de contactos guardada.
  • text (string, opcional): Contenido del mensaje principal.
  • templateId (string, opcional): ID de plantilla preconfigurada.
  • flowId (string, opcional): ID de flujo interactivo.
  • sendNow (boolean, opcional): Encola y transmite la difusión inmediatamente (por defecto true).
  • allowSmsFallback (boolean, opcional): Habilitar conmutación a SMS para destinatarios sin RCS.
• Formato de salida: Objeto de estado con campaignId, status: "Sending", recipientSource y channel.

Analítica y Multimedia

get_message_stats

Agrega el volumen de entrega de mensajes en tiempo real, recuentos de fallos y tasas de lectura durante intervalos de tiempo determinados.

• Parámetros:
  • agentId (string, opcional): Identificador del agente.
  • timeRange (string, opcional): "today", "yesterday", "7d" o "30d" (por defecto "today").
• Formato de salida: Métricas agregadas con totales enviados, entregados, leídos, fallidos y porcentaje de entrega.

search_images

Busca imágenes libres de derechos en la biblioteca multimedia del espacio de trabajo y en proveedores externos según un término de búsqueda.

• Parámetros:
  • query (string, obligatorio): Término de búsqueda (ej. "café", "rebajas de verano").
• Formato de salida: Array de objetos de imagen con URLs, previsualizaciones y dimensiones.

messages://inbox

La bandeja de entrada del espacio de trabajo contiene la lista de los 20 mensajes más recientes (respuestas entrantes de clientes y mensajes salientes).

• Tipo MIME: application/json
• Formato: Array JSON con detalles del mensaje: id, recipient, content, status y date.

Notificaciones de Actualización en Tiempo Real

Los agentes cliente MCP conectados pueden suscribirse al recurso messages://inbox:

1. Cuando un contacto responde (ej. pulsa un botón de respuesta rápida), el operador entrega la respuesta a RubiConnect.
2. El Servidor MCP envía de inmediato una notificación JSON-RPC notifications/resources/updated con el parámetro uri: "messages://inbox" sobre el flujo activo SSE.
3. El agente de IA cliente recibe la notificación y puede ejecutar resources/read para obtener la nueva respuesta y continuar la conversación interactivamente.

Salesforce Agentforce y Einstein Copilot

Salesforce Einstein y Agentforce admiten la conexión a servicios API externos para ejecutar herramientas.

1. Named Credentials: Configura una Named Credential en Salesforce Setup apuntando a https://console.rubiconnect.com/api/mcp y especifica el encabezado X-Rubi-Key.
2. Apex Action Bridge: Implementa una clase Apex que gestione la conexión SSE y traduzca las peticiones JSON-RPC, exponiéndolas como Einstein Copilot Actions.
3. Activación: Einstein Copilot puede ejecutar dinámicamente send_message o create_campaign cuando los comerciales interactúan con el asistente (ej. "Envía el folleto de precios vía RCS al cliente potencial").

HubSpot Breeze y Agentes de IA

Los agentes de IA de HubSpot pueden utilizar extensiones personalizadas de flujo de trabajo para consultar y activar mensajes externos.

1. Acciones personalizadas: Registra una Custom Workflow Action en el portal de desarrolladores de HubSpot apuntando a nuestra ruta de API.
2. Automatización: Cuando se dispara un evento en HubSpot (ej. el estado del contacto cambia a "Contactado"), el agente HubSpot Breeze procesa los datos y ejecuta send_message en RubiConnect para enviar una introducción interactiva.

Agentes de IA de Shopify y Shopify Flow

Las tiendas Shopify pueden utilizar agentes de atención al cliente con IA (creados sobre OpenAI Assistants o flujos LangChain) para automatizar comunicaciones transaccionales.

1. Detección de eventos: El agente de IA detecta un carrito abandonado o un evento de confirmación de pedido.
2. Invocación: El agente ejecuta send_message para enviar la actualización del pedido o un código de descuento directamente al móvil del cliente vía RCS.