Supovia MCP

Gerencie sites, documentos de ajuda, campanhas e conversas de suporte ao cliente com ferramentas seguras, com escopo organizacional, e visualizações interativas.

Ver em supovia.com

Documentação

Tudo o que você precisa para integrar a Supovia ao seu produto: um widget de chat completo ou um mascote compacto, uma API JavaScript, API REST e webhooks, um servidor MCP e suporte para seu próprio agente de IA.

Widget

Instale o widget de chat

Cole este trecho logo antes da tag de fechamento do body em todas as páginas onde deseja o widget de chat. Substitua YOUR_WEBSITE_ID pelo id do seu painel da 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 JavaScript

Quando o widget carrega, ele expõe uma fila de comandos em window.$supovia. Envie um array de [comando,...argumentos] para chamá-lo. Comandos enfileirados antes do carregamento do widget são executados assim que ele estiver pronto.

// 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 o visitante autenticado para que suas conversas o acompanhem.
  • setUserEmail(email, signature)Associa o endereço de e-mail do visitante à conversa.
  • setUserNickname(name)Define um nome de exibição para o visitante.
  • setUserPhone(phone)Associa o número de telefone do visitante.
  • setMetadata(key, value)Armazena qualquer atributo extra na conversa.
  • addReadable(readable)Expõe o contexto ao vivo da página que o agente de IA pode ler.
  • removeReadable(readable)Remove um trecho de contexto legível.
  • addAction(action)Registra uma ação que o agente de IA pode oferecer para executar.
  • removeAction(action)Remove uma ação previamente registrada.
  • openChat() / closeChat()Abre ou fecha a janela de chat.
  • showChat() / hideChat()Mostra ou oculta o lançador de chat completamente.
  • sendMessage(content)Envia uma mensagem para a conversa em nome do visitante.
  • searchDocuments(query, locale)Busca seus documentos de ajuda publicados a partir da página.
  • setBrandColor(color)Substitui a cor da marca do widget em tempo de execução.

Mascote

Use um mascote em vez do widget completo

O mascote é uma superfície de conversa alternativa da Supovia para produtos web e nativos. Ele flutua com apenas a mensagem mais recente visível; passar o mouse, focar ou tocar revela a conversa recente e um campo de resposta. A Supovia é responsável pelo comportamento do chat enquanto você fornece a arte do mascote do produto.

<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>

Assine a identidade do visitante no seu servidor

O terceiro argumento de setUserId é um HMAC-SHA256 hexadecimal em minúsculas da string exata do ID do usuário. Gere-o somente após autenticar esse usuário no seu servidor. Mantenha o segredo de identidade no armazenamento secreto do lado do servidor e compartilhe-o apenas com o agente confiável que verifica a identidade; nunca o coloque em JavaScript, HTML ou em um pacote móvel.

// 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.

A arte do mascote é um atlas PNG ou WebP transparente de 1536×2288: 8 colunas por 11 linhas de células de 192×208. As linhas 0–8 são ocioso, correndo para a direita, correndo para a esquerda, acenando, pulando, falhou, esperando, correndo e revisão. As linhas 9–10 contêm 16 direções de olhar no sentido horário em passos de 22,5 graus, começando de cima. Defina spriteVersionNumber como 2 no manifesto do mascote. O mascote consome a mesma fila de comandos window.$supovia que o widget, então identidade, metadados, contexto legível, ações e mensagens programáticas funcionam com qualquer superfície.

API REST

API REST e chaves de API

Experimente a API sem credenciais

Nenhuma autenticação é necessária, e o sandbox ao vivo não precisa de chave de API. Ele retorna documentos de ajuda de demonstração determinísticos no mesmo formato JSON que leituras autenticadas, e cada resposta inclui cabeçalhos RateLimit reais.

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

Abra o sandbox da API Supovia sem chave ou crie uma conta gratuita por meio do cadastro self-serve sem aprovação de vendas. Crie uma conta gratuita na Supovia.

Use dados da organização

Leia e escreva seu espaço de trabalho da Supovia a partir do seu próprio backend. Crie uma chave de API no painel e autentique com HTTP Basic auth, enviando o segredo da chave codificado em base64 no cabeçalho Authorization.

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

Cada chave carrega escopos por recurso, então você pode conceder acesso somente leitura ou leitura e escrita recurso por recurso e manter cada integração com privilégio mínimo por padrão.

Explore a referência completa da API — cada endpoint com seus parâmetros, corpo da solicitação, respostas e escopo necessário.

CLI

Interface de linha de comando

Os mesmos documentos de ajuda, conversas, clientes e sites estão disponíveis no seu terminal por meio do CLI da supovia. Instale-o globalmente com npm ou execute-o ad hoc com npx.

A autenticação é um único comando: supovia login abre seu navegador para entrar na sua conta da Supovia e armazena uma sessão para comandos futuros — sem chave de API para colar.

# 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

