Guia do Usuário do Servidor MCP
Conecte suas ferramentas de IA diretamente ao seu projeto UserGuiding por meio do MCP Server. Uma vez conectadas, ferramentas como Claude, Cursor ou qualquer assistente compatível com MCP podem pesquisar usuários, buscar por atributos ou eventos, rastrear eventos, gerenciar empresas e muito mais — tudo por meio de linguagem natural.
Como funciona
O MCP (Model Context Protocol) é um padrão aberto que permite que ferramentas de IA chamem serviços externos de forma estruturada e segura. O servidor MCP do UserGuiding disponibiliza os dados de usuário do seu projeto como um conjunto de ferramentas que a IA pode usar em seu nome.
AI Tools (Claude, ChatGPT, etc.)
│
│ SSE connection + JSON-RPC messages
▼
UserGuiding MCP Server
│
│ Authenticated via your API key
▼
Your UserGuiding Project Data
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 transporte. Adicione o seguinte às configurações do MCP da sua ferramenta de IA:
URL do servidor:
https://mcp.userguiding.com/mcp/sseAutenticaçã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 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>"
}
}
}
}
Ferramentas disponíveis
Gerenciamento de usuários
get_user
Pesquise um usuário pelo ID. Retornará todos os atributos, associação com a empresa e histórico de interações.
upsert_user
Crie um novo usuário ou atualize um existente. Mesclará atributos e, opcionalmente, vinculará o usuário a uma empresa.
delete_user
Excluir um usuário permanentemente.
reset_user_history
Redefina o histórico de interações do usuário (visualizações do guia, progresso da lista de verificação, etc.), mantendo seus atributos personalizados.
list_users
Liste todos os usuários com paginação baseada em cursor.
Pesquisa e análise
search_users
Pesquise e filtre usuários por atributos ou eventos. Suporta paginação e ordenação.
get_user_count
Contabilizará usuários que correspondem aos filtros sem obter os dados completos do usuário.
list_attributes
Descubra todos os atributos de usuário disponíveis e seus tipos de dados.
list_events
Descubra todos os nomes de eventos monitorados em seu projeto.
Eventos
track_event
Registre um evento específico para um usuário, opcionalmente com metadados.
Empresas
get_company
Pesquise uma empresa pelo ID. Retorna atributos e IDs de usuários membros.
list_companies
Liste e filtre empresas com paginação e ordenação.
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
Filtrar usuários com base na ocorrência ou contagem de eventos:
{"event_name": "page_view", "metric": "count", "equation": "greater_than", "value": 10}
{"event_name": "signup", "metric": "last_occurred", "equation": "after", "value": 1704067200000}
Métricas disponíveis:
count
greater_than , less_than , equals , not_equals
last_occurred
before , after , on
first_occurred
before , after , on
Combinando filtros
Utilize o parâmetro filter_operator para combinar vários filtros com lógica AND (padrão) ou OR .
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."
Segurança e Acesso
- Autenticação necessária. Cada conexão deve incluir uma chave de API válida.
- Acesso restrito ao escopo do projeto. Cada chave de API está vinculada a um projeto específico do UserGuiding — a IA só pode acessar dados dentro desse projeto.
- Não há acesso entre projetos. Uma ferramenta de IA conectada não pode visualizar ou modificar dados em outros projetos.
- As sessões expiram após 2 horas de inatividade.
Perguntas frequentes
A ferramenta de IA armazena meus dados de usuário? O servidor MCP transmite dados diretamente para a ferramenta de IA durante a sua sessão. O UserGuiding não controla como a ferramenta de IA lida com os dados — consulte as políticas de dados do seu provedor de IA.
Posso limitar a quais ferramentas estão disponíveis? Atualmente, todas as ferramentas estão disponíveis assim que a conexão é estabelecida. O controle de acesso por ferramenta está em nossos planos futuros.
O que acontece se minha chave de API for rotacionada? As sessões MCP ativas continuarão funcionando até expirarem (até 2 horas). Novas conexões precisarão da chave atualizada.
Existe um limite de taxa? O servidor MCP segue os mesmos limites de taxa da API pública do UserGuiding.