Configurando o servidor UserGuiding MCP

Conecte seu assistente de IA ao UserGuiding com OAuth ou uma chave de API, em um servidor dos EUA ou da UE.

Configurando o servidor UserGuiding MCP

Este artigo explica como conectar um assistente de IA ao seu projeto UserGuiding por meio do servidor MCP: onde encontrar o URL do servidor, como autenticar com OAuth ou uma chave de API e o que muda se sua conta estiver hospedada no servidor da UE.

Para uma visão geral do que é o MCP e do que ele pode fazer, consulte o Guia do Usuário do Servidor MCP .

Antes de começar

O MCP está disponível em todos os planos UserGuiding.
Você precisa de acesso ao painel do projeto ao qual deseja se conectar. Uma conexão é sempre limitada a um único projeto.
A configuração leva cerca de dois minutos. Não é necessária a ajuda de um desenvolvedor nem qualquer alteração de código no seu produto.
Seu cliente de IA deve ser compatível com servidores MCP remotos via HTTP Streamable. Claude (web, desktop e Claude Code), Cursor e OpenAI Codex são compatíveis.

Passo 1: Copie o URL do seu servidor

No painel UserGuiding, acesse Configurações > Configurações do Projeto > MCP e Chave de API . A página exibe o URL do servidor da sua conta, além de trechos de código prontos para colar para os clientes mais comuns.

Existem dois servidores de produção, um para cada região de dados:

EUA (padrão): https://mcp.userguiding.com/mcp/
UE: https://eu-mcp.userguiding.com/mcp/

O painel sempre exibe o URL que corresponde à região da sua conta, portanto, copiá-lo de lá é a opção mais segura. Se sua conta estiver no servidor da UE, leia a seção de suporte ao servidor da UE abaixo antes de se conectar.

Observe a barra invertida no final. O servidor utiliza o protocolo HTTP Streamable em /mcp/ . Os antigos endpoints de Eventos Enviados pelo Servidor ( /mcp/sse e /mcp/messages ) foram desativados e agora respondem com o 410 Gone . Se você configurou o MCP antes dessa alteração, atualize o URL no seu cliente.

Passo 2: Escolha como você se autentica.

O painel oferece duas abas: OAuth e Chave de API . OAuth é o método recomendado para todas as novas conexões. A autenticação por chave de API ainda funciona, mas está sendo descontinuada, e o painel exibe um aviso de descontinuação nessa aba.

Opção A: OAuth (recomendado)

Com o OAuth, você nunca precisa copiar uma chave secreta para um arquivo de configuração. Você adiciona a URL do servidor e seu assistente o encaminha para um processo de login normal do UserGuiding na primeira vez que se conecta.

O que acontece quando você se conecta:

Seu cliente se cadastra automaticamente no UserGuiding (cadastro dinâmico de clientes) e abre uma janela do navegador.
Você faz login com sua conta do painel UserGuiding. Se sua conta exigir autenticação de dois fatores, você a completa aqui.
Uma tela de consentimento é exibida. Na parte superior, você escolhe a qual projeto o assistente pode acessar, com seu projeto padrão pré-selecionado. Abaixo, você vê as permissões exatas que o cliente está solicitando.
Você aprova e o cliente recebe um token. Os tokens de acesso têm curta duração (uma hora) e são renovados silenciosamente em segundo plano, portanto, você não precisa repetir esse fluxo a cada sessão.

Trechos de conexão:

Código Claude

 claude mcp add --transport http userguiding https://mcp.userguiding.com/mcp/

Codex CLI

 codex mcp add userguiding --url https://mcp.userguiding.com/mcp/

Cursor e outros clientes de configuração JSON

 {
  "mcpServers": {
    "userguiding": {
      "url": "https://mcp.userguiding.com/mcp/"
    }
  }
 }

Claude.ai e Claude para Desktop

