Configuração de Analytics MCP com Amplitude
Instrumenta um servidor MCP para que cada chamada de ferramenta se torne um evento Amplitude, unificável com o restante dos dados Amplitude do produto (retenção, receita, uso web/mobile).
A referência autoritativa do SDK é o README do pacote:
https://github.com/amplitude/Amplitude-MCP-Analytics-Node (npm: @amplitude/mcp-analytics).
O SDK está em preview e evolui rapidamente — sempre busque o README mais recente e siga-o para instalação, formas das APIs, configuração e eventos padrão. Não confie em trechos memorizados ou resumos desta skill para detalhes da API do SDK; o README prevalece em caso de conflito.
Há quatro etapas. As etapas 1–2 são obrigatórias e estão documentadas no README — esta skill informa quais seções seguir e quais invariantes verificar. As etapas 3–4 são fortemente recomendadas e estão documentadas aqui por completo, pois exigem alterações fora do SDK (os esquemas de ferramentas do servidor e o aplicativo web do produto) que o README do SDK propositalmente não cobre.
Faça-as em ordem: Etapa 1 (chamadas de ferramenta) → Etapa 2 (identidade) → Etapa 3 (justificativa) → Etapa 4 (UTM, apenas se o servidor retornar links). Acerto a identidade antes de considerar qualquer coisa "pronta" — tudo que depende dela vem depois.
Antes de começar
Confirme:
- Este é um servidor MCP Node/TypeScript construído em
@modelcontextprotocol/sdk. Este SDK não suporta outras linguagens/runtimes. - O usuário tem (ou pode obter) uma chave de API Amplitude para o projeto onde os eventos devem chegar.
- Qual gerenciador de pacotes o repositório usa (pnpm/npm/yarn) — ajuste o comando de instalação de acordo.
Etapa 1 — Instalar o SDK e rastrear chamadas de ferramenta (obrigatório)
Busque o README e siga as seções Instalação e Início rápido. Sempre instale a versão mais recente publicada (ex.: pnpm add @amplitude/mcp-analytics@latest) — nunca fixe uma versão de memória, e não reproduza comandos de instalação desta skill.
Invariantes a verificar após a integração (o README explica cada uma):
analytics.instrumentServer(server, ...)é executado antes deserver.connect()— a ordem importa.- Toda função manipuladora de ferramenta é envolvida com
analytics.instrumentTool(). Ferramentas não envolvidas não são rastreadas. O envoltório tem a mesma forma do manipulador e é um pass-through sem efeito se o servidor nunca foi vinculado, portanto é seguro envolver defensivamente. - Todos os eventos padrão carregam o prefixo
[MCP], para que nunca colidam com eventos Amplitude existentes do produto. Consulte a tabela Eventos padrão no README (edocs/events.mdno repositório) para o conjunto atual de eventos e propriedades.
Opcional: anexe dimensões personalizadas estáveis (plano, equipe, feature flags) via extra em instrumentTool/instrumentServer — veja a seção Propriedades de evento personalizadas no README.
Etapa 2 — Acerto a identidade (obrigatório, faça antes de considerar a Etapa 1 "pronta")
Os eventos MCP devem carregar o mesmo user_id que o produto já envia para o Amplitude via web/mobile. Pule isso e o uso do MCP aparecerá como uma população desconectada que não pode ser unida aos dados do produto — isso anula a maior parte do propósito da integração.
Siga a seção Identidade do README para a API atual: ela oferece vinculação no nível do servidor, setIdentity() por requisição dentro de um manipulador, e um mapeamento resolveIdentity opcional baseado nas claims authInfo da requisição. Escolha o que melhor se adequa ao modelo de autenticação do servidor.
Um comportamento a sinalizar ao usuário: eventos totalmente anônimos, sem âncora, são descartados por padrão (não contados como usuários) a menos que explicitamente optados via emitAnonymousEvent: true para rastreamento apenas agregado — pergunte antes de ativar isso, pois altera o que é contado.
Etapa 3 — Capturar justificativa (recomendado)
Diferente de um humano clicando em um botão, um agente pode dizer por que chamou uma ferramenta. Capturar isso transforma os dados de "o que aconteceu" para "o que o usuário estava tentando fazer".
O lado do SDK é uma chamada (analytics.setRationale(...) — veja a seção Justificativa no README), mas o SDK nunca lê a justificativa diretamente das entradas da ferramenta: como a justificativa chega ao servidor é uma convenção do lado do servidor que esta skill implementa. O padrão testado é a injeção no schema — adicione um campo rationale opcional ao schema de entrada de toda ferramenta. Como o parâmetro é descrito no schema que os agentes já leem, eles o preenchem sem serem solicitados, em todos os clientes, sem alterações no lado do cliente:
// Adicione ao schema de entrada de toda ferramenta (exemplo com zod):
rationale: z
.string()
.optional()
.describe(
'Breve explicação de por que você está chamando esta ferramenta e o que ' +
'espera aprender com o resultado.',
),
Depois leia dentro do manipulador instrumentado e passe para o SDK:
analytics.instrumentTool(async (args, extra) => {
if (typeof args.rationale === 'string') {
analytics.setRationale(args.rationale);
}
return doWork(args);
}, { name: 'search' });
Tornar o campo opcional significa que nada quebra quando um agente o omite. Ele é emitido como a propriedade reservada [MCP] Rationale (truncada a 1.000 caracteres; a última escrita vence). Vale a pena fazer em todas as ferramentas, não apenas em uma amostra.
Etapa 4 — Adicionar tags UTM a links externos (recomendado, apenas se o servidor retornar URLs)
Esta etapa está inteiramente fora do SDK — ela altera como o servidor constrói URLs e depende da análise web do lado do produto. Ela não é coberta no README do SDK.
Se a resposta de alguma ferramenta incluir um link (painel, documento, página de produto), marque-o com UTM antes de deixar o servidor para que os cliques sejam atribuíveis ao tráfego MCP/agente em vez de aparecerem como diretos:
function addUtmParams(url: string, clientName?: string): string {
const u = new URL(url);
u.searchParams.append('utm_source', 'mcp');
u.searchParams.append('utm_medium', 'referral');
// O cliente conectado (ex.: "Claude", "Cursor"), se conhecido:
u.searchParams.append('utm_content', clientName ?? 'unknown');
return u.toString();
}
Direcione todo caminho de construção de URL nas respostas das ferramentas por uma única função central como esta — um único link sem tag quebra a história de atribuição para aquele fluxo.
Pré-requisito (diga isso ao usuário explicitamente): isso só funciona se a análise web deles capturar parâmetros UTM em eventos de visualização de página (ou qualquer evento que seu site dispare ao carregar). O SDK Browser 2 do Amplitude faz isso por padrão — veja Rastrear atribuição de marketing (parâmetros UTM, referenciador e ID de clique são capturados nativamente). Se eles usam um rastreador de visualização de página personalizado, precisam confirmar que os valores UTM também chegam nesses eventos, caso contrário não há com o que unir os cliques marcados pelo MCP.
Documentação relevante do Amplitude:
- Browser SDK 2 — Rastrear atribuição de marketing (captura UTM no lado web, a metade de implementação desta etapa)
- Sessões, canais e atribuição para análise de marketing (como o tráfego marcado se torna análise de canal)
- Autocaptura (visualizações de página e mais)
Após a instrumentação
Assim que os eventos estiverem fluindo, aponte um agente de codificação para a skill publicada analyze-mcp-server do Amplitude para executar agrupamento de intenções e identificar padrões de erro de chamada de ferramenta por intenção. (Se este projeto tiver a skill mcp-intent-error-analysis instalada, essa é a certa — use-a quando o usuário já tiver dados fluindo e quiser analisá-los, em vez de duplicar essa análise aqui.)
Erros comuns a sinalizar
- Seguir trechos de API desatualizados em vez do README atual — busque-o fresco; o SDK está em preview e muda rapidamente.
- Instalar uma versão fixada/mais antiga em vez da versão mais recente.
- Chamar
instrumentServer()depois deserver.connect()— deve ser antes. - Envolver alguns manipuladores de ferramenta, mas não outros — toda ferramenta precisa de
instrumentTool. - Enviar um
user_idque não corresponde ao usado em web/mobile — quebra a unificação, o objetivo central da integração. - Ativar
emitAnonymousEvent: truesem que o usuário entenda que isso infla contagens agregadas com tráfego sem âncora. - Esquecer o pré-requisito UTM (captura no lado web) e assumir que marcar links com tags é suficiente.