Guia do Usuário do Servidor MCP
Conecte suas ferramentas de IA diretamente ao seu projeto UserGuiding por meio do servidor MCP. Uma vez conectadas, ferramentas como Claude, Cursor, OpenAI Codex ou qualquer assistente compatível com MCP podem pesquisar usuários, buscar por atributos ou eventos, rastrear eventos, gerenciar empresas, gerenciar artigos da Base de Conhecimento e muito mais — tudo por meio de linguagem natural.
O MCP está disponível em todos os planos da UserGuiding e leva cerca de dois minutos para ser configurado. Não é necessária ajuda de um desenvolvedor.
Como funciona
O MCP (Model Context Protocol) é um padrão aberto lançado pela Anthropic em 2024 que permite que ferramentas de IA chamem serviços externos de forma estruturada e autenticada — semelhante a como um desenvolvedor chama uma API, mas mediado pelo modelo de IA. Em vez de colar dados em uma janela de bate-papo ou conectar-se a integrações ad hoc, a ferramenta de IA se conecta uma única vez a um servidor MCP e obtém um conjunto bem definido de ferramentas que pode invocar em seu nome.
O servidor UserGuiding MCP expõe os dados de usuário do seu projeto como um conjunto de ferramentas que a IA pode invocar em seu nome.
AI Tools (Claude, Cursor, OpenAI Codex, etc.)
│
│ SSE connection + JSON-RPC messages
▼
UserGuiding MCP Server
│
│ Authenticated via your API key
▼
Your UserGuiding Project Data
Claude (Desktop e Claude.ai), Cursor e OpenAI Codex oferecem suporte nativo ao MCP. Qualquer outra ferramenta que adote o MCP como protocolo de transporte poderá se conectar ao servidor UserGuiding sem configuração adicional.
O que você pode fazer com o UserGuiding MCP
O servidor MCP transforma os dados de produtos que você já rastreia em algo que você pode consultar de forma conversacional. Cinco casos de uso comuns:
Pesquisa de usuários sem SQL. Filtre seus usuários por qualquer atributo ou evento, combine critérios e segmente por coorte. Sem painéis de controle com filtros, sem exportação para CSV. A IA seleciona automaticamente as ferramentas de busca adequadas.
"Mostre-me todos os usuários do plano Pro que se inscreveram nos últimos 30 dias e acionaram o evento export_csv pelo menos uma vez."
Pesquisa prévia para vendas. Antes de uma ligação de renovação ou demonstração para um potencial cliente, colete tudo o que o usuário fez em seu produto: plano, data de inscrição, uso de recursos, quais metas ele atingiu e quais eventos ele acionou nesta semana.
"Consulte o perfil do usuário [email protected]. Qual é o plano dele, quando ele se cadastrou e o que ele fez no produto esta semana?"
Suporte ao contexto. Quando um chamado é aberto, o sistema exibe o perfil completo do usuário e o histórico de interações recentes em uma única solicitação. Isso elimina as 2 ou 3 trocas de mensagens que geralmente começam com "qual plano você utiliza?".
"Obtenha o perfil completo do usuário [email protected] para que eu possa ver o plano, os recursos utilizados e a atividade recente."
Análise de ativação e integração. Compare grupos, encontre diferenças de comportamento e identifique as etapas de integração que diferenciam os usuários ativos daqueles que cancelam o serviço.
"Mostre-me os usuários que concluíram nossa lista de verificação de integração em comparação com os usuários que desistiram na etapa 3. O que os que concluíram fizeram que os outros não fizeram?"
Sinais de expansão e rotatividade. Identifique usuários cujos padrões de uso sugerem que estão prontos para fazer um upgrade ou usuários de planos pagos que estão ficando inativos.
"Encontre os usuários do plano Starter que acionaram o evento api_rate_limit_hit mais de dez vezes neste mês."
Começando
Passo 1: Obtenha sua chave de API
Encontre sua chave de API em Painel de Guias do Usuário → Configurações → Configurações do Projeto → MCP e API .
Etapa 2: Conecte sua ferramenta de IA
O servidor MCP utiliza Eventos Enviados pelo Servidor (SSE) como meio de transporte. Adicione o seguinte às configurações do MCP da sua ferramenta de IA:
URL do servidor:
https://mcp.userguiding.com/mcp/sse
Autenticação — envie sua chave de API como um cabeçalho:
UG-API-KEY: <your-api-key>
Ou como um parâmetro de consulta (para ferramentas que não suportam cabeçalhos personalizados):
https://mcp.userguiding.com/mcp/sse?api_key=<your-api-key>
Claude.ai e Claude para Desktop
Tanto para o Claude.ai quanto para o Claude para Desktop, um administrador precisa primeiro adicionar o servidor UserGuiding MCP como um conector antes que outros usuários do Claude possam se conectar.
- Selecione o ícone do seu perfil no canto inferior esquerdo do Claude e, em seguida, selecione Configurações de administrador .
- Abra a aba Conectores e clique no ícone (+) na parte superior do campo Conectores.
- Selecione Adicionar Conector Personalizado :
- Nome: Guia do Usuário
- URL do servidor MCP remoto:
https://mcp.userguiding.com/mcp/sse
- Clique em Conectar para autenticar e começar a usar o conector com Claude.
Exemplos de configuração
Claude.ai
Claude Desktop ( claude_desktop_config.json ):
{
"mcpServers": {
"userguiding": {
"url": "https://mcp.userguiding.com/mcp/sse",
"headers": {
"UG-API-KEY": "<your-api-key>"
}
}
}
}
Cursor ( .cursor/mcp.json ):
{
"mcpServers": {
"userguiding": {
"url": "https://mcp.userguiding.com/mcp/sse",
"headers": {
"UG-API-KEY": "<your-api-key>"
}
}
}
}
OpenAI Codex ( mcp.json ):
O Codex segue o mesmo formato de configuração do servidor MCP que o Cursor. Adicione a entrada do servidor UserGuiding ao seu arquivo mcp.json do Codex usando o JSON acima. Consulte a documentação atual do Codex MCP da OpenAI para obter a localização exata do arquivo no seu sistema.
{
"mcpServers": {
"userguiding": {
"url": "https://mcp.userguiding.com/mcp/sse",
"headers": {
"UG-API-KEY": "<your-api-key>"
}
}
}
}
Ferramentas disponíveis
O servidor UserGuiding MCP disponibiliza 17 ferramentas em cinco áreas de funcionalidade . Cada uma delas pode ser acionada em linguagem natural por qualquer assistente de IA compatível com MCP, e você pode combiná-las em um único comando — o assistente de IA seleciona as ferramentas adequadas para responder à sua pergunta.
Gerenciamento de usuários
get_user— Busca um usuário por ID. Retorna todos os atributos, associação com a empresa e histórico de interações. Conecta-se a: Identificação de Usuário, Segmentação, Análise.upsert_user— Cria um novo usuário ou atualiza um existente. Mescla atributos e, opcionalmente, vincula o usuário a uma empresa. Conecta-se a: Identificação de Usuário, Segmentação.delete_user— Exclui um usuário permanentemente. Conecta-se a: Identificação do Usuário.reset_user_history— Redefine o histórico de interações de um usuário (visualizações de guias, progresso de listas de verificação, etc.), mantendo seus atributos personalizados. Conecta-se a: Guias, Listas de Verificação, Pesquisas, Pontos de Interesse, Centros de Recursos.list_users— Lista todos os usuários com paginação baseada em cursor. Conecta-se a: Identificação de Usuário, Segmentação.
Pesquisa e análise
search_users— Busca e filtra usuários por atributos ou eventos. Suporta paginação e ordenação. Conecta-se a: Segmentação, Analytics.get_user_count— Conta os usuários que correspondem aos filtros sem buscar os dados completos do usuário. Conecta-se a: Segmentação, Análise.list_attributes— Descubra todos os atributos de usuário disponíveis e seus tipos de dados. Conecta-se a: Identificação de Usuário, Segmentação.list_events— Descubra todos os nomes de eventos rastreados em seu projeto. Conecta-se a: Analytics, No-Code Analytics, Alertas Personalizados.
Eventos
track_event— Rastreia um evento nomeado para um usuário, opcionalmente com metadados. Conecta-se a: Analytics, No-Code Analytics, Alertas Personalizados, Segmentação.
Empresas
get_company— Busca uma empresa por ID. Retorna atributos e IDs de usuários membros. Conecta-se a: Segmentação, direcionamento em nível de conta.list_companies— Lista e filtra empresas com paginação e ordenação. Conecta-se a: Segmentação, direcionamento por conta.
Base de conhecimento
search_kb_articles— Pesquise artigos da sua Base de Conhecimento por meio de uma consulta de texto. Retorna IDs, títulos, descrições e categorias dos artigos, classificados por relevância. Conecta-se à: Base de Conhecimento.get_kb_article— Recupera o conteúdo completo de um artigo da Base de Conhecimento pelo seu ID, incluindo título, corpo, descrição, status de publicação e todos os idiomas. Conecta-se a: Base de Conhecimento.create_kb_article— Cria um novo artigo na Base de Conhecimento com título, conteúdo e descrição opcional. Conecta-se à: Base de Conhecimento.update_kb_article— Atualiza o título ou o conteúdo de um artigo existente da Base de Conhecimento pelo seu ID. Conecta-se a: Base de Conhecimento.delete_kb_article— Exclui permanentemente um artigo da Base de Conhecimento pelo seu ID. Conecta-se a: Base de Conhecimento.
Pesquisa e filtragem de usuários
A ferramenta search_users suporta dois tipos de filtros.
Filtros de atributos
Filtre os usuários por qualquer atributo integrado ou personalizado:
{"attribute": "email", "equation": "contains", "value": "@acme.com"}
{"attribute": "plan", "equation": "equals", "value": "enterprise"}
{"attribute": "first_seen", "equation": "after", "value": 1704067200000}
Equações disponíveis por tipo de atributo:
Texto: equals , not_equals , contains , not_contains , starts_with , ends_with , regexp , is_not_known , has_any_value
Número: equals a , not_equals , more_than , less_than , is_known , is_not_known
Data: before , after , equals a , not_equals de , more_than_days_ago , less_than_days_ago , exact_days_ago , is_not_known , has_any_value
Booleano: equals a , not_equals , is_not_known , has_any_value
Filtros de eventos
Filtre por se um usuário realizou (ou não) um evento:
{"event": "signed_up", "equation": "has_done"}
{"event": "export_csv", "equation": "has_not_done"}
Equações disponíveis: has_done , has_not_done
Combinando filtros
Passe vários objetos de filtro na matriz de filtros. Os filtros são combinados com lógica AND:
[
{"attribute": "plan", "equation": "equals", "value": "enterprise"},
{"event": "export_csv", "equation": "has_done"}
]
Exemplos de perguntas
Após a conexão, aqui estão algumas instruções que sua equipe pode usar:
- Quantos usuários se cadastraram nos últimos 7 dias?
- "Encontre todos os usuários do plano empresarial cuja última data de acesso seja anterior a janeiro de 2025."
- "Mostre-me os detalhes do usuário u_abc123."
- "Rastrear um evento plan_upgraded para o usuário u_abc123."
- "Liste todas as empresas com mais de 50 membros."
- "Pesquise na base de conhecimento por artigos sobre como começar."
- "Encontre todos os artigos da base de conhecimento na categoria Desenvolvedores."
- "Mostre-me o conteúdo completo do artigo 182 da base de conhecimento."
- "Crie um novo artigo na base de conhecimento intitulado 'Como usar a API REST' com uma breve introdução."
- "Atualizar o artigo 299 para mencionar que as novas opções de indexação estão disponíveis."
O que o servidor MCP oferece
Um breve resumo do conteúdo da caixa:
- Acesso de leitura e gravação — consulte usuários, empresas e eventos; atualize perfis, acompanhe eventos e crie ou atualize artigos da Base de Conhecimento a partir da sua ferramenta de IA.
- Profundidade da interação — guia individual, lista de verificação, pesquisa e eventos de destaque com registros de data e hora, e não apenas contagens agregadas.
- Configuração sem código — conecte-se através das configurações do conector Claude.ai ou de um arquivo de configuração JSON. Leva cerca de dois minutos.
- Consultas em linguagem natural — pergunte sobre os usuários em inglês simples. A IA seleciona automaticamente as ferramentas certas.
- Dados em tempo real — as consultas refletem o estado atual, não uma exportação em cache.
Emparelhamento com rastreamento de eventos sem código
O servidor MCP integra-se perfeitamente com o Rastreamento de Eventos Sem Código da UserGuiding . Basta clicar em elementos do seu produto para começar a capturar eventos — sem código, sem tempo de engenharia, sem necessidade de instalar um novo SDK. Em seguida, consulte esses eventos por meio do servidor MCP em linguagem natural.
Para a maioria das equipes de produto, crescimento e sucesso do cliente, essa combinação substitui uma estrutura que antes exigia Amplitude, Heap ou Mixpanel para rastreamento de eventos, além de uma ferramenta de análise separada para exploração. A captura de eventos reside na mesma plataforma que seu onboarding, suas listas de verificação e sua Base de Conhecimento, e o servidor MCP transforma a análise de produtos em uma interface de bate-papo dentro do Claude, Cursor ou Codex.
Perguntas frequentes
Quais planos incluem o MCP? O MCP está disponível em todos os planos UserGuiding.
Precisamos de ajuda técnica para configurar? Não. É uma conexão que você habilita nas configurações da sua ferramenta de IA. O tempo total de configuração é de aproximadamente dois minutos.
A que dados o servidor MCP pode aceder? O servidor MCP só pode aceder a dados dentro do projeto associado à sua chave de API. Não pode aceder a outros projetos ou outras contas.
A conexão é segura? Sim. Toda a comunicação é feita via HTTPS e sua chave de API autentica cada solicitação.
E quanto à privacidade dos dados? Os dados permanecem no seu projeto UserGuiding. A ferramenta de IA envia consultas ao servidor MCP do UserGuiding e recebe os resultados. Não há exportação ou armazenamento em massa no lado da IA.
Os dados são em tempo real? Sim. As consultas do MCP acessam o banco de dados ativo do UserGuiding, não uma exportação em cache. Se um usuário acionou um evento há 30 segundos, sua ferramenta de IA o detecta.
Funciona com o ChatGPT ou outras ferramentas de IA? O suporte a MCP é nativo no Claude (Desktop e Claude.ai), Cursor e OpenAI Codex. O ChatGPT e o Gemini não oferecem suporte nativo a MCP até abril de 2026. Qualquer ferramenta que adote o MCP como protocolo de transporte poderá se conectar ao servidor UserGuiding sem necessidade de configuração adicional da nossa parte.
Os usuários podem causar problemas com operações de escrita? As ferramentas de escrita ( upsert_user , track_event , delete_user , reset_user_history e as ferramentas de criação/atualização/exclusão da Base de Conhecimento) usam a mesma chave de API que as ferramentas de leitura. Trate a chave como qualquer credencial de administrador: compartilhe-a com cuidado. O uso somente leitura (search, get, list) é seguro em qualquer caso.
Existe um limite de taxa? O servidor MCP segue os mesmos limites de taxa da API pública do UserGuiding.
Como isso se compara ao Amplitude, Heap ou Mixpanel? Amplitude, Heap e Mixpanel são plataformas de análise de produtos com seus próprios SDKs de rastreamento de eventos e interfaces de consulta. O Rastreamento de Eventos Sem Código do UserGuiding captura os mesmos tipos de eventos de usuário sem código ou ajuda de engenharia, e o servidor MCP permite que você os consulte em linguagem natural em vez de criar painéis. Para equipes de produto, crescimento e sucesso do cliente que desejam análises sem um analista dedicado, ele substitui um contrato de análise separado por algo que já está incluído no seu plano do UserGuiding.