Usercall

Dale a tus agentes de IA la capacidad de preguntar a usuarios reales por qué.

Documentación

Usercall MCP - Agentes de IA que realizan entrevistas reales con usuarios

La IA puede construir productos. Pero todavía no habla con los usuarios.

Dale a tus agentes de IA la capacidad de preguntar a usuarios reales por qué.

Usercall MCP ejecuta entrevistas de voz o texto moderadas por IA con usuarios reales. Úsalo para saber por qué los usuarios se dan de baja, dónde falla la incorporación, o por qué falló una acción, y obtén temas, perspectivas y citas textuales.

Por qué existe esto

Los agentes de IA ahora pueden construir y lanzar productos extremadamente rápido.

Pero la mayoría de los agentes todavía dependen de comentarios sintéticos o suposiciones sobre los usuarios.

Usercall MCP permite a los agentes recopilar comentarios cualitativos reales directamente de los usuarios.

Elige una conexión

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

Añade https://mcp.usercall.co como conector MCP remoto / conector personalizado.

Inicio de sesión OAuth (sin clave API, sin npx)
Mismas herramientas que este paquete (estudios + Research Triggers)
Documentación: app.usercall.co/docs/mcp
Cursor Directory / Grok Bot: este repositorio incluye .mcp.json para que cursor.directory pueda instalar el conector alojado. Grok Bot no puede ejecutar el paquete local npx.

Este paquete: local / clave API / máquina a máquina

Usa @usercall/mcp sobre stdio cuando quieras una clave API Bearer (scripts, clientes locales, M2M).

Inicia sesión en app.usercall.co → Inicio → Desarrollador → Crear clave API
Ejecuta npx -y @usercall/mcp con USERCALL_API_KEY

Flujo de trabajo de ejemplo

Agent: "Why are users confused about onboarding?"

→ create_study
→ share interview_link with users
→ get_study_results

El interview_link devuelto se puede compartir con los participantes a través de correo electrónico, Slack, Discord o mensajes dentro del producto.

Resultado de ejemplo:

{
  "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."]
    }
  ]
}

Cómo funciona

Agente de IA

↓

Usercall MCP (OAuth alojado o este paquete stdio)

↓

API de agente de Usercall

↓

Entrevistas reales con usuarios

↓

Temas y citas textuales devueltos al agente

Con Research Triggers, el agente también puede dirigirse a usuarios dentro de tu producto:

Analytics MCP (PostHog, Mixpanel, …) detecta un comportamiento

↓

Usercall MCP crea un estudio y un Research Trigger en pausa

↓

Lo activas en Usercall

↓

El SDK de Usercall invita a los usuarios que coinciden a una entrevista justo después del comportamiento

Research Triggers

Analytics le dice a un agente qué hacen los usuarios. Los Research Triggers le permiten preguntarles 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>"

El SDK de Usercall debe estar instalado. Si list_trigger_events no devuelve nada, llama a get_trigger_sdk_setup (con tu proveedor de analytics y nombres de eventos) para obtener el fragmento de código. Los agentes de programación pueden instalarlo por ti.
Solo se pueden usar eventos que Usercall haya recibido realmente. Los filtros son coincidencias exactas en propiedades de eventos o rasgos de usuarios. get_trigger_event_schema muestra qué campo es cuál.
Las condiciones no compatibles se rechazan, no se ignoran silenciosamente. Estas incluyen conteos de eventos, secuencias, ausencia ("no hizo X"), ventanas de tiempo y no-igual. get_trigger_capabilities devuelve la lista completa.

Instalación local (clave API)

1. Obtén una clave API

Inicia sesión en app.usercall.co → Inicio → Desarrollador → Crear clave API

2. Añádelo a tu 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 de Claude, ChatGPT o Cursor, prefiere https://mcp.usercall.co en lugar de esta configuración JSON.

Reinicia tu cliente MCP.

3. Pregunta a tu 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

El agente:

creará un estudio
devolverá un enlace de entrevista
recopilará las respuestas
devolverá el resumen (temas, perspectivas y riesgos)

