Servidor MCP

1. O que um agente pode fazer com isso

Aponte um cliente do Model Context Protocol para o endpoint, e ele poderá responder a perguntas como “qual página gera mais cliques de raiva neste mês” ou “mostre três sessões da Alemanha com mais de dois minutos” e depois fornecer um link para reproduzir a sessão.

Ferramenta	Responde
mp_projects	quais projetos esta chave pode consultar
mp_overview	sessões, pessoas, visualizações de página, duração e sinais de frustração
mp_sessions	sessões recentes com links de reprodução, filtradas por país, dispositivo ou duração
mp_session	uma sessão: páginas em ordem, eventos, origem e dispositivo
mp_pages	páginas por número de visualizações, com visitantes únicos
mp_frustration	cliques de raiva, cliques mortos e erros de JavaScript agrupados por página
mp_goals	suas metas e a frequência com que cada uma foi atingida

2. Conectar

O endpoint aceita POST em /mcp e usa Streamable HTTP, versão do protocolo 2026-07-28.

A autenticação usa uma chave comum de leitura da API do MousePlayer, do mesmo tipo que você cria em Configurações, Chaves de API, e que a API REST aceita. Não há uma segunda credencial. Revogar a chave revoga o acesso do agente no mesmo momento.

Depois, ative o projeto

Uma chave de API abre todo o seu espaço de trabalho. Este acesso deliberadamente não: cada projeto tem seu próprio controle na página de integrações, desativado por padrão. Um projeto não ativado não aparece em mp_projects e não pode ser consultado, mesmo que o agente adivinhe seu ID.

Isso não é burocracia. Uma chave de API em um script de implantação fica em um lugar que você controla; uma chave no arquivo de configuração de um agente alimenta o contexto de um modelo, sob um controle bem menos direto. Liberar um projeto de cada vez oferece o controle adequado.

3. Somente leitura, e por que isso não vai mudar

Nenhuma das sete ferramentas grava dados. Este endpoint não permite exclusão, exportação ou alteração de configuração. Isso não é por falta de tempo, mas porque uma ferramenta que um agente pode chamar também pode ser chamada por engano.

O que não é retornado

Nem as gravações em si, nem capturas do DOM, nem endereços IP. O agente recebe o que uma pessoa vê na interface, com o link para assistir ao restante.

Limites de solicitações e abrangência

Sessenta solicitações por minuto por chave, como na API REST. O intervalo de tempo é limitado a 365 dias, e a lista de resultados a 200 linhas; uma resposta truncada informa essa condição, pois uma lista cortada silenciosamente parece completa.

4. Para quem desenvolve o cliente

Três métodos: server/discover, tools/list, tools/call. Sem sessões, sem fluxo GET e sem Last-Event-ID : esses recursos pertencem a versões do protocolo até 2025-11-25 e não fazem parte desta versão. GET ou DELETE recebem 405.

Cada POST inclui MCP-Protocol-Version, Mcp-Method e, para tools/call, Mcp-Name, e cada valor precisa corresponder ao corpo. Uma divergência retorna 400 com o erro JSON-RPC -32020; uma versão não compatível retorna 400 com -32022 e a lista de versões aceitas, para que seu cliente possa escolher uma e tentar novamente.

Dois tipos de erro, de propósito

Uma solicitação malformada ou uma ferramenta desconhecida gera um erro JSON-RPC. “Este projeto não está liberado” ou “sessão inexistente” retorna como resultado normal com isError: true , porque um modelo pode se recuperar do segundo tipo consultando mp_projects e tentando novamente, mas não do primeiro.

Os resultados incluem tanto structuredContent quanto os mesmos dados serializados em um bloco de texto, para que clientes mais antigos ainda recebam algo útil.