Claude se conecta a servidores remotos por meio de conectores personalizados. Em um ambiente de equipe ou corporativo, um administrador adiciona o conector uma única vez, e então todos os outros o habilitam.

Selecione o ícone do seu perfil no canto inferior esquerdo do Claude e, em seguida, abra as Configurações (administradores do espaço de trabalho: Configurações de administrador ).
Abra a aba Conectores e clique em Adicionar conector personalizado .
Dê o nome de UserGuiding e cole o URL do seu servidor a partir do painel.
Clique em Conectar , faça login com sua conta UserGuiding, selecione seu projeto e aprove as permissões.

Opção B: Chave de API (legada)

A autenticação por chave de API ainda é compatível com configurações existentes, mas deixará de funcionar. Migre as conexões para OAuth assim que possível.

Crie ou copie a chave na seção "User API Key" (Chave de API do Usuário) na mesma página do painel e, em seguida, envie-a no cabeçalho UG-API-KEY .

Código Claude

 claude mcp add --transport http userguiding https://mcp.userguiding.com/mcp/ --header "UG-API-KEY: YOUR_API_KEY"

CLI do Codex ( ~/.codex/config.toml )

 [mcp_servers.userguiding]
 url = "https://mcp.userguiding.com/mcp/"
 http_headers = { "UG-API-KEY" = "YOUR_API_KEY" }

Cursor e outros clientes de configuração JSON

 {
  "mcpServers": {
    "userguiding": {
      "url": "https://mcp.userguiding.com/mcp/",
      "headers": {
        "UG-API-KEY": "YOUR_API_KEY"
      }
    }
  }
 }

Clientes que não conseguem enviar cabeçalhos personalizados podem passar a chave como um parâmetro de consulta, https://mcp.userguiding.com/mcp/?api_key=YOUR_API_KEY . Esta é apenas uma alternativa de compatibilidade. Ela insere uma credencial ativa em uma URL que é armazenada em arquivos de configuração e logs, portanto, prefira o OAuth.

Uma chave de API concede acesso a todas as ferramentas sem qualquer filtro de escopo, portanto, trate-a como uma credencial de administrador. Redefinir a chave no painel invalida imediatamente todas as conexões que a utilizam.

Suporte a servidores da UE

O UserGuiding opera em ambientes separados para os EUA e a UE, e cada um armazena seus próprios dados de clientes. O MCP segue a mesma divisão: o servidor MCP da UE é um host diferente que lê apenas dados da UE.

As contas dos EUA se conectam a https://mcp.userguiding.com/mcp/ .
As contas da UE se conectam a https://eu-mcp.userguiding.com/mcp/ .

Ambas as regiões compartilham um serviço de login em api.userguiding.com , portanto a experiência OAuth é idêntica. O que difere é o token: quando você aprova a tela de consentimento, o UserGuiding emite um token vinculado à região da sua conta, e cada servidor MCP aceita apenas tokens gerados para si próprio. Essa vinculação é o que mantém os dados da UE dentro do ambiente da UE.

Consequências práticas:

Sempre copie o URL de Configurações > Configurações do Projeto > MCP e Chave de API, em vez de copiá-lo de uma postagem de blog ou de uma versão antiga deste artigo. O painel resolve a região automaticamente.
Se uma conta da UE direcionar um cliente para um URL dos EUA, a conexão falhará na verificação do token, em vez de retornar silenciosamente os dados de outra pessoa.
Os membros da equipe que compartilham um arquivo de configuração devem estar na mesma conta e, portanto, na mesma região. Não existe uma URL combinada que sirva para ambos.
Não tem certeza de em qual região você está? Veja Mudando para o servidor da UE .

Permissões

Uma conexão OAuth possui um conjunto de escopos, e cada chamada de ferramenta é verificada em relação a eles. Se um escopo estiver faltando, essa ferramenta específica é recusada com uma mensagem clara, e o restante da conexão continua funcionando. Solicitar menos escopos é a maneira mais simples de conceder acesso somente leitura a um assistente.

