Usercall

Dê aos seus agentes de IA a capacidade de perguntar aos usuários reais o porquê.

Documentação

Usercall MCP - Agentes de IA que realizam entrevistas reais com usuários

A IA pode construir produtos. Mas ainda não conversa com usuários.

Dê aos seus agentes de IA a capacidade de perguntar a usuários reais o porquê.

Usercall MCP executa entrevistas de voz ou texto moderadas por IA com usuários reais. Use-o para descobrir por que usuários cancelam, onde a integração falha, ou por que uma ação falhou, e obtenha temas, insights e citações literais.

Por que isso existe

Agentes de IA agora podem construir e lançar produtos extremamente rápido.

Mas a maioria dos agentes ainda depende de feedback sintético ou suposições sobre usuários.

Usercall MCP permite que agentes coletem feedback qualitativo real diretamente de usuários.

Escolha uma conexão

Recomendado: MCP hospedado (Claude, ChatGPT, Cursor, Grok Bot)

Adicione https://mcp.usercall.co como um conector MCP remoto / conector personalizado.

Login OAuth (sem chave de API, sem npx)
Mesmas ferramentas deste pacote (estudos + Research Triggers)
Documentação: app.usercall.co/docs/mcp
Cursor Directory / Grok Bot: este repositório inclui .mcp.json para que cursor.directory possa instalar o conector hospedado. Grok Bot não pode executar o pacote local npx.

Este pacote: local / chave de API / máquina a máquina

Use @usercall/mcp via stdio quando quiser uma chave de API Bearer (scripts, clientes locais, M2M).

Entre em app.usercall.co → Início → Desenvolvedor → Criar chave de API
Execute npx -y @usercall/mcp com USERCALL_API_KEY

Fluxo de trabalho de exemplo

Agent: "Why are users confused about onboarding?"

→ create_study
→ share interview_link with users
→ get_study_results

O interview_link retornado pode ser compartilhado com participantes por e-mail, Slack, Discord ou prompts no produto.

Exemplo de resultado:

{
  "themes": [
    {
      "name": "Onboarding confusion",
      "summary": "Users struggled to understand the second step.",
      "quotes": [
        "I wasn't sure what the app was asking me to do.",
        "I didn't know I had to verify my email before continuing."
      ]
    },
    {
      "name": "Pricing confusion",
      "summary": "Free plan limits were not clearly communicated.",
      "quotes": ["I wasn't sure if the free plan included analytics."]
    }
  ]
}

Como funciona

Agente de IA

↓

Usercall MCP (OAuth hospedado ou este pacote stdio)

↓

Usercall Agent API

↓

Entrevistas reais com usuários

↓

Temas e citações literais retornados ao agente

Com Research Triggers, o agente também pode segmentar usuários no seu produto:

Analytics MCP (PostHog, Mixpanel, …) identifica um comportamento

↓

Usercall MCP cria um estudo e um Research Trigger pausado

↓

Você o ativa no Usercall

↓

O SDK do Usercall convida usuários correspondentes para uma entrevista logo após o comportamento

Research Triggers

O Analytics diz ao agente o que os usuários fazem. Os Research Triggers permitem que ele pergunte a eles por quê.

User:  "Look at our PostHog data and find something worth investigating."

Agent (PostHog MCP):  users who test a study rarely launch one.

Agent (Usercall MCP):
  list_trigger_events()                  → study_tested, study_launched, …
  get_trigger_event_schema("study_tested")
                                         → properties: source, interview_type
                                           traits: plan ("free", "pro"), account_type
  create_study(...)  or  list_studies()
  create_research_trigger({
    study_id, event_name: "study_tested",
    traits: { plan: "free" }, sampling_percent: 25, max_invites_per_day: 10
  })                                     → status: "paused", summary, activation_url

Agent: "I've prepared a Research Trigger. When: study_tested · Audience: plan = free ·
        25% sampled · max 10 invites/day. It's paused. A human activates it here: <activation_url>"

O SDK do Usercall precisa estar instalado. Se list_trigger_events não retornar nada, chame get_trigger_sdk_setup (com seu provedor de analytics e nomes de eventos) para obter o snippet. Agentes de codificação podem instalá-lo para você.
Somente eventos que o Usercall realmente recebeu podem ser usados. Filtros são correspondências exatas em propriedades de eventos ou atributos de usuários. get_trigger_event_schema mostra qual campo é qual.
Condições não suportadas são rejeitadas, não descartadas silenciosamente. Isso inclui contagens de eventos, sequências, ausência ("não fez X"), janelas de tempo e diferentes-de. get_trigger_capabilities retorna a lista completa.

Instalação local (chave de API)

1. Obtenha uma chave de API

Entre em app.usercall.co → Início → Desenvolvedor → Criar chave de API

