Construir com o Moose: ligue o Claude Code, o Codex ou o Cursor e construa sobre o Hi, Moose

Antes de começar

O que tem de existir primeiro

O Hi, Moose devolve respostas reais guardadas, por isso tem de haver algo recolhido antes de um agente poder construir sobre isso. Se é um agente a ler isto, percorra estes quatro pontos com o seu utilizador antes de começar.

1

Uma conta Hi, Moose

A gratuita serve para MCP. A REST API precisa de um plano pago.
Criar uma conta
2

A app de desktop, instalada e com sessão iniciada

A recolha corre na app, no seu computador ou num anfitrião que controla. Para trabalhos MCP tem de estar aberta e com sessão iniciada. As leituras REST são servidas a partir da cloud e funcionam com a app fechada.
Transferir a app
3

Um projeto com prompts acompanhados

Um projeto por marca. Adicione os prompts que quer acompanhar, escolha motores e deixe pelo menos uma execução terminar. O histórico começa na primeira execução, por isso adicione os prompts cedo.
4

Para a app terminada, uma chave de API

O proprietário da conta cria uma chave só de leitura em Definições, Chaves de API. Fica em HIMOOSE_API_KEY no seu servidor, nunca no browser.

Ligar

Adicione o Hi, Moose ao seu agente de programação

Um comando ou uma entrada de configuração, e depois um início de sessão no browser. O MCP não precisa de chave de API, e nada vai para o ficheiro que um colega não pudesse enviar para o repositório.

Corra isto no terminal, depois inicie o Claude Code e escreva /mcp. Escolha himoose e depois Authenticate.

Terminal

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

O browser abre o início de sessão do Hi, Moose. Adicione --scope user para o ter disponível em todos os projetos.

Adicione o servidor e depois inicie sessão. A CLI do Codex e a extensão do IDE partilham esta configuração.

Terminal

codex mcp add himoose --url https://mcp.himoose.com/mcp
codex mcp login himoose

O comando de login abre o início de sessão do Hi, Moose no browser.

Adicione isto a ~/.cursor/mcp.json, ou a .cursor/mcp.json para um único projeto.

mcp.json

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

Depois abra Cursor Settings, Tools & MCP, e inicie sessão no Hi, Moose quando pedido.

Qualquer agente que consiga adicionar um servidor MCP remoto por HTTPS com início de sessão OAuth pode ligar-se.

Endereço do servidor

https://mcp.himoose.com/mcp

Deixe vazio qualquer campo de ID de cliente OAuth. O Hi, Moose regista a app durante o início de sessão.

Depois de iniciar sessão, peça ao agente para chamar list_projects. Se devolver o seu projeto, está ligado. As apps de chat como o Claude e o ChatGPT ligam-se da mesma forma; os passos estão em Ligar um agente.

Primeiro prompt

Um primeiro olhar numa sessão. Só MCP, por isso funciona no plano gratuito.

