Conector MCP da AlterVision 🤖

O que é

O conector oficial da AlterVision dá ao seu assistente de IA acesso somente leitura aos indicadores das suas lojas físicas, permitindo que você pergunte em linguagem natural sobre fluxo de visitantes, conversão, metas, corridas e motivos de não conversão — sem abrir o painel nem montar relatório.

Ele é um servidor MCP (Model Context Protocol), o protocolo aberto que padroniza como assistentes de IA acessam ferramentas e dados externos. Qualquer cliente compatível com MCP pode usá-lo — Claude e ChatGPT, entre outros.

URL do servidor	https://api.painelalter.com/mcp
Transporte	Streamable HTTP
Autenticação	OAuth 2.1 com PKCE e client ID metadata documents (CIMD)
Tela de consentimento	https://painelalter.com/mcp/authorize
Ferramentas	9, todas somente leitura
Compatibilidade	Qualquer cliente MCP com suporte a HTTP remoto e OAuth

Somente leitura

Todas as ferramentas do conector apenas consultam informações. Nenhuma escreve, altera ou apaga dado no PainelAlter.

Pré-requisitos

• Conta AlterVision ativa no painelalter.com.
• Acesso a pelo menos uma loja.
• Para parte das ferramentas, lojas com o produto AlterVez ativo — veja a Referência das ferramentas.

Lojas sem AlterVez

As ferramentas de corridas, motivos de não conversão e transcrições só reportam lojas com AlterVez ativo. Uma loja sem AlterVez é silenciosamente excluída do resultado — não gera erro. Se você espera ver uma loja e ela não aparece nessas respostas, é provável que ela não tenha o produto ativo.

Como conectar

O passo a passo muda de cliente para cliente, mas em todos eles é o mesmo procedimento: adicionar um conector remoto informando a URL do servidor. Não há registro prévio nem chave de API para gerar — ao adicionar o conector, o fluxo OAuth inicia sozinho.

https://api.painelalter.com/mcp

No Claude

1. Abra Configurações → Conectores.
2. Escolha adicionar conector personalizado.
3. Cole a URL do servidor.
4. O Claude abre a tela de consentimento em https://painelalter.com/mcp/authorize. Entre com as credenciais do seu painel AlterVision.
5. Aprove o acesso. O conector fica disponível nas suas conversas.

TODO

Incluir os screenshots de cada passo no Claude (Configurações → Conectores, campo da URL, tela de consentimento do PainelAlter e tela de aprovação).

No ChatGPT

O ChatGPT permite adicionar conectores MCP remotos nas configurações de conectores. Depois de informar a URL do servidor, o restante do fluxo é idêntico: a tela de consentimento do PainelAlter abre, você entra com suas credenciais e aprova o acesso.

TODO

Confirmar e descrever o caminho exato na interface atual do ChatGPT (planos em que o recurso está disponível, nome do menu e se é necessário algum modo de desenvolvedor), e incluir os screenshots correspondentes.

Em outros clientes MCP

Qualquer cliente com suporte a servidores MCP remotos via HTTP e autenticação OAuth pode usar o conector. Informe a URL do servidor no formato que o cliente pedir e conclua o login na tela de consentimento do PainelAlter.

Independente do cliente

O conector não depende de nenhum assistente específico: as mesmas 9 ferramentas, o mesmo escopo de dados e o mesmo fluxo de autenticação valem para todos os clientes.

O token gerado dá acesso exatamente às lojas que você já enxerga no painel — nem mais, nem menos.

O que dá para perguntar

Você não precisa saber o nome das ferramentas nem os ids das lojas: pergunte como falaria com um analista. Alguns exemplos:

Fluxo e conversão

• "Como foi a conversão das minhas lojas essa semana?"
• "Quantos visitantes minha loja do centro recebeu por dia no mês passado?"
• "Qual loja teve o melhor PA em agosto?"
• "As câmeras ficaram no ar todo o período?"

Metas

• "Estou batendo a meta do mês?"
• "Se o ritmo continuar assim, onde minhas metas vão fechar?"
• "Quais vendedores estão contribuindo para a meta da loja X?"

Corridas

• "Quem está ganhando a corrida?"
• "Como está a classificação da corrida de conversão entre as lojas?"
• "Qual vendedor está na frente na corrida da loja X?"

Não conversão

• "Por que os clientes não estão comprando na loja X?"
• "Quanto de receita eu perdi por ruptura de estoque no último mês?"
• "Os motivos de não conversão pioraram em relação ao período anterior?"
• "O que os clientes pediram e não tinha? Me mostre os atendimentos."

