LetsFindWhy

Agentes y la API

Un agente es un asistente de IA que trabaja en LetsFindWhy en tu nombre: Claude Code, una rutina programada de Claude, un asistente del editor o cualquier otra herramienta que hable el Model Context Protocol (MCP). Dale una clave de API y podrá configurar proyectos, escribir guías de discusión, invitar a encuestados y leer transcripciones e insights desde un chat, con exactamente el acceso que tú tienes.

Todo lo que puede hacer un agente, también puedes hacerlo tú con llamadas HTTP normales a la API REST. Ambos usan la misma clave.

Cómo crear una clave de API

  1. Abre Configuración y busca la tarjeta Claves de API.
  2. Crea una clave y dale un nombre que diga qué agente la tendrá, como “Claude Code en mi portátil”. Una clave por agente facilita revocar una sin afectar a las demás.
  3. Copia la clave de inmediato. Empieza por mtg_ y se muestra solo una vez; si la pierdes, elimínala y crea otra.

Una clave es tuya, no de una organización. Un agente que la tenga ve todas las organizaciones a las que perteneces, con el rol que tienes en cada una, y todo lo que hace se registra como hecho por ti. Trata la clave como una contraseña y revócala en cuanto dejes de usar el agente. Una conexión creada al iniciar sesión tiene el mismo alcance que una clave y, como una clave, sobrevive al cierre de sesión y al cambio de contraseña. Desconectarla es un paso aparte, descrito más abajo.

Cómo conectar claude.ai

claude.ai se conecta mediante una URL y un inicio de sesión, sin ninguna clave que pegar. Una conexión creada en claude.ai cubre también Claude Desktop y las aplicaciones móviles de Claude.

  1. En claude.ai, abre Configuración, luego Conectores y elige Añadir conector personalizado.
  2. Introduce https://letsfindwhy.com/api/mcp como URL, exactamente como está escrita y sin barra final, y deja en blanco el ID de cliente y el secreto.
  3. Elige Conectar. LetsFindWhy te pide que inicies sesión si aún no lo has hecho y luego muestra lo que puede hacer la conexión; elige Permitir.

Para terminar una conexión, abre Configuración en LetsFindWhy y elige Desconectar en la tarjeta Agentes conectados. Es la única forma de revocarla: quitar el conector en Claude impide que Claude lo use, pero un conector añadido de nuevo más tarde vuelve a iniciar sesión directamente. Quítalo en ambos sitios para que Claude deje de pedirte que inicies sesión otra vez.

Cómo conectar Claude Code

Claude Code puede iniciar sesión de la misma forma. Ejecuta esto una vez, luego escribe /mcp en Claude Code y elige Authenticate; se abre una ventana del navegador para el inicio de sesión. Es una conexión distinta de la que tiene claude.ai, y aparece por separado en Configuración.

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

Para scripts, uso sin interfaz o cualquier cliente que te permita definir una cabecera de solicitud, pega una clave en su lugar:

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

Claude Code lista entonces una herramienta por cada cosa que puedes hacer en LetsFindWhy, con el nombre de lo que hace: create_project, create_discussion_guide_with_questions, invite_recruited_respondents_to_session, get_session_transcript, etcétera. Pide lo que quieras con palabras normales y elegirá las herramientas.

Cursor, los scripts y otros clientes que te permiten definir una cabecera de solicitud funcionan igual. Los directorios de conectores de claude.ai y Claude Desktop no pueden enviar una cabecera; en su lugar se conectan mediante URL e inicio de sesión, como se describe más arriba.

Qué puede y qué no puede hacer un agente

Un agente trabaja como tú. Prepara y lee la investigación; no dirige entrevistas ni gestiona tu equipo.

Puede:

  • Crear y actualizar organizaciones, proyectos, procesos, guías de discusión y cuestionarios de selección.
  • Gestionar el reclutamiento: abrir y cerrar enlaces de inscripción, añadir encuestados a mano e invitarlos a sesiones.
  • Preparar sesiones con antelación: crearlas, cambiar su configuración, asignar una guía y editar sus preguntas.
  • Leer resultados: grabaciones, transcripciones, respuestas, insights de IA y uso.

No puede:

  • Tocar una entrevista en curso. Iniciar, finalizar, admitir personas, expulsarlas y convocar o retirar al moderador IA quedan en manos de quienes están en la sala.
  • Cambiar quién está en tu organización: no puede cambiar roles, eliminar miembros, transferir la propiedad, abandonar ni eliminar la organización.
  • Eliminar grabaciones. Eliminar una grabación elimina también su transcripción, así que sigue siendo una decisión que tomas en la aplicación.

La línea está donde está porque un agente lee lo que dijeron los encuestados, y un encuestado podría decir algo pensado para manipularlo. Lea lo que lea, no puede dejarte fuera de tu propia organización ni borrar tu investigación.

Eliminar un proyecto, una sesión, un proceso, una guía o un cuestionario de selección está permitido. Los proyectos y las sesiones pueden restaurarse durante 30 días, y tu agente te pedirá confirmación antes de cualquier eliminación.

Cómo llamar directamente a la API REST

Por debajo, cada herramienta es un endpoint REST. Envía tu clave como Authorization: Bearer mtg_... y consulta la referencia completa, con cada endpoint y sus parámetros, en /api/docs una vez que hayas iniciado sesión.

Las claves están limitadas a ráfagas cortas: 60 llamadas en un segundo por la API REST, y unas 30 a través de MCP, donde cada llamada a una herramienta comprueba la clave dos veces. Ningún agente que piense llega a ninguno de los dos límites. Una llamada que los supera recibe una respuesta 429 que indica cuánto esperar.