Configuración del MCP

El Model Context Protocol (MCP) de Caramelo AI es un estándar abierto que permite conectar asistentes de Inteligencia Artificial (como Claude Desktop, ChatGPT y Gemini) directamente a los datos de su proyecto de forma segura y en tiempo real.

Con esta integración, la IA de su elección adquiere la capacidad de consultar y analizar métricas, leads, conversaciones y el rendimiento de sus campañas de forma autónoma.

🚀 Cómo acceder al panel MCP

1. Acceda al Panel de Administración de Caramelo AI.
2. Navegue hasta su proyecto.
3. En el menú lateral, acceda a Integraciones.
4. En la tarjeta Model Context Protocol (MCP), haga clic en Gestionar.

En esta página, encontrará su URL de Conexión exclusiva del proyecto, la lista de conexiones OAuth activas y la sección Claves de API de MCP.

[!IMPORTANT] Claves de API exclusivas para MCP: Para clientes que utilizan autenticación estática (como Claude Desktop o Cursor), debe generar una clave de MCP (mak_...) en esta pantalla. Las claves generales de API del proyecto (sak_... o cak_...) serán rechazadas estrictamente por el servidor de MCP por razones de seguridad.

⚙️ Instrucciones de Configuración por Cliente

La URL de conexión de su proyecto tiene el siguiente formato estándar: https://mcp.carameloai.com/mcp/projects/<PROJECT_ID>

Parâmetros de URL Disponibles

Para ampliar la compatibilidad con diferentes clientes y CLIs, puede añadir parámetros de consulta a la URL de conexión:

• ?json=true (or ?jsonResponse=true): Fuerza al servidor a responder a las peticiones POST en formato application/json en lugar de text/event-stream. Útil para clientes que no admiten la lectura de paquetes SSE en las respuestas de peticiones POST.
• Detección y Soporte Automático: El servidor detecta y negocia dinámicamente conexiones del estándar oficial SSE o conexiones heredadas del borrador Streamable HTTP (enviados por CLIs como agy o clientes en Go), proporcionando soporte retrocompatible bajo la misma URL.

🔵 Cursor / Antigravity IDE (Conexión SSE Directa)

Si está utilizando un editor o IDE con soporte nativo para conexiones MCP a través de SSE/HTTP (como Cursor o Antigravity IDE):

1. Agregue un nuevo servidor MCP en la configuración de su IDE.
2. Seleccione el tipo de transporte como SSE (o use la propiedad "serverUrl" en el archivo de configuración del agente).
3. Ingrese su URL de Conexión exclusiva obtenida del panel: https://mcp.carameloai.com/mcp/projects/SU_PROJECT_ID
4. Configure los encabezados de autorización pasando la clave mak_ generada en el panel. Ejemplo en el archivo mcp_config.json:

{
  "mcpServers": {
    "caramelo-vendedor": {
      "serverUrl": "https://mcp.carameloai.com/mcp/projects/SU_PROJECT_ID",
      "headers": {
        "Authorization": "Bearer mak_SU_CLAVE_MCP_AQUI"
      }
    }
  }
}

🟣 Claude Desktop (Puente de Conexión stdio vía Supergateway)

Dado que Claude Desktop nativamente solo admite servidores locales a través de stdio (entrada/salida estándar), debe utilizar un puente para convertir la conexión SSE de nuestro servidor en stdio local. Para ello, utilizamos la herramienta supergateway proporcionando la clave mak_ correspondiente.

1. Abra o cree el archivo de configuración de Claude Desktop en su sistema operativo:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Inserte la siguiente estructura bajo la clave mcpServers (reemplazando la URL y la clave mak_ por sus credenciales copiadas del Dashboard):

{
	"mcpServers": {
		"caramelo-vendedor": {
			"command": "npx",
			"args": [
				"-y",
				"supergateway",
				"--sse",
				"https://mcp.carameloai.com/mcp/projects/SU_PROJECT_ID",
				"--oauth2Bearer",
				"mak_SU_CLAVE_MCP_AQUI"
			]
		}
	}
}

3. Reinicie Claude Desktop. Aparecerá un icono de enchufe (plug) en el chat indicando que las herramientas se han cargado.

🟢 ChatGPT (Custom GPTs / Connectors)

ChatGPT admite la integración remota con el flujo de autorización automática (OAuth 2.1) y el registro dinámico.