2. Adicione ao seu cliente MCP

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "usercall": {
      "command": "npx",
      "args": ["-y", "@usercall/mcp"],
      "env": {
        "USERCALL_API_KEY": "your_key_here"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "usercall": {
      "command": "npx",
      "args": ["-y", "@usercall/mcp"],
      "env": {
        "USERCALL_API_KEY": "your_key_here"
      }
    }
  }
}

Para conectores remotos do Claude, ChatGPT ou Cursor, prefira https://mcp.usercall.co em vez desta configuração JSON.

Reinicie seu cliente MCP.

3. Pergunte ao seu agente

Run user interviews to understand why users drop off during onboarding.

Context:
- B2B SaaS product
- 3-step signup flow

Goal:
Identify confusion points and friction.

Target interviews: 5
Language: ko
Interview mode: voice

Show participants this prototype during the interview:
https://www.figma.com/proto/abcd1234/onboarding-flow

O agente irá:

criar um estudo
retornar um link de entrevista
coletar respostas
retornar o resumo (temas, insights e riscos)

Exemplo de ferramenta estruturada

Chamada de ferramenta create_study equivalente:

create_study
key_research_goal: "Understand why users drop off during onboarding"
business_context: "B2B SaaS signup flow"
target_interviews: 5
languages: ["en"]
interview_mode: "voice"

study_media:
  type: "prototype"
  url: "https://www.figma.com/proto/abcd1234/onboarding-flow"
  description: "New onboarding flow concept"

Ferramentas

`create_study`

Crie um estudo de entrevista moderado por IA para descobrir por que usuários cancelam, desistem na integração, falham em uma ação, ou onde uma suposição de produto está errada. Retorna study_id e interview_link para uma entrevista por voz, texto ou voz e texto. key_research_goal é obrigatório e não pode ser alterado depois. business_context é opcional. Padrões: target_interviews 1, duration_minutes 12, interview_mode voz. Um estudo de agente ativo por conta. Não executa a entrevista nem convida um participante. HTTP 402 inclui checkout_url.

Campo	Tipo	Obrigatório	Padrão
`key_research_goal`	string (5–2000)	sim
`business_context`	string (5–2000)	não
`additional_context_prompt`	string	não
`target_interviews`	number (1–200)	não	`1`
`languages`	string[]	não
`duration_minutes`	number (5–65)	não	`12`
`interview_mode`	`voice \| text \| voice_and_text`	não	`voice`
`voice_gender`	`female \| male`	não
`enable_link_context`	boolean	não
`custom_link_variables`	`{ key, label?, default_value? }[]`	não
`metadata`	object	não
`study_media`	object	não

Um idioma desativa o seletor de idioma; dois ou mais o ativam. O objetivo da pesquisa não pode ser alterado após a criação.

study_media (opcional). Estímulo visual exibido durante todas as perguntas da entrevista:

Campo	Tipo	Obrigatório
`type`	`image \| prototype`	sim
`url`	string (URL)	sim
`description`	string (máx. 500 caracteres)	não

image: URL de imagem direta (.png, .jpg, .gif, .webp)
prototype: URL de protótipo Figma (convertido em embed interativo)
A mídia só é visível para participantes na web; chamadas telefônicas não a veem

`update_study`

Atualize um estudo de entrevista: vagas, perguntas do roteiro, introdução, idiomas, voz, ou uma imagem ou protótipo Figma exibido aos participantes. Retorna o estudo atualizado. key_research_goal não pode ser alterado. is_link_disabled true interrompe novas entrevistas e mantém as gravações. Um idioma oculta o seletor de idioma; dois ou mais o exibem. Parâmetros de consulta em interview_link são ignorados até que enable_link_context seja true. study_media null limpa a mídia. Erros de API incluem http_status. Não faz teste do roteiro nem convida um participante.

Campo	Tipo	Obrigatório
`study_id`	uuid string	sim
`target_interviews`	number (1–200)	não
`is_link_disabled`	boolean	não
`ai_agent_intro_message`	string	não
`key_learning_goals`	string	não
`workflow_end_message`	string	não
`workflow_questions`	`{ text, ... }[]`	não
`interview_mode`	`voice \| text \| voice_and_text`	não
`languages`	string[]	não
`voice_gender`	`female \| male`	não
`enable_link_context`	boolean	não
`custom_link_variables`	`{ key, label?, default_value? }[]`	não
`study_media`	object ou `null`	não

Passe study_media: null para limpar a mídia. O objeto study_media segue o mesmo esquema de create_study.

`get_study_status`

Verifique se as entrevistas com usuários ainda estão em andamento, sendo analisadas ou concluídas. Retorna completed_interviews, target_interviews, interview_link e next_step. running e analyzing não incluem descobertas, temas ou citações. Não altera o estudo.

Campo	Tipo
`study_id`	uuid string

Valores de status: running · analyzing · complete