Referência das ferramentas

Todas as ferramentas com período exigem dateBegin e dateEnd no formato YYYY-MM-DD. Todas aceitam storeIds opcional (lista de ids); omitir significa "todas as lojas que o usuário acessa".

Ferramenta	O que retorna	Exige AlterVez
whoami	Id, nome de usuário e e-mail do usuário autenticado. Sem parâmetros.	—
get_stores	Lojas que o usuário acessa, com id, alias e nome. Sem parâmetros. Serve para resolver o nome de uma loja no id que as outras ferramentas esperam.	—
get_flow_per_day	Contagem de visitantes e média diária por loja, dia a dia.	—
conversion_rate_per_date	Faturamento, número de vendas, taxa de conversão, PA, preço médio por peça e uptime das câmeras, por loja.	—
metas_infos	Compara faturamento, fluxo, conversão e PA realizados contra o projetado de cada meta ativa no período, e projeta onde cada meta fecha.	—
corridas_infos	Corridas entre lojas ou entre vendedores de uma loja, com KPI, datas e participantes.	Sim
get_noc_reason_classifications_available	Classificações e subclassificações que um motivo de não conversão pode ter. Sem parâmetros.	—
noc_reasons_stats	Distribuição dos motivos de não conversão: contagem, participação, receita perdida e variação contra o período anterior de mesmo tamanho.	Sim
search_non_conversion_transcriptions	Os atendimentos por trás das não conversões, com o relato do próprio vendedor sobre o que o cliente pediu.	Sim

Detalhes por ferramenta

get_flow_per_day

Parâmetros extras: includeDetails (quebra por dia) e flowPreference (individual ou group, sobrepõe a preferência salva do usuário). Lojas sem fluxo medido no período são omitidas.

conversion_rate_per_date

Parâmetros extras: includeDetails e flowPreference. As métricas por item (PA e preço médio por peça) só fazem sentido em lojas com integração de vendas por ERP.

metas_infos

Parâmetros extras: includeDetails e includeSellers. Suporta metas escalonadas. Retorna uma entrada por meta, não por loja — uma meta pode abranger várias lojas.

corridas_infos

Parâmetros extras: category (store ou seller), kpi (conversion, numberOfSales, revenue, averageTicket, pa) e includeRanking (classificação atual).

get_noc_reason_classifications_available

Deve ser chamada antes de noc_reasons_stats e search_non_conversion_transcriptions para descobrir os valores válidos de filtro.

noc_reasons_stats

Parâmetros extras: includeSubclassifications, includeStoreBreakdown e sellerIds — omitir sellerIds significa sem quebra por vendedor; um array vazio quebra por todos os vendedores.

search_non_conversion_transcriptions

Parâmetros: mainClassifications (obrigatório, pelo menos uma), subClassifications e sellerIds. Traz o relato do próprio vendedor sobre o que o cliente pediu — ruptura de estoque, marcas, formas de pagamento, objeção de preço.

Limite de resultados

O resultado é limitado a 100 atendimentos no total, então os filtros devem ser estreitos.

Glossário

Termo	Significado
Atendimentos	Interações registradas entre vendedor e cliente na loja.
AlterVez	Produto da AlterVision que habilita o registro de atendimentos, motivos de não conversão e corridas.
Corridas	Competições entre lojas ou entre vendedores de uma mesma loja, disputadas em cima de um KPI.
Metas	Objetivos definidos no painel para faturamento, fluxo, conversão e PA. Podem ser escalonadas e abranger várias lojas.
Não conversão	Atendimento que não resultou em venda, classificado por motivo.
PA	Peças por atendimento — quantidade média de itens por venda.

Privacidade e segurança

• Somente leitura. As nove ferramentas apenas consultam dados. Nenhuma escreve, altera ou apaga informação no PainelAlter.
• Mesmo escopo do painel. O assistente vê exatamente as lojas que você já enxerga no PainelAlter — nem mais, nem menos. Mudanças no seu acesso ao painel se refletem no conector.
• Autenticação sua. O login acontece na tela do PainelAlter (https://painelalter.com/mcp/authorize); suas credenciais não são informadas ao assistente.
• Revogação. Para retirar o acesso, desconecte o conector nas configurações do seu assistente. No Claude: Configurações → Conectores.

TODO

Linkar a política de privacidade da AlterVision — não há URL registrada neste repositório.

Suporte

Dúvidas, problemas ou sugestões sobre o conector: entre em contato por e-mail em suporte@altervision.com.br.