LetsFindWhy

Agentes e a API

Um agente é um assistente de IA que trabalha na LetsFindWhy em seu nome: o Claude Code, uma rotina agendada do Claude, um assistente de editor ou qualquer outra ferramenta que fale o Model Context Protocol (MCP). Dê a ele uma chave de API e ele pode configurar projetos, escrever guias de discussão, convidar respondentes e ler transcrições e insights a partir de um chat, usando exatamente o acesso que você tem.

Tudo o que um agente pode fazer, você também pode fazer com chamadas HTTP simples à API REST. Ambos usam a mesma chave.

Como criar uma chave de API

  1. Abra Configurações e encontre o cartão Chaves de API.
  2. Crie uma chave e dê a ela um nome que diga qual agente vai usá-la, como “Claude Code no meu notebook”. Uma chave por agente facilita revogar uma sem perturbar as outras.
  3. Copie a chave imediatamente. Ela começa com mtg_ e é mostrada apenas uma vez; se você a perder, exclua-a e crie outra.

Uma chave é sua, não de uma organização. Um agente que a possui vê todas as organizações às quais você pertence, com o papel que você tem em cada uma, e tudo o que ele faz é registrado como feito por você. Trate a chave como uma senha e revogue-a assim que parar de usar o agente. Uma conexão feita por login tem o mesmo alcance que uma chave e, como uma chave, sobrevive a sair da conta e a trocar sua senha. Desconectá-la é um passo separado, descrito abaixo.

Como conectar o claude.ai

O claude.ai se conecta por URL e login, sem nenhuma chave para colar. Uma conexão feita no claude.ai cobre também o Claude Desktop e os apps móveis do Claude.

  1. No claude.ai, abra Configurações, depois Conectores, e escolha Adicionar conector personalizado.
  2. Digite https://letsfindwhy.com/api/mcp como URL, exatamente como está escrita e sem barra no final, e deixe o ID de cliente e o segredo em branco.
  3. Escolha Conectar. A LetsFindWhy pede que você entre, se ainda não tiver entrado, e depois mostra o que a conexão pode fazer; escolha Permitir.

Para encerrar uma conexão, abra Configurações na LetsFindWhy e escolha Desconectar no cartão Agentes conectados. Essa é a única forma de revogá-la: remover o conector no Claude impede que o Claude o use, mas um conector adicionado de novo mais tarde entra direto outra vez. Remova-o nos dois lugares para que o Claude pare de pedir que você entre de novo.

Como conectar o Claude Code

O Claude Code pode entrar do mesmo jeito. Execute isto uma vez, depois digite /mcp no Claude Code e escolha Authenticate; uma janela do navegador se abre para o login. Essa é uma conexão separada da que o claude.ai mantém, e aparece separadamente em Configurações.

claude mcp add --transport http letsfindwhy https://letsfindwhy.com/api/mcp

Para scripts, uso sem interface ou qualquer cliente que permita definir um cabeçalho de requisição, cole uma chave em vez disso:

claude mcp add --transport http letsfindwhy https://letsfindwhy.com/api/mcp --header "Authorization: Bearer mtg_..."

O Claude Code então lista uma ferramenta para cada coisa que você pode fazer na LetsFindWhy, nomeada pelo que faz: create_project, create_discussion_guide_with_questions, invite_recruited_respondents_to_session, get_session_transcript e assim por diante. Peça o que quiser em palavras simples e ele escolhe as ferramentas.

Cursor, scripts e outros clientes que permitem definir um cabeçalho de requisição funcionam do mesmo jeito. Os diretórios de conectores do claude.ai e do Claude Desktop não conseguem enviar um cabeçalho; em vez disso, eles se conectam por URL e login, como descrito acima.

O que um agente pode e não pode fazer

Um agente trabalha como você. Ele prepara e lê pesquisas; não conduz entrevistas nem gerencia sua equipe.

Ele pode:

  • Criar e atualizar organizações, projetos, processos, guias de discussão e questionários de triagem.
  • Gerenciar o recrutamento: abrir e fechar links de inscrição, adicionar respondentes manualmente e convidá-los para sessões.
  • Preparar sessões com antecedência: criá-las, alterar suas configurações, atribuir um guia e editar suas perguntas.
  • Ler resultados: gravações, transcrições, respostas, insights de IA e uso.

Ele não pode:

  • Mexer em uma entrevista ao vivo. Iniciar, encerrar, admitir pessoas, removê-las e chamar ou dispensar o moderador IA ficam com as pessoas na sala.
  • Mudar quem está na sua organização: ele não pode alterar papéis, remover membros, transferir a propriedade, sair nem excluir a organização.
  • Excluir gravações. Excluir uma gravação também exclui sua transcrição, então isso continua sendo uma decisão que você toma no aplicativo.

A linha está onde está porque um agente lê o que os respondentes disseram, e um respondente pode dizer algo feito para manipulá-lo. Seja o que for que ele leia, não pode trancar você fora da sua própria organização nem apagar sua pesquisa.

Excluir um projeto, sessão, processo, guia ou questionário de triagem é permitido. Projetos e sessões podem ser restaurados por 30 dias, e seu agente pedirá confirmação antes de qualquer exclusão.

Como chamar a API REST diretamente

Por baixo, toda ferramenta é um endpoint REST. Envie sua chave como Authorization: Bearer mtg_... e navegue pela referência completa, com cada endpoint e seus parâmetros, em /api/docs depois de fazer login.

As chaves são limitadas a rajadas curtas: 60 chamadas em um segundo pela API REST e cerca de 30 via MCP, onde cada chamada de ferramenta verifica a chave duas vezes. Nenhum agente que pensa atinge nenhum dos dois. Uma chamada que ultrapassa recebe uma resposta 429 dizendo quanto tempo esperar.