A resposta inclui campos de progresso da entrevista, incluindo completed_interviews e target_interviews.

`get_study_results`

Obtenha as descobertas da entrevista depois que usuários reais conversaram: temas, insights, riscos e citações literais. format omitido ou summary retorna temas, insights e riscos. format=full também retorna transcrições. Temas vazios significam que a análise ainda não está pronta. Não cria entrevistas nem edita o roteiro.

Campo	Tipo	Obrigatório
`study_id`	uuid string	sim
`format`	`summary \| full`	não

Respostas resumidas/completas incluem campos de progresso do estudo e saída da análise.

`simulate_interview`

Faça um teste de um roteiro de entrevista antes de um participante real entrar, incluindo uma pergunta sobre cancelamento, integração ou uma ação falha. Omita simulation_id para iniciar; retorna imediatamente com status running e um simulation_id. Passe simulation_id para ler essa execução. O status do resultado é pass, fail ou error. Máximo de 5 simulações por conta por dia UTC. HTTP 429 significa que o limite diário foi atingido. persona opcional tem name e prompt. Um teste não altera completed_interviews e não convida um participante.

Campo	Tipo	Obrigatório
`study_id`	uuid string	sim
`simulation_id`	uuid string	não
`persona`	`{ name, prompt }`	não

Omita simulation_id para POST /api/v1/agent/studies/{studyId}/simulations. Passe simulation_id para GET essa simulação. A ferramenta não faz polling.

`review_study`

Revise um roteiro de entrevista e retorne uma crítica escrita das perguntas antes que usuários reais as vejam. Lê apenas o roteiro: sem transcrições, e as edições sugeridas não são aplicadas. Custa 1 crédito. A solicitação é somente study_id; call_ids não são aceitos. Funciona quando o controle de revisão no aplicativo está oculto. HTTP 402 inclui checkout_url. Não retorna temas, citações ou outras descobertas.

Campo	Tipo	Obrigatório
`study_id`	uuid string	sim

Envia somente study_id. Não envia call_ids.

`delete_study`

Exclua permanentemente um estudo de entrevista, suas gravações e créditos reservados não utilizados. Não pode ser desfeito. Não exclui research triggers no produto.

Campo	Tipo	Obrigatório
`study_id`	uuid string	sim

Ferramentas de Research Trigger

Ferramenta	Finalidade
`get_trigger_capabilities`	Quais condições de acionamento no produto funcionam. Um evento, propriedade ou atributo exato, regra de URL, tempo de permanência na página. Sem contagens, sequências, ausência, janelas de tempo ou diferentes-de
`get_trigger_sdk_setup`	Trecho para eventos de produto (ação falha, onboarding, churn). `install_snippet`, `identify_snippet`, `allowlist_update_snippet`. Sem chaves secretas
`list_trigger_events`	Nomes de eventos de produto dos últimos 30 dias. Um acionador aceita apenas um nome observado
`get_trigger_event_schema`	Campos em um evento de produto, com tipos e valores de exemplo. Exato, sensível a maiúsculas/minúsculas, sensível a tipos
`list_studies`	Estudos de entrevista existentes: `study_id`, `interview_link`, `interview_mode`, `trigger_eligible`
`create_research_trigger`	Convite pausado após um momento de produto (ação falha, churn, onboarding). Retorna `activation_url`
`list_research_triggers`	Acionadores no produto com status e `activation_url`
`get_research_trigger`	Um acionador: quem ele convida, `activation_url`, contagens de convites e entrevistas. Sem temas ou citações
`update_research_trigger`	Quem é convidado. `status: "active"` é rejeitado (409). Editar um acionador ativo o pausa
`delete_research_trigger`	Excluir permanentemente um acionador. Entrevistas concluídas permanecem no estudo

`create_research_trigger`

Campo	Tipo	Obrigatório	Padrão
`study_id`	string uuid	sim
`event_name`	string (de `list_trigger_events`)	sim
`properties`	objeto de valores de correspondência exata	não
`traits`	objeto de valores de correspondência exata	não
`url`	`{ match: equals \| contains \| starts_with, value }`	não
`dwell_seconds`	1–600 (somente acionadores de visita à página)	não
`source`	`page_visit` \| `analytics_event` \| `custom`	não
`sampling_percent`	1–100	não	100
`cooldown_days`	0–365	não	30
`max_invites_per_day`	1–100	não	100
`intercept_title`	string (≤120), pequeno rótulo acima do prompt	não	padrão
`intercept_body`	string (≤500), texto do prompt	não	padrão
`delivery_method`	`intercept` \| `webhook`	não	interceptação
`webhook_url`	URL https pública (obrigatória para `webhook`)	não
`webhook_secret`	string (16–200), chave HMAC, somente gravação	não
`invite_link_params`	`{ static?, from_traits?, from_properties? }`	não
`name`	string (≤100)	não	gerado

