Supovia MCP

Gestiona sitios web, documentos de ayuda, campañas y conversaciones de soporte al cliente con herramientas seguras y vistas interactivas limitadas a la organización.

Ver en supovia.com

Documentación

Todo lo que necesitas para conectar Supovia a tu producto: un widget de chat completo o una mascota compacta, una API de JavaScript, API REST y webhooks, un servidor MCP y soporte para tu propio agente de IA.

Widget

Instala el widget de chat

Pega este fragmento justo antes de la etiqueta de cierre del body en cada página donde quieras el widget de chat. Reemplaza YOUR_WEBSITE_ID con el id de tu panel de Supovia.

<script>
  window.SUPOVIA_WEBSITE_ID = "YOUR_WEBSITE_ID";
  (function () {
    window.$supovia = window.$supovia || [];
    var d = document;
    var s = d.createElement('script');
    s.src = 'https://widget.supovia.com/widget.js';
    s.async = 1;
    d.getElementsByTagName('head')[0].appendChild(s);
  })();
</script>

API de JavaScript

Una vez que el widget se ha cargado, expone una cola de comandos en window.$supovia. Envía un arreglo de [comando,...argumentos] para llamarlo. Los comandos en cola antes de que el widget se cargue se ejecutan tan pronto como esté listo.

// Identify the signed-in visitor
window.$supovia.push(['setUserId', 'user-123']);
window.$supovia.push(['setUserEmail', 'jane@example.com']);

// Attach context for your team and the AI agent
window.$supovia.push(['setMetadata', 'plan', 'pro']);
window.$supovia.push(['addReadable', {
  userId: 'user-123',
  description: 'Current cart total',
  value: '$84.00',
}]);

// Give the AI an action it can trigger
window.$supovia.push(['addAction', {
  userId: 'user-123',
  name: 'refundOrder',
  description: 'Refund the customer last order',
}]);

// Control the widget from your own UI
window.$supovia.push(['openChat']);
window.$supovia.push(['sendMessage', 'Hi, I need help with my order']);

Comandos

  • setUserId(id, signature)Identifica al visitante con sesión iniciada para que sus conversaciones lo sigan.
  • setUserEmail(email, signature)Adjunta la dirección de correo del visitante a la conversación.
  • setUserNickname(name)Establece un nombre para mostrar para el visitante.
  • setUserPhone(phone)Adjunta el número de teléfono del visitante.
  • setMetadata(key, value)Almacena cualquier atributo adicional en la conversación.
  • addReadable(readable)Expone el contexto de la página en vivo que el agente de IA puede leer.
  • removeReadable(readable)Elimina una pieza de contexto legible.
  • addAction(action)Registra una acción que el agente de IA puede ofrecer ejecutar.
  • removeAction(action)Elimina una acción previamente registrada.
  • openChat() / closeChat()Abre o cierra la ventana de chat.
  • showChat() / hideChat()Muestra u oculta el lanzador de chat por completo.
  • sendMessage(content)Envía un mensaje a la conversación en nombre del visitante.
  • searchDocuments(query, locale)Busca tus documentos de ayuda publicados desde la página.
  • setBrandColor(color)Anula el color de marca del widget en tiempo de ejecución.

Mascota

Usa una mascota en lugar del widget completo

La mascota es una superficie de conversación alternativa de Supovia para productos web y nativos. Flota mostrando solo el último mensaje; al pasar el cursor, enfocar o tocar, se revela la conversación reciente y un campo de respuesta. Supovia gestiona el comportamiento del chat mientras tú proporcionas el arte de la mascota del producto.

<script>
  window.SUPOVIA_MASCOT = {
    websiteId: 'YOUR_WEBSITE_ID',
    brandColor: '#386FA4',
    pet: {
      id: 'your-pet',
      name: 'Your assistant',
      spritesheet: 'https://your-cdn.com/your-pet.webp',
    },
  };

  window.$supovia = window.$supovia || [];
  window.$supovia.push([
    'setUserId',
    'user-123',
    'SERVER_MINTED_USER_SIGNATURE',
  ]);
</script>
<script async src="https://mascot.supovia.com/mascot.js"></script>

Firma la identidad del visitante en tu servidor

El tercer argumento de setUserId es un HMAC-SHA256 hexadecimal en minúsculas de la cadena exacta del ID de usuario. Genéralo solo después de autenticar a ese usuario en tu servidor. Mantén el secreto de identidad en almacenamiento secreto del lado del servidor y compártelo solo con el agente de confianza que verifica la identidad; nunca lo coloques en JavaScript, HTML o un paquete móvil.

// Run on your server after authenticating this user.
import { createHmac } from 'node:crypto';

const userId = String(authenticatedUser.id);
const signature = createHmac(
  'sha256',
  process.env.YOUR_PRODUCT_IDENTITY_SECRET,
)
  .update(userId, 'utf8')
  .digest('hex');