users:read : ler perfis de usuários finais, atributos, segmentos, eventos rastreados e análises de desempenho para todos os materiais.
users:write : cria, atualiza e exclui usuários finais e redefine seu histórico de orientação do usuário.
events:write : rastreia eventos personalizados para usuários finais.
companies:read : leia os perfis das empresas e os dados de engajamento.
knowledge_base:read : ler e pesquisar artigos e categorias da Base de Conhecimento.
knowledge_base:write : cria, atualiza e exclui artigos e categorias da Base de Conhecimento.
segments:write : criar e atualizar segmentos de usuário.
product_updates:read : ler as publicações de atualizações de produtos.
product_updates:write : criar, atualizar e excluir posts de Atualizações de Produto.
roadmap:read : leia os itens do roadmap e as solicitações de recursos.
roadmap:write : aprovar, rejeitar e gerenciar solicitações de recursos.

Um cliente que não solicita nada específico recebe o conjunto padrão: users:read , companies:read , events:write e knowledge_base:read . As conexões por chave de API ignoram completamente as verificações de escopo, o que é mais um motivo para preferir o OAuth.

Independentemente do método utilizado, o projeto é fixo no momento da conexão. O projeto selecionado na tela de consentimento (ou o projeto ao qual a chave da API pertence) é o único que o assistente pode acessar, e nenhum argumento da ferramenta pode alterá-lo. O acesso entre projetos e entre contas diferentes não é possível.

Limites

Limite de taxa: 60 chamadas de ferramentas por minuto por projeto, compartilhadas por todas as conexões desse projeto.
Intervalos de datas: as ferramentas de análise aceitam um intervalo de, no máximo, um ano.
Análise de retenção: no máximo 31 grupos por chamada, portanto, uma matriz diária abrange 31 dias e uma semanal, 31 semanas.
Públicos grandes: a segmentação por membro é recusada para públicos acima de 10.000 membros, tanto para segmentos quanto para empresas. Em vez disso, refine o segmento.

Quando uma solicitação excederia um desses limites, a ferramenta retornaria um erro explicando o limite. Ela nunca trunca os dados silenciosamente, porque uma resposta truncada silenciosamente pareceria definitiva e estaria errada.

O que é registrado

Cada chamada da ferramenta MCP é gravada por aproximadamente três meses e usada para análise forense de abusos e solução de problemas. As gravações vão um passo além: a criação de um artigo, a atualização de um segmento ou a aprovação de uma solicitação de recurso são registradas no Log de Atividades do painel com o nome do usuário do painel por trás da conexão, exatamente como se ele tivesse feito a alteração manualmente.

Solução de problemas

Erro 410 Gone, ou "O transporte SSE legado não é suportado": seu cliente ainda aponta para /mcp/sse . Altere o URL para https://mcp.userguiding.com/mcp/ (ou o host da UE) e reconecte.
Erro 401 Não autorizado: o token foi emitido para outra região, expirou ou a chave da API foi redefinida. Remova a conexão no seu cliente e adicione-a novamente.
"Cabeçalho de autorização ausente ou UG-API-KEY ausente": o cliente não está enviando credenciais. Em clientes JSON, verifique se o bloco de cabeçalho está dentro da entrada do servidor.
"Escopo insuficiente": a conexão foi aprovada sem a permissão necessária para a ferramenta. Reconecte e aprove o escopo ausente.
O assistente responde, mas os números parecem vazios: provavelmente você selecionou o projeto errado na tela de consentimento. Reconecte-se e selecione o correto.
Uma série repentina de erros durante uma análise longa: você atingiu o limite de taxa por minuto. Peça ao assistente para trabalhar em lotes menores.

Próximos passos

Guia do Usuário - Referência de Ferramentas MCP : todas as ferramentas e as permissões necessárias.
Guia do Usuário MCP: Casos de Uso e Exemplos de Instruções : instruções para copiar para sua equipe.