Para acionadores de visita à página, use source: "page_visit" e event_name: "$pageview", com url e opcionalmente dwell_seconds.

Entrega.

intercept (padrão) mostra o widget do Usercall no seu produto, e o usuário faz uma entrevista por voz ou texto na página. Os modos vêm do estudo; list_studies retorna o interview_mode de cada estudo.
webhook envia via POST cada usuário correspondido para webhook_url, com seu ID de usuário, e-mail se conhecido, atributos, propriedades de evento e um link de entrevista pessoal. Se webhook_secret estiver definido, as solicitações carregam um cabeçalho HMAC x-usercall-signature.
Apenas URLs https públicas são aceitas, e a página de ativação mostra o destino antes de uma pessoa ativar o acionador.

Segurança

Agentes não podem ativar acionadores. Acionadores são sempre criados pausados. Chamar update_research_trigger com status: "active" retorna HTTP 409 e o activation_url. Uma pessoa precisa abrir esse link, revisar quem será convidado, o que verão e o custo em créditos, e clicar em Ativar.
Alterações em um acionador ativo precisam de nova aprovação. Alterar a configuração de um acionador ativo o pausa novamente.
Chaves secretas nunca são retornadas. A chave secreta de ingestão nunca volta de nenhuma ferramenta.

Exemplo de fluxo de trabalho

1. create_study
   key_research_goal: "Why do users drop off during onboarding?"
   business_context: "B2B SaaS, 3-step signup flow"
   target_interviews: 5
   languages: ["ko"]
   interview_mode: "voice"

   → returns { study_id, interview_link }
   (`business_context` is optional; `key_research_goal` alone still creates a study)

2. simulate_interview
   study_id
   → running, simulation_id
   call again with simulation_id
   → pass, fail, or error

3. review_study
   study_id
   → guide check only; write changes with update_study

4. Share interview_link with participants
   (email, Slack, in-product prompt, etc.)

5. get_study_status
   → "analyzing"

6. get_study_results
   → summary: themes, insights, and risks
   use format=full only for a quote

Com estímulo visual

1. create_study
   key_research_goal: "Get feedback on new dashboard design"
   business_context: "Redesigning analytics dashboard for power users"
   study_media:
     type: "image"
     url: "https://example.com/dashboard-mockup.png"
     description: "New dashboard design concept"

   → returns { study_id, interview_link }

2. After simulate_interview passes, a human shares interview_link. Participants see the mockup during the interview.

Para protótipos do Figma, use type: "prototype" com uma URL de protótipo do Figma.

Requisitos

Node.js 18+
Uma chave de API Usercall válida (somente caminho local / chave de API)

Auto-hospedagem / desenvolvimento

pnpm install
pnpm build
USERCALL_API_KEY="your_key_here" pnpm start

Testes e testes de fumaça:

pnpm test                                   # unit + MCP contract tests
USERCALL_API_KEY="your_key_here" pnpm smoke # creates a real study
USERCALL_API_KEY="your_key_here" SMOKE_STUDY_ID="<uuid>" SMOKE_EVENT_NAME="<observed event>" pnpm smoke:triggers

Registro Oficial do MCP

Usercall está listado no Registro Oficial do MCP como co.usercall/mcp.

Solução de problemas

Erro	Correção
`Missing USERCALL_API_KEY`	Defina a variável de ambiente antes de iniciar este pacote stdio
`401 Unauthorized`	Chave de API inválida ou revogada
`402 Insufficient credits`	Abra o `checkout_url` retornado, ou adicione créditos em app.usercall.co
`500` ao criar	Verifique se sua chave tem acesso à API do Agente v1
`event_not_observed`	Usercall não recebeu o evento. Adicione-o à lista de permissões do seu SDK (`get_trigger_sdk_setup(events=[...])`), acione-o no seu aplicativo e tente novamente
`wrong_placement`	O campo é um atributo, não uma propriedade (ou o contrário). Use a correção sugerida no erro
Filtros de atributos nunca correspondem	Chame `window.usercall.identify({ userId, traits })` quando o usuário for conhecido (veja `identify_snippet`)
`webhook_url_not_allowed`	Use uma URL `https` pública, sem credenciais; localhost e IPs privados são rejeitados
`409 activation_required`	Esperado: agentes não podem ativar. Compartilhe `activation_url` com o usuário
`429` em `simulate_interview`	O limite é de 5 simulações por conta por dia UTC. Pare por hoje
Acionador ativo nunca dispara	Verifique se o evento ainda está chegando (`list_trigger_events`) e se os valores correspondem exatamente (maiúsculas/minúsculas e tipo)

Conectores remotos do Claude / ChatGPT / Cursor devem usar https://mcp.usercall.co (OAuth). Este pacote é o caminho stdio com chave de API.

Licença

MIT