// Return only { userId, signature } to the browser. Never return the secret.

El arte de la mascota es un atlas PNG o WebP transparente de 1536×2288: 8 columnas por 11 filas de celdas de 192×208. Las filas 0–8 son inactiva, corriendo a la derecha, corriendo a la izquierda, saludando, saltando, fallida, esperando, corriendo y revisión. Las filas 9–10 contienen 16 direcciones de mirada en el sentido de las agujas del reloj en pasos de 22.5 grados, comenzando hacia arriba. Establece spriteVersionNumber en 2 en el manifiesto de la mascota. La mascota consume la misma cola de comandos window.$supovia que el widget, por lo que identidad, metadatos, contexto legible, acciones y mensajes programáticos funcionan con cualquiera de las dos superficies.

API REST

API REST y claves de API

Prueba la API sin credenciales

No se requiere autenticación, y el sandbox en vivo no necesita clave de API. Devuelve documentos de ayuda deterministas de demostración con la misma forma JSON que las lecturas autenticadas, y cada respuesta incluye encabezados RateLimit reales.

curl https://api.supovia.com/api/sandbox/documents

Abre el sandbox de API de Supovia sin clave o crea una cuenta gratuita mediante el registro de autoservicio sin aprobación de ventas. Crea una cuenta gratuita de Supovia.

Usa datos de la organización

Lee y escribe tu espacio de trabajo de Supovia desde tu propio backend. Crea una clave de API en el panel y autentícate con autenticación básica HTTP, enviando el secreto de la clave codificado en base64 en el encabezado Authorization.

curl https://api.supovia.com/... \
  -H "Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)"

Cada clave tiene alcances por recurso, por lo que puedes otorgar acceso de solo lectura o de lectura y escritura recurso por recurso y mantener cada integración con privilegios mínimos por defecto.

Explora la referencia completa de la API — cada endpoint con sus parámetros, cuerpo de solicitud, respuestas y alcance requerido.

CLI

Interfaz de línea de comandos

Los mismos documentos de ayuda, conversaciones, clientes y sitios web están disponibles desde tu terminal a través de la CLI de supovia. Instálala globalmente con npm, o ejecútala ad hoc con npx.

La autenticación es un solo comando: supovia login abre tu navegador para iniciar sesión en tu cuenta de Supovia y almacena una sesión para comandos posteriores — sin necesidad de pegar una clave de API.

# Install once, globally
npm install -g supovia
# or run it ad hoc without installing
npx supovia --help

# Log in — opens your browser to sign in and stores a session
supovia login

# The websites (support workspaces) in your account
supovia websites list

# The newest support conversations, then one full thread
supovia conversations list
supovia conversations read CONVERSATION_ID

# List and read your help-center documents
supovia docs list
supovia docs read how-to-install-the-widget

La CLI es de código abierto en github.com/supovia/cli y se publica como supovia en npm. Ejecuta cualquier comando con --help para ver sus opciones.

Webhooks

Webhooks

Suscríbete a eventos y Supovia los enviará por POST a tu servidor a medida que ocurran, incluyendo message.created, conversation.created y customer.created.

Cada solicitud lleva un encabezado X-Supovia-Signature con la forma t=timestamp,v1=signature. La firma es un HMAC-SHA256 de timestamp.body con tu secreto de suscripción; recalcúlala y compárala antes de confiar en el payload.

POST https://your-server.com/supovia-webhook

{
  "event": "message.created",
  "timestamp": 1719000000,
  "data": { "...": "..." }
}

Servidor MCP

Conecta Claude, ChatGPT o cualquier cliente MCP

Supovia habla el Protocolo de Contexto de Modelo (MCP) sobre HTTP Streamable. Agrega la URL de producción a continuación como conector personalizado en Claude o ChatGPT, luego inicia sesión en Supovia y elige la organización que deseas autorizar. Cada solicitud permanece dentro de esa organización.

# Add Supovia as a custom connector in Claude or ChatGPT
# Remote MCP server URL
https://mcp.supovia.com/mcp

# Sign in to Supovia when your host asks you to connect.
# Example prompts:
"Count every unresolved conversation and group them by website."
"Find and read the best help article for installing the Supovia widget."
"Open my private Supovia inbox and show only the unread count."

El conector expone doce herramientas de lectura y dos herramientas de escritura limitadas. Puede resumir sitios web y la carga de trabajo de soporte, contar cada conversación sin resolver en resultados paginados, buscar y leer documentos de ayuda, inspeccionar campañas sin enviarlas, y abrir vistas interactivas de resumen de soporte, bandeja de entrada solo con metadatos y actividad de conversación.