Usando o servidor MCP do Hi, Moose (https://mcp.himoose.com/mcp), constrói um relatório HTML estático em ./ai-visibility que mostre como a nossa marca aparece na pesquisa com IA para os nossos tópicos acompanhados. Não consultes motores de IA por conta própria. Eu termino o início de sessão do Hi, Moose no meu browser. Nunca me peças uma palavra-passe ou um token. Começa com list_projects e pergunta-me que projeto usar. Obtém os dados com visibility_check_topic e usa visibility_get_answer para as respostas guardadas por trás dos números. Mostra resultados por motor, a variação nos últimos 30 dias, os concorrentes nomeados e as páginas que cada motor cita. Se uma ferramenta indicar que não há dispositivo anfitrião, histórico de visibilidade ou histórico suficiente para uma comparação, para e diz-me o que configurar no Hi, Moose em vez de estimar.

Um painel que a sua equipa abre no browser. MCP enquanto constrói, REST API na app terminada. A REST API precisa de um plano pago.

Constrói um painel web interno que mostre como a nossa marca aparece na pesquisa com IA para os nossos 20 tópicos principais. Usa o Hi, Moose para todos os dados de pesquisa com IA. Não consultes motores de IA por conta própria. 1. Enquanto constróis, usa o servidor MCP do Hi, Moose (https://mcp.himoose.com/mcp) para ver que dados existem. Eu termino o início de sessão no meu browser. Nunca me peças uma palavra-passe ou um token. 2. Chama list_projects e pergunta-me que projeto usar. Verifica quantos prompts são acompanhados, que motores, e até onde recua o histórico. 3. Na app, chama a REST API do Hi, Moose (https://api.himoose.com/v1) apenas a partir do servidor, com a chave na variável de ambiente HIMOOSE_API_KEY. Nunca envies a chave para o browser. Lê o esquema em https://api.himoose.com/v1/openapi.json. 4. Mostra resultados por tópico e motor, a variação desde o mês passado, os concorrentes nomeados e as fontes que cada motor cita. Liga cada número à resposta guardada por trás dele. 5. Se faltar algo (sem prompts acompanhados para um tópico, menos de dois meses de histórico, sem concorrentes definidos), mostra-o claramente na app e diz-me o que configurar no Hi, Moose. Não estimes nem preenchas lacunas.

Ficheiro de skill

Ensine o Hi, Moose ao seu agente uma só vez

Coloque este ficheiro no seu projeto e o agente fica a saber que ferramentas chamar, por que ordem e o que fazer quando faltam dados. Cobre tanto o MCP durante o desenvolvimento como a REST API na app terminada.

Claude Code.claude/skills/himoose/SKILL.md

CodexAGENTS.md

Cursor.cursor/rules/himoose.mdc

O Codex e o Cursor leem Markdown simples, por isso cole o mesmo conteúdo sem o front matter.

SKILL.md

---
name: himoose
description: AI search visibility data from Hi, Moose. Use when the user asks how their brand appears in ChatGPT, Gemini, Perplexity, Claude or other AI search engines, or wants to build a report, dashboard or app on that data.
---

# Hi, Moose

Hi, Moose collects answers from AI search engines on a schedule, stores each one with its sources, and measures mentions, citations and competitor presence over time. Use it for that data. Do not query AI engines yourself.

## Two ways in

- MCP server: https://mcp.himoose.com/mcp (OAuth, every plan). Use during development and for work with the user present.
- REST API: https://api.himoose.com/v1 (API key, paid plans). Use in deployed apps and scheduled jobs. Call it from a server only, with the key in HIMOOSE_API_KEY. Schema: https://api.himoose.com/v1/openapi.json.

## Sign-in

Sign-in happens in the user's browser. Never ask for a password, token or API key in chat. Never put a key in client-side code.

## Order of operations

1. list_projects (MCP) or GET /v1/projects (REST). Ask the user which project to use.
2. Check what exists: tracked prompts, engines, firstAnswerDate and latestAnswerDate. History starts when a prompt is first tracked; there is no backfill.
3. Read data: visibility_check_topic for mentions, citations and competitors per engine over a window; visibility_get_answer for one stored answer with sources; visibility_list_opportunities for gaps. REST equivalents: /stats/daily, /stats/competitors, /answers, /answers/{id}.
4. Link every number you display to the answer ID behind it.

## When something is missing

If a tool reports no host device, host offline, no project, no tracked prompts or not enough history, relay the message to the user as written and say what to set up in the Hi, Moose desktop app. Do not estimate, backfill or invent visibility numbers.

## Limits

- MCP jobs run on the host device, so the desktop app must be open and signed in.
- REST reads work with the app closed. REST actions that start runs need a running app and the runs:execute scope.
- /stats/daily returns up to 366 days per request and reports incompleteDays; label those days rather than showing a dip.
- Month-over-month views need runs across both months.

O que as pessoas constroem

O seu frontend, a sua lógica, os dados do Moose

Três formas comuns, com as chamadas que cada uma faz. A interface, a marca, o alojamento e tudo o que é específico do seu negócio é seu.

Painel interno

Visibilidade por tópico e motor, variação desde o mês passado, concorrentes e as fontes que cada motor cita.

GET /v1/projects/{id}/stats/dailyGET /v1/projects/{id}/stats/competitorsGET /v1/projects/{id}/answers/{answerId}

Precisa de cerca de dois meses de execuções para a comparação.

Resumo semanal no Slack

Um trabalho agendado que compara esta semana com as últimas quatro e publica a quota de voz, uma resposta citada e qualquer fonte nova.

GET /v1/projects/{id}/stats/competitorsGET /v1/projects/{id}/answers?mentioned=false

Corre sem ninguém presente, por isso REST com uma chave só de leitura.

Portal de clientes para agências

Um início de sessão por cliente, cada um associado aos projetos Hi, Moose que pode ver. A sua marca e exportação para PDF.

GET /v1/projectsGET /v1/projects/{id}/stats/daily

Um projeto por marca de cliente. As chaves podem ser limitadas aos projetos escolhidos.

Um agente de programação consegue escrever um coletor numa tarde. O que não consegue é mantê-lo a funcionar. Essa é a parte que o Hi, Moose lhe tira das mãos.

Um método de recolha diferente por motorAlterações de motores e interfaces, detetadas e corrigidasAgendamento diário, novas tentativas e limites de pedidosGuardar cada resposta para que continue comparável um ano depoisDetetar marcas, concorrentes e citações em texto livreDistinguir uma queda real de uma execução incompleta

Referência

MCP e REST, lado a lado

MCPREST API

Endereço MCP: https://mcp.himoose.com/mcp REST API: https://api.himoose.com/v1

Ideal para MCP: Agentes de programação e assistentes de IA a trabalhar com uma pessoa REST API: Aplicações, portais e trabalhos agendados que a sua equipa implementa

Autenticação MCP: OAuth 2.1. Uma pessoa inicia sessão com a sua conta Hi, Moose num browser. Sem chaves para guardar. REST API: Chave de API secreta num cabeçalho Authorization: Bearer. As chaves começam por hmk_live_ e são mostradas uma vez.

De onde chamar MCP: A partir do agente, depois de iniciar sessão REST API: Apenas do seu servidor. A API não aceita chamadas de browsers.

Plano MCP: Todos os planos, incluindo o gratuito REST API: Planos pagos. O proprietário da conta cria chaves em Definições, Chaves de API.

Permissões MCP: Ler projetos e dados de visibilidade, e criar trabalho na Biblioteca. Não pode publicar, eliminar ou alterar definições. REST API: Leitura por predefinição. Âmbitos opcionais para alterar o acompanhamento (tracking:write) e iniciar execuções (runs:execute). As chaves podem ser limitadas a projetos escolhidos e expirar ao fim de 30, 90 ou 365 dias.

Com a app fechada MCP: Os trabalhos correm no dispositivo anfitrião, por isso tem de estar ligado com o Hi, Moose aberto e com sessão iniciada. REST API: As leituras funcionam, porque são servidas a partir da cloud. As execuções que precisam do seu anfitrião esperam por ele até 24 horas.

Respostas MCP: Resultados de ferramentas estruturados com IDs de resposta. Mensagens claras indicam o que falta. REST API: JSON com paginação por cursor e erros Problem Details. Cada resposta indica a sua quota diária de pedidos.

Esquema MCP: tools/list depois de iniciar sessão REST API: https://api.himoose.com/v1/openapi.json

Ferramentas MCP para dados de visibilidade

Servidor https://mcp.himoose.com/mcp. As ferramentas de briefs, rascunhos e auditoria estão listadas em Ligar um agente.

list_projectsProjetos da conta com sessão iniciada

visibility_check_topicMenções, citações e concorrentes por motor para um tópico, agora e numa janela

visibility_get_answerUma resposta guardada por inteiro, com fontes

visibility_list_opportunitiesLacunas priorizadas, com as páginas que os motores citam em vez disso

get_resultRecolher um trabalho terminado por ID

Endpoints REST

URL base https://api.himoose.com/v1. Os esquemas exatos estão em /v1/openapi.json.

GET /v1/projectsProjetos que a chave pode ler

GET /v1/projects/{id}Um projeto, com prompts acompanhados, motores e datas do histórico

GET /v1/projects/{id}/topicsTópicos e os prompts que contêm

GET /v1/projects/{id}/stats/dailyTaxas de menção e citação por dia e motor, até 366 dias

GET /v1/projects/{id}/stats/competitorsQuota de voz para um intervalo de datas

GET /v1/projects/{id}/answersRespostas guardadas, filtráveis por motor, prompt, tópico, execução, mencionado e citado

GET /v1/projects/{id}/answers/{answerId}Uma resposta por inteiro, com fontes

POST /v1/projects/{id}/run-requestsIniciar uma execução (precisa de runs:execute)

Um pedido a partir do seu servidor

curl "https://api.himoose.com/v1/projects/q7Rk2mBw/stats/daily?from=2026-10-05&to=2026-10-11&engine=gemini" \
  -H "Authorization: Bearer $HIMOOSE_API_KEY"

{
  "from": "2026-10-05",
  "to": "2026-10-11",
  "incompleteDays": 0,
  "data": [
    {
      "date": "2026-10-05",
      "engineId": "gemini",
      "answers": 40,
      "mentioned": 4,
      "cited": 0,
      "mentionRate": 0.1,
      "citationRate": 0
    },
    {
      "date": "2026-10-06",
      "engineId": "gemini",
      "answers": 40,
      "mentioned": 3,
      "cited": 0,
      "mentionRate": 0.075,
      "citationRate": 0
    },
    /* …five more days */
  ]
}

Uma linha por dia e motor. incompleteDays conta os dias do intervalo ainda não resumidos, para que a sua app os possa assinalar em vez de mostrar uma queda. Os valores são dados de exemplo.

Perguntas sobre construir com o Hi, Moose

A minha app deve usar MCP ou a REST API?

Use MCP quando um agente faz o trabalho com uma pessoa presente, no Claude Code, Codex, Cursor, Claude ou ChatGPT. Use a REST API quando a sua própria aplicação ou um trabalho agendado chama o Hi, Moose a partir de um servidor. Muitos projetos usam ambos: MCP enquanto o agente explora e constrói, a REST API na app que entrega.

Uma app no browser pode chamar a API diretamente?

Não. A API não aceita chamadas de browsers, e uma chave de API em código do lado do cliente ficaria exposta. Chame-a a partir do seu servidor, de uma função serverless ou de um trabalho agendado, e envie ao seu frontend apenas os dados de que precisa.

Quanto histórico precisa a minha app?

Um instantâneo por motor precisa de uma execução concluída. As comparações mês a mês precisam de execuções em ambos os meses. O histórico começa quando um prompt é acompanhado pela primeira vez, por isso adicione cedo os prompts que lhe interessam.

A app de desktop tem de ficar aberta?

Para MCP, sim: os trabalhos correm no dispositivo anfitrião que escolhe em Definições, Agentes ligados. Para leituras REST, não: são servidas a partir da cloud. As execuções que precisam do seu anfitrião esperam por ele até 24 horas.

Posso correr a app noutro sítio que não o meu portátil?

Sim. Instale-a num alojamento que controla e deixe-a a correr, ou deixe o Hi, Moose corrê-la num servidor dedicado na sua região. Ambas as opções estão descritas na página de infraestrutura.

Posso construir uma app para os meus clientes?

Sim. As agências usam um projeto por marca de cliente e limitam uma chave de API aos projetos que um portal deve ler. O portal, a sua marca e os inícios de sessão dos seus clientes são seus para construir.

Ligar um agenteConfiguração para o Claude e o ChatGPT, e a lista completa de ferramentas. Visão geral da infraestruturaComo o Hi, Moose recolhe e guarda respostas, e onde pode correr. Documentação da APIEndpoints, parâmetros, erros e a especificação OpenAPI. Transferir a app de desktopNecessária para a recolha. Mac ou PC.

Construa as suas próprias ferramentas de visibilidade em IA. Salte a construção do coletor.