O CLI é open source em github.com/supovia/cli e publicado como supovia no npm. Execute qualquer comando com --help para ver suas opções.

Webhooks

Webhooks

Assine eventos e a Supovia os enviará via POST para o seu servidor conforme ocorrem, incluindo message.created, conversation.created e customer.created.

Cada solicitação carrega um cabeçalho X-Supovia-Signature no formato t=timestamp,v1=signature. A assinatura é um HMAC-SHA256 de timestamp.body com chave do seu segredo de assinatura; recalcule-a e compare antes de confiar no payload.

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

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

Servidor MCP

Conecte Claude, ChatGPT ou qualquer cliente MCP

A Supovia fala o Model Context Protocol sobre Streamable HTTP. Adicione a URL de produção abaixo como um conector personalizado no Claude ou ChatGPT, depois entre na Supovia e escolha a organização que deseja autorizar. Cada solicitação permanece dentro dessa organização.

# 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."

O conector expõe doze ferramentas de leitura e duas ferramentas de escrita restritas. Ele pode resumir sites e carga de trabalho de suporte, contar cada conversa não resolvida em resultados paginados, buscar e ler documentos de ajuda, inspecionar campanhas sem enviá-las e abrir visualizações interativas de visão geral de suporte, caixa de entrada somente metadados e atividade de conversa.

Identidades de clientes, notas internas, IDs de funcionários, credenciais, prompts de agentes, metadados arbitrários, corpos de mensagens, visualizações e IDs de mensagens são excluídos tanto dos resultados do modelo quanto dos aplicativos incorporados. As visualizações de caixa de entrada e conversa recebem apenas campos seguros de status, não lido, timestamp e atividade agregada.

As únicas escritas são enviar uma resposta exata do operador e alterar o estado resolvido de uma conversa. Ambas são marcadas como escritas destrutivas para que o host possa pedir confirmação. O envio não é idempotente e não deve ser repetido após um resultado ambíguo; resolver ou reabrir é idempotente e não altera nenhum outro campo da conversa.

Use outro cliente MCP

Não há nada para instalar e nenhuma chave de API para colar. Clientes MCP remotos usam a mesma URL; clientes que suportam apenas entrada e saída padrão locais podem fazer a ponte com 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

A autenticação usa OAuth 2.0 com registro dinâmico de cliente e PKCE, então os clientes se registram sozinhos e você nunca copia um ID ou segredo de cliente. A Supovia usa o mesmo servidor de autorização que nossos outros produtos, então a tela de aprovação pode listar escopos para mais de um produto; a declaração de produto do token assinado ainda fixa esta conexão à Supovia. Desconecte-a no seu host MCP ou revogue a conexão da sua conta sempre que quiser remover o acesso.

Plugins de Agente

Instale a Supovia como um plugin portátil

O padrão aberto Agent Plugins empacota o servidor MCP da Supovia e sua habilidade de operações de suporte juntos. Instale um repositório e seu agente aprende o fluxo de trabalho de suporte seguro para privacidade, conecta-se às ferramentas remotas e envia você pelo mesmo fluxo de aprovação OAuth da Supovia — nenhuma chave de API ou segredo de cliente está incluído no 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

O repositório inclui os manifestos portáteis plugin.json e mcp.json, além de adaptadores nativos para Claude, Gemini CLI e Google Antigravity. O pacote portátil também é o artefato de submissão para Kiro Powers, o Cursor Marketplace e o Awesome Copilot.

Agentes e registros podem descobrir o mesmo pacote a partir do manifesto conhecido do Agent Plugin ou do Catálogo de IA da Supovia.

Habilidades de Agente

Ensine seu agente de codificação sobre a Supovia

A Supovia oferece Agent Skills — guias que seguem o padrão agentskills.io e ensinam agentes de codificação a executar operações de suporte com o CLI da supovia e o conector MCP, em vez de adivinhar comandos e ferramentas.

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

Um único comando instala as habilidades no Claude Code, Cursor, Codex, Gemini CLI e qualquer outro agente que siga o padrão Skills. O CLI também inclui os mesmos guias, com versão correspondente aos comandos que ele envia: supovia skills get <name> imprime um sob demanda.

As habilidades são open source em github.com/supovia/skills. Usuários do Claude também podem instalar o plugin Supovia Claude, que agrupa o conector junto com a habilidade de operações de suporte: github.com/supovia/claude-plugin.

Agente de IA

Traga seu próprio agente de IA

Prefere executar sua própria IA? Defina uma URL de agente no seu site e a Supovia a chama pelo protocolo aberto AG-UI, transmitindo a resposta de volta para a conversa conforme é gerada. Seu agente pode usar quaisquer modelos, prompts, ferramentas e dados que desejar.

A Supovia autentica cada solicitação ao seu endpoint com um segredo bearer, então apenas seu agente é chamado. O protocolo AG-UI é um padrão aberto, então você pode reutilizar um agente existente sem escrever um adaptador específico da Supovia.

Comece a construir