Las identidades de clientes, notas internas, IDs de personal, credenciales, prompts de agentes, metadatos arbitrarios, cuerpos de mensajes, vistas previas e IDs de mensajes se excluyen tanto de los resultados del modelo como de las aplicaciones integradas. Las vistas de bandeja de entrada y conversación reciben solo campos seguros de estado, no leídos, marca de tiempo y actividad agregada.

Las únicas escrituras son enviar una respuesta exacta de operador y cambiar el estado de resolución de una conversación. Ambas están marcadas como escrituras destructivas para que el host pueda pedir confirmación. El envío no es idempotente y no debe reintentarse después de un resultado ambiguo; resolver o reabrir es idempotente y no cambia ningún otro campo de la conversación.

Usa otro cliente MCP

No hay nada que instalar ni clave de API que pegar. Los clientes MCP remotos usan la misma URL; los clientes que solo admiten entrada y salida estándar local pueden conectarse con mcp-remote.

# Any MCP client that supports remote servers uses the same URL:
https://mcp.supovia.com/mcp

# Codex CLI
codex mcp add supovia --url https://mcp.supovia.com/mcp
codex mcp login supovia

# VS Code
code --add-mcp '{"name":"supovia","type":"http","url":"https://mcp.supovia.com/mcp"}'

# Cursor, Windsurf and other editors: add to their MCP config file
{
  "mcpServers": {
    "supovia": {
      "type": "http",
      "url": "https://mcp.supovia.com/mcp"
    }
  }
}

# Clients that only support local (stdio) servers can bridge:
npx mcp-remote https://mcp.supovia.com/mcp

La autenticación usa OAuth 2.0 con registro dinámico de clientes y PKCE, por lo que los clientes se registran solos y nunca copias un ID o secreto de cliente. Supovia usa el mismo servidor de autorización que nuestros otros productos, por lo que la pantalla de aprobación puede listar alcances para más de un producto; la declaración de producto del token firmado aún fija esta conexión a Supovia. Desconéctalo en tu host MCP o revoca la conexión desde tu cuenta cuando quieras eliminar el acceso.

Plugins de Agente

Instala Supovia como un plugin portátil

El estándar abierto Agent Plugins empaqueta el servidor MCP de Supovia y su habilidad de operaciones de soporte juntos. Instala un repositorio y tu agente aprende el flujo de trabajo de soporte seguro para la privacidad, se conecta a las herramientas remotas y te envía a través del mismo flujo de aprobación OAuth de Supovia — sin clave de API ni secreto de cliente incluido en el plugin.

# Portable Agent Plugins package (Kiro, Cursor, Copilot-compatible hosts)
https://github.com/supovia/claude-plugin

# Gemini CLI
gemini extensions install https://github.com/supovia/claude-plugin

# Google Antigravity uses its native adapter from the same repository
git clone https://github.com/supovia/claude-plugin.git
agy plugin install ./claude-plugin/com.google.antigravity

El repositorio incluye los manifiestos portátiles plugin.json y mcp.json, además de adaptadores nativos para Claude, Gemini CLI y Google Antigravity. El paquete portátil también es el artefacto de envío para Kiro Powers, el Marketplace de Cursor y Awesome Copilot.

Los agentes y registros pueden descubrir el mismo paquete desde el manifiesto conocido de Agent Plugin o desde el Catálogo de IA de Supovia.

Habilidades de Agente

Enseña a tu agente de codificación sobre Supovia

Supovia incluye Agent Skills — guías que siguen el estándar agentskills.io que enseñan a los agentes de codificación cómo ejecutar operaciones de soporte con la CLI de supovia y el conector MCP, en lugar de adivinar comandos y herramientas.

# Install the Supovia skills into your coding agent
npx skills add supovia/skills

Un solo comando instala las habilidades en Claude Code, Cursor, Codex, Gemini CLI y cualquier otro agente que siga el estándar de Skills. La CLI también incluye las mismas guías, con versiones coincidentes con los comandos que envía: supovia skills get <name> imprime una bajo demanda.

Las habilidades son de código abierto en github.com/supovia/skills. Los usuarios de Claude también pueden instalar el plugin de Claude de Supovia, que agrupa el conector junto con la habilidad de operaciones de soporte: github.com/supovia/claude-plugin.

Agente de IA

Trae tu propio agente de IA

¿Prefieres ejecutar tu propia IA? Establece una URL de agente en tu sitio web y Supovia la llama a través del protocolo abierto AG-UI, transmitiendo la respuesta de vuelta a la conversación a medida que se genera. Tu agente puede usar cualquier modelo, prompt, herramienta y datos que desees.

Supovia autentica cada solicitud a tu endpoint con un secreto bearer, por lo que solo se llama a tu agente. El protocolo AG-UI es un estándar abierto, por lo que puedes reutilizar un agente existente sin escribir un adaptador específico de Supovia.

Empieza a construir