1. En ChatGPT, acceda a Explore GPTs -> Create GPT.
2. En la pestaña Configure, desplácese hasta Actions y haga clic en Create new action.
3. En la sección de Autenticación, seleccione OAuth y complete la configuración utilizando la URL base de conexión obtenida en el panel. ChatGPT realizará el autorregistro (DCR) en nuestro servidor.
4. Cuando el usuario interactúe con el Custom GPT por primera vez, será redirigido a la pantalla de inicio de sesión y consentimiento de Caramelo AI.
5. Tras aprobar, la conexión se establecerá y aparecerá listada en las Conexiones Activas de su panel.

🔵 Gemini CLI / Clientes compatibles con SSE

Para herramientas CLI o clientes personalizados que utilizan transporte a través de Server-Sent Events (SSE):

• Configure el cliente apuntando a la URL de conexión HTTP de su proyecto.
• El cliente MCP recibirá un desafío 401 Unauthorized con el encabezado WWW-Authenticate que contiene la información de la pantalla de consentimiento.
• Siga las instrucciones del cliente para completar la autenticación en el navegador.

📊 Herramientas Disponibles para la IA

Una vez conectado, el asistente de IA podrá activar las siguientes herramientas (tools) cuando lo solicite en el chat:

📁 Proyectos y Cuentas

• list_projects: Lista todos los proyectos disponibles en la cuenta para localizar identificadores rápidamente.
• get_account_subscription: Recupera datos sobre el plan de suscripción actual.

👥 Clientes y Leads

• search_customers: Permite realizar búsquedas textuales de contactos en la base de clientes (nombre, correo electrónico, teléfono, etc.).
• get_lead_funnel: Muestra la distribución de los leads en las etapas del embudo de ventas (CRM).
• get_funnel_transitions: Devuelve las tasas de conversión y la duración promedio de los leads en cada etapa del pipeline de ventas.

📈 Métricas y Rendimiento

• get_chatbot_metrics: Devuelve métricas agregadas de rendimiento del chatbot (tasas de conversión, desbordamiento a humanos, costos y sentimientos).
• get_live_metrics: Obtiene métricas en tiempo real de las interacciones y mensajes en las últimas horas (conversaciones activas, cola de espera, desbordamientos).
• get_daily_usage: Presenta el consumo diario de recursos y tokens en el proyecto para el seguimiento de límites.
• get_usage_insights: Proporciona información consolidada sobre el volumen de uso en la cuenta (tokens consumidos, llamadas a la API, tareas, etc.).

💬 Conversaciones y Atención

• list_chatbots: Lista todos los chatbots configurados en el proyecto.
• read_conversation: Permite a la IA visualizar el historial completo de mensajes de una conversación específica para analizar el contexto de la atención.
• list_conversations: Lista las conversaciones (hilos) del proyecto con soporte para filtros de estado, sentimiento, etc.
• get_failed_conversations: Identifica y lista conversaciones con bajo compromiso, sentimiento negativo o insatisfacción del usuario.

🔧 Diagnósticos y Logs (v1.2)

• get_chatbot: Obtiene la configuración detallada de prompts, personas y herramientas de un chatbot.
• get_tool_execution_logs: Recupera los registros de ejecución de herramientas y APIs del chatbot para el diagnóstico de fallas de integración.
• get_nlp_insights: Devuelve información consolidada de las intenciones de los usuarios y las preguntas no respondidas.

🤖 Ciclo de Vida del Chatbot (Mutación - v1.3)

• create_chatbot: Crea un nuevo chatbot en el proyecto con una versión de borrador inicial.
• get_chatbot_draft: Obtiene la configuración del borrador actual de un chatbot.
• edit_chatbot_draft: Permite editar propiedades de configuración del borrador de un chatbot.
• generate_chatbot_test_url: Crea una URL temporal para probar y previsualizar el borrador del chatbot.
• publish_chatbot_draft: Promueve el borrador del chatbot a producción, generando una nueva versión activa.

🔒 Seguridad y Control

[!IMPORTANT] Aislamiento de Datos: Cada conexión está estrictamente vinculada al proyecto seleccionado. El asistente no puede visualizar datos de otros proyectos sin una nueva autorización explícita.

[!TIP] Revogación Instantánea: Si pierde el acceso al dispositivo o desea finalizar la conexión de un asistente de IA, vaya a la sección Conexiones Activas en la página de MCP en el panel y haga clic en Revocar al lado de la conexión correspondiente. El token se invalidará de inmediato.

[!WARNING] Límites de Petición (Rate Limiting): Para garantizar la estabilidad de la plataforma, cada proyecto tiene un límite de 30 peticiones por minuto al servidor MCP.

🙋 Preguntas Frecuentes (FAQ)