Ejemplo de herramienta estructurada

Llamada de herramienta 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"

Herramientas

`create_study`

Crea un estudio de entrevista moderado por IA para saber por qué los usuarios se dan de baja, fallan en la incorporación, fallan una acción o dónde una suposición de producto es incorrecta. Devuelve study_id y interview_link para una entrevista de voz, texto o voz y texto. key_research_goal es obligatorio y no se puede cambiar después. business_context es opcional. Valores predeterminados: target_interviews 1, duration_minutes 12, interview_mode voz. Un estudio de agente activo por cuenta. No ejecuta la entrevista ni invita a un participante. HTTP 402 incluye checkout_url.

Campo	Tipo	Obligatorio	Predeterminado
`key_research_goal`	cadena (5–2000)	sí
`business_context`	cadena (5–2000)	no
`additional_context_prompt`	cadena	no
`target_interviews`	número (1–200)	no	`1`
`languages`	cadena[]	no
`duration_minutes`	número (5–65)	no	`12`
`interview_mode`	`voice \| text \| voice_and_text`	no	`voice`
`voice_gender`	`female \| male`	no
`enable_link_context`	booleano	no
`custom_link_variables`	`{ key, label?, default_value? }[]`	no
`metadata`	objeto	no
`study_media`	objeto	no

Una configuración regional desactiva el selector de idioma; dos o más lo activan. El objetivo de la investigación no se puede cambiar después de la creación.

study_media (opcional). Estímulo visual mostrado durante todas las preguntas de la entrevista:

Campo	Tipo	Obligatorio
`type`	`image \| prototype`	sí
`url`	cadena (URL)	sí
`description`	cadena (máx. 500 caracteres)	no

image: URL de imagen directa (.png, .jpg, .gif, .webp)
prototype: URL de prototipo de Figma (convertido a inserción interactiva)
El contenido multimedia solo es visible para participantes web; los que llaman por teléfono no lo verán

`update_study`

Actualiza un estudio de entrevista: espacios, preguntas de la guía, introducción, idiomas, voz, o una imagen o prototipo de Figma mostrado a los participantes. Devuelve el estudio actualizado. key_research_goal no se puede cambiar. is_link_disabled verdadero detiene nuevas entrevistas y conserva las grabaciones. Una configuración regional oculta el selector de idioma; dos o más lo muestran. Los parámetros de consulta en interview_link se ignoran hasta que enable_link_context sea verdadero. study_media nulo borra el contenido multimedia. Los errores de API incluyen http_status. No hace una prueba de la guía ni invita a un participante.

Campo	Tipo	Obligatorio
`study_id`	cadena uuid	sí
`target_interviews`	número (1–200)	no
`is_link_disabled`	booleano	no
`ai_agent_intro_message`	cadena	no
`key_learning_goals`	cadena	no
`workflow_end_message`	cadena	no
`workflow_questions`	`{ text, ... }[]`	no
`interview_mode`	`voice \| text \| voice_and_text`	no
`languages`	cadena[]	no
`voice_gender`	`female \| male`	no
`enable_link_context`	booleano	no
`custom_link_variables`	`{ key, label?, default_value? }[]`	no
`study_media`	objeto o `null`	no

Pasa study_media: null para borrar el contenido multimedia. El objeto study_media sigue el mismo esquema que en create_study.

`get_study_status`

Comprueba si las entrevistas con usuarios todavía están en curso, en análisis o completadas. Devuelve completed_interviews, target_interviews, interview_link y next_step. running y analyzing no incluyen hallazgos, temas ni citas. No cambia el estudio.

Campo	Tipo
`study_id`	cadena uuid

Valores de estado: running · analyzing · complete

La respuesta incluye campos de progreso de la entrevista, incluyendo completed_interviews y target_interviews.

`get_study_results`

Obtén los hallazgos de la entrevista después de que los usuarios reales hayan hablado: temas, perspectivas, riesgos y citas textuales. format omitido o summary devuelve temas, perspectivas y riesgos. format=full también devuelve transcripciones. Temas vacíos significan que el análisis no está listo. No crea entrevistas ni edita la guía.

Campo	Tipo	Obligatorio
`study_id`	cadena uuid	sí
`format`	`summary \| full`	no

Las respuestas de resumen/completas incluyen campos de progreso del estudio y resultados del análisis.

`simulate_interview`

Haz una prueba de una guía de entrevista antes de que se una un participante real, incluyendo una pregunta sobre abandono, incorporación o una acción fallida. Omite simulation_id para comenzar; devuelve inmediatamente con estado running y un simulation_id. Pasa simulation_id para leer esa ejecución. El estado del resultado es pass, fail o error. Máximo 5 simulaciones por cuenta por día UTC. HTTP 429 significa que se alcanzó el límite diario. El persona opcional tiene name y prompt. Una prueba no cambia completed_interviews y no invita a un participante.

Campo	Tipo	Obligatorio
`study_id`	cadena uuid	sí
`simulation_id`	cadena uuid	no
`persona`	`{ name, prompt }`	no

Omite simulation_id para POST /api/v1/agent/studies/{studyId}/simulations. Pasa simulation_id para GET esa simulación. La herramienta no hace sondeos.

`review_study`

Revisa una guía de entrevista y devuelve una crítica escrita de las preguntas antes de que los usuarios reales las vean. Solo lee la guía: sin transcripciones, y las ediciones sugeridas no se aplican. Cuesta 1 crédito. La solicitud es solo study_id; call_ids no se aceptan. Funciona cuando el control de revisión en la aplicación está oculto. HTTP 402 incluye checkout_url. No devuelve temas, citas ni otros hallazgos.

Campo	Tipo	Obligatorio
`study_id`	cadena uuid	sí

Envía solo study_id. No envía call_ids.

`delete_study`

Elimina permanentemente un estudio de entrevista, sus grabaciones y los créditos reservados no utilizados. No se puede deshacer. No elimina los research triggers dentro del producto.

Campo	Tipo	Obligatorio
`study_id`	cadena uuid	sí

Herramientas de Research Trigger

Herramienta	Propósito
`get_trigger_capabilities`	Qué condiciones de activación dentro del producto funcionan. Un evento, propiedad o rasgo exacto, regla de URL, permanencia en página. Sin conteos, secuencias, ausencias, ventanas de tiempo ni desigualdades
`get_trigger_sdk_setup`	Fragmento para eventos de producto (acción fallida, incorporación, abandono). `install_snippet`, `identify_snippet`, `allowlist_update_snippet`. Sin claves secretas
`list_trigger_events`	Nombres de eventos de producto de los últimos 30 días. Una activación solo acepta un nombre observado
`get_trigger_event_schema`	Campos en un evento de producto, con tipos y valores de muestra. Exacto, sensible a mayúsculas y minúsculas, sensible a tipos
`list_studies`	Estudios de entrevista existentes: `study_id`, `interview_link`, `interview_mode`, `trigger_eligible`
`create_research_trigger`	Invitación pausada después de un momento de producto (acción fallida, abandono, incorporación). Devuelve `activation_url`
`list_research_triggers`	Activaciones dentro del producto con estado y `activation_url`
`get_research_trigger`	Una activación: a quién invita, `activation_url`, conteos de invitación y entrevista. Sin temas ni citas
`update_research_trigger`	Quién recibe la invitación. `status: "active"` se rechaza (409). Editar una activación activa la pausa
`delete_research_trigger`	Eliminar permanentemente una activación. Las entrevistas completadas permanecen en el estudio

`create_research_trigger`

Campo	Tipo	Requerido	Predeterminado
`study_id`	cadena uuid	sí
`event_name`	cadena (de `list_trigger_events`)	sí
`properties`	objeto de valores de coincidencia exacta	no
`traits`	objeto de valores de coincidencia exacta	no
`url`	`{ match: equals \| contains \| starts_with, value }`	no
`dwell_seconds`	1–600 (solo activaciones de visita a página)	no
`source`	`page_visit` \| `analytics_event` \| `custom`	no
`sampling_percent`	1–100	no	100
`cooldown_days`	0–365	no	30
`max_invites_per_day`	1–100	no	100
`intercept_title`	cadena (≤120), etiqueta pequeña sobre el mensaje	no	predeterminado
`intercept_body`	cadena (≤500), texto del mensaje	no	predeterminado
`delivery_method`	`intercept` \| `webhook`	no	intercepción
`webhook_url`	URL https pública (requerida para `webhook`)	no
`webhook_secret`	cadena (16–200), clave HMAC, solo escritura	no
`invite_link_params`	`{ static?, from_traits?, from_properties? }`	no
`name`	cadena (≤100)	no	generado

Para activaciones de visita a página, usa source: "page_visit" y event_name: "$pageview", con url y opcionalmente dwell_seconds.

Entrega.

intercept (predeterminado) muestra el widget de Usercall en tu producto, y el usuario realiza una entrevista de voz o texto en la página. Los modos provienen del estudio; list_studies devuelve el interview_mode de cada estudio.
webhook envía por POST cada usuario coincidente a webhook_url, con su ID de usuario, correo electrónico si se conoce, rasgos, propiedades de evento y un enlace de entrevista personal. Si webhook_secret está configurado, las solicitudes llevan un encabezado HMAC x-usercall-signature.
Solo se aceptan URLs públicas https, y la página de activación muestra el destino antes de que una persona active la activación.

Seguridad

Los agentes no pueden activar activaciones. Las activaciones siempre se crean pausadas. Llamar a update_research_trigger con status: "active" devuelve HTTP 409 y el activation_url. Una persona tiene que abrir ese enlace, revisar quién será invitado, qué verá y el costo de créditos, y hacer clic en Activar.
Los cambios en una activación activa requieren nueva aprobación. Cambiar la configuración de una activación activa la pausa nuevamente.
Las claves secretas nunca se devuelven. La clave secreta de ingesta nunca regresa de ninguna herramienta.

Flujo de trabajo de ejemplo

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

Con 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 prototipos de Figma, usa type: "prototype" con una URL de prototipo de Figma.

Requisitos

Node.js 18+
Una clave de API de Usercall válida (solo ruta local / clave de API)

Autoalojamiento / desarrollo

pnpm install
pnpm build
USERCALL_API_KEY="your_key_here" pnpm start

Pruebas y pruebas de humo:

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 de MCP

Usercall está listado en el Registro oficial de MCP como co.usercall/mcp.

Solución de problemas

Error	Solución
`Missing USERCALL_API_KEY`	Establece la variable de entorno antes de iniciar este paquete stdio
`401 Unauthorized`	Clave de API inválida o revocada
`402 Insufficient credits`	Abre el `checkout_url` devuelto, o agrega créditos en app.usercall.co
`500` al crear	Verifica que tu clave tenga acceso a la API de agente v1
`event_not_observed`	Usercall no ha recibido el evento. Agrégalo a la lista de permitidos de tu SDK (`get_trigger_sdk_setup(events=[...])`), actívalo en tu aplicación y reintenta
`wrong_placement`	El campo es un rasgo, no una propiedad (o viceversa). Usa la corrección sugerida en el error
Los filtros de rasgos nunca coinciden	Llama a `window.usercall.identify({ userId, traits })` cuando el usuario sea conocido (ver `identify_snippet`)
`webhook_url_not_allowed`	Usa una URL pública `https`, sin credenciales; localhost e IPs privadas se rechazan
`409 activation_required`	Esperado: los agentes no pueden activar. Comparte `activation_url` con el usuario
`429` en `simulate_interview`	El límite es de 5 simulaciones por cuenta por día UTC. Detente por el día
La activación activa nunca se dispara	Verifica que el evento siga llegando (`list_trigger_events`), y que los valores coincidan exactamente (mayúsculas, minúsculas y tipo)

Los conectores remotos de Claude / ChatGPT / Cursor deben usar https://mcp.usercall.co (OAuth). Este paquete es la ruta stdio de clave de API.

Licencia

MIT