Ir al contenido
Base de conocimiento

Interfaz MCP

Askalot es compatible con el Model Context Protocol (MCP), un estándar abierto que permite a los asistentes de IA interactuar directamente con la plataforma. Así, los agentes de IA pueden crear encuestas, gestionar campañas, recorrer el flujo de los cuestionarios y analizar los resultados mediante conversaciones en lenguaje natural.

MCP es un protocolo estandarizado que permite a sistemas de IA como Claude utilizar herramientas y fuentes de datos externas. Con la interfaz MCP de Askalot puede:

  • Automatizar los procesos de encuesta: crear proyectos, cuestionarios y campañas conversando con la IA
  • Ejecutar encuestas mediante programación: recorrer el flujo de los cuestionarios y enviar respuestas
  • Gestionar encuestados: importarlos, organizarlos y asignarlos a campañas como destinatarios de las encuestas
  • Consultar el registro de auditoría: seguir los cambios y garantizar el cumplimiento normativo
  • Acceder a la documentación: los agentes de IA pueden leer la documentación de la plataforma para obtener contexto
https://portor.<tenant>.askalot.io/mcp

Sustituya <tenant> por el nombre del inquilino de su organización.

Este es el conector para usted y su equipo. Los encuestados nunca se conectan aquí: una campaña que ofrece el asistente de IA proporciona a cada encuestado un conector aparte, https://portor.<tenant>.askalot.io/respond/mcp, al que se accede con un código de emparejamiento obtenido en su página de la encuesta. Ese conector solo contiene su propia encuesta. Consulte Autoentrevista asistida por IA.

La interfaz MCP se autentica con OAuth 2.1, no con un token de API pegado a mano. En la primera llamada a una herramienta, Portor responde 401 con una indicación de descubrimiento OAuth, y su cliente MCP (por ejemplo, el plugin de Askalot para Claude Code) le guía por un inicio de sesión en el navegador ante el proveedor OIDC de la plataforma. A continuación, el cliente guarda los tokens de acceso y de actualización obtenidos y envía el token de acceso como Authorization: Bearer en cada llamada; usted nunca manipula ese valor.

Configuración del punto de conexión (solo la URL):

Lo único que se configura es la URL del servidor. El plugin de Askalot la lee de la variable de entorno ASKALOT_MCP_URL; una entrada .mcp.json sencilla contiene esa misma URL y nada más, sin ningún campo de token:

{
"mcpServers": {
"askalot": {
"type": "http",
"url": "https://portor.<tenant>.askalot.io/mcp"
}
}
}

Inicio de sesión (primer uso):

  1. Apunte el cliente a su inquilino (export ASKALOT_MCP_URL=https://portor.<tenant>.askalot.io/mcp).
  2. Invoque cualquier herramienta MCP. El cliente abre el navegador en el punto de conexión /authorize de Portor, que redirige al inicio de sesión OIDC de la plataforma.
  3. Inicie sesión. Encima del formulario, la página de inicio de sesión indica qué aplicación lo solicita y a qué dirección se enviará su acceso; continúe solo si fue usted quien inició esta conexión desde esa aplicación. El cliente canjea el código por tokens y repite la llamada original.
  4. El intercambio en el navegador ocurre una sola vez; después, el token de actualización se canjea de forma transparente.

Su sesión MCP se encuentra siempre en una sola organización a la vez —su organización activa— y cada llamada a una herramienta se resuelve en ella. Los proyectos, cuestionarios, campañas, encuestados y conjuntos de datos pertenecen a una organización, por lo que esto es lo más importante que debe saber sobre dónde busca una herramienta.

Dónde empieza. Una sesión nueva comienza en su organización de origen, aquella a la que pertenece su cuenta. Durante el inicio de sesión no se le pide que elija.

Cómo verla. list_organizations devuelve todas las organizaciones en las que la sesión puede actuar, indica cuál es la activa y señala las que están selladas. La lista coincide exactamente con lo que le ofrece el menú Cambiar de organización en el navegador: si pertenece a una sola organización, esa es toda la lista y no hay nada que gestionar.

Cómo cambiarla. switch_organization traslada la sesión a otra organización de esa lista. Todas las llamadas posteriores se resuelven en la nueva, y el cambio se conserva: si reinicia su cliente MCP, continúa donde lo dejó. El inquilino se fija al iniciar sesión y nunca cambia, de modo que el cambio solo le traslada entre organizaciones de un mismo inquilino.

Poder entrar no es lo mismo que poder actuar. La lista contiene las organizaciones de las que es miembro; las membresías las concede y retira un administrador, nunca la propia sesión (la lista de un operador de Askalot abarca todas las organizaciones del inquilino). La membresía permite que la sesión entre; las herramientas que puede usar allí dependen de sus roles en esa organización, y un rol que tenga en otra no se traslada. En una organización de la que es miembro pero en la que no tiene ningún rol, la lista de herramientas se reduce a las de sesión —list_organizations, switch_organization, list_toolsets, get_my_entitlements y su configuración de modelos— hasta que un administrador le asigne un rol allí, de modo que siempre puede volver a salir. Si un administrador le retira de la organización en la que está la sesión, la conexión termina; vuelva a iniciar sesión y la nueva sesión empezará en su organización de origen.

Algunas organizaciones están selladas: una demostración preparada o los datos de un antiguo cliente que se conservan durante su periodo de retención. list_organizations las señala, para que lo sepa antes de actuar.

Lo que se sella es el registro de investigación de esa organización: sus proyectos, cuestionarios, campañas, encuestados, grupos, encuestas, conjuntos de datos y artículos de investigación. La lectura no se ve afectada: listar y consultar todo ello sigue funcionando, igual que las herramientas de documentación y de la biblioteca de metodología. Las herramientas de auditoría mantienen sus reglas habituales (consulte Auditoría y cumplimiento). Crear, actualizar y eliminar se rechaza con org_sealed. Cada herramienta declara si lee o escribe, y es esa declaración la que determina el rechazo: el límite es una propiedad de la herramienta, no una conjetura a partir de su nombre.

Probar un instrumento sigue siendo posible, porque una vista previa no modifica nada del registro. create_survey sin campaña inicia una vista previa en lugar de una encuesta, y get_survey_current_item, submit_survey_response y finish_survey la recorren; así puede revisar un cuestionario de principio a fin en una organización sellada. Si pasa una campaña a create_survey, la llamada se rechaza: ese recorrido sería un caso real, y los casos reales entran en el conjunto de datos.

list_organizations y switch_organization siguen funcionando allí, de modo que una sesión siempre puede ver a qué otras organizaciones puede cambiar para salir de ella.

El sellado también desactiva los tokens de API de esa organización: no se puede generar uno nuevo y los existentes dejan de funcionar. El inicio de sesión OAuth descrito arriba no se ve afectado.

Askalot realiza tres tipos de llamadas de IA en su nombre, y cada una elige su proveedor y su modelo por separado: embedding (fijado al modelo local de la plataforma; la indexación y la búsqueda deben usar el mismo, por lo que no es configurable), LLM directo (una única compleción en bruto: la extracción de palabras clave en una búsqueda de documentos y el paso de extracción al ingerir un documento) y razonamiento, que ejecuta los agentes y tiene un nivel high / medium / low.

get_model_configuration informa de lo que está vigente para su propia cuenta y, para cada ranura, de dónde procede el valor:

Origen Significado
user lo eligió usted
org heredado de su organización
platform el valor predeterminado de Askalot (solo la ranura de embedding)
mixed el proveedor y el modelo proceden de lugares distintos
unconfigured no hay nada definido y no existe un valor predeterminado de la plataforma

La ranura de LLM directo y todos los niveles de razonamiento figuran como unconfigured hasta que usted o su organización elijan un proveedor, y esto resuelve una confusión frecuente: esas ranuras no tienen valor predeterminado de la plataforma a propósito, porque las llamadas se facturan a su propia cuenta del proveedor. Una búsqueda de documentos o una ingesta que se rechaza con “requires an LLM provider — none is configured” («requiere un proveedor de LLM; no hay ninguno configurado»), o un agente que le pide configurar un proveedor, corresponde a este estado, no a una clave defectuosa. Un nivel de razonamiento sin configurar figura como null en effective_config.

update_model_configuration modifica sus propias ranuras. Combina los valores: si indica direct_llm, sus niveles de razonamiento quedan como estaban; si indica reasoning: {"high": …}, medium y low no se tocan. Pase null para un nivel —o clear_direct_llm: true— para devolver una ranura al valor de su organización. Los tres niveles de razonamiento deben quedar en un mismo proveedor, y un nivel sin definir cuenta como discrepancia, así que la primera escritura debe indicar los tres: definir solo high se rechaza, porque medium y low quedarían sin definir. Por el mismo motivo, para borrar el razonamiento cuando su organización no define ninguno hay que pasar null para los tres niveles a la vez.

direct_llm y reasoning aceptan cada uno anthropic_api o bedrock. Consulte en get_model_configuration los valores aceptados y el modelo predeterminado de cada proveedor en lugar de adivinarlos; una escritura rechazada no cambia nada e indica qué estaba mal.

La ranura de LLM directo y los niveles de razonamiento forman cada uno un panel con una casilla Usar siempre el modelo más reciente, activada salvo que usted la haya desactivado. Mientras está activada, Askalot mantiene las ranuras del panel en el Sonnet más reciente (LLM directo) o en Opus / Sonnet / Haiku (high / medium / low), y solo cambia después de que una llamada de prueba con la credencial de esa ranura tenga éxito; el funcionamiento se explica en Funciones de IA y opciones de modelo. A través de las herramientas:

  • get_model_configuration devuelve auto_latest (por panel, direct_llm y reasoning: si la casilla está activada) y auto_status (por ranura: cuándo se comprobó por última vez, el resultado y el último modelo cuya llamada de prueba falló). Los resultados incluyen ok, no_newer_model, pending_verification, no_credential, catalog_unreadable, session_expired o el motivo de rechazo de la propia llamada de prueba.
  • En update_model_configuration, indicar un model_id para cualquier ranura de un panel es una elección manual: la casilla de ese panel se desactiva en la misma escritura, y el otro panel no se toca. Indicar solo un proveedor para un panel cuya casilla está activada (direct_llm={"provider": "bedrock"}, o cada nivel de razonamiento como {"provider": …}) rellena sus ranuras con el modelo más reciente de la familia de cada ranura que ofrezca el proveedor, deja la casilla activada y marca las ranuras para probarlas en la siguiente comprobación. La respuesta incluye el auto_latest resultante.
  • La herramienta nunca vuelve a activar una casilla; eso se hace en la página del perfil.

Ambas herramientas actúan solo sobre su cuenta. La misma configuración está en la sección Modelos de IA de su página de perfil, y un cambio por cualquiera de las dos vías queda registrado en el registro de auditoría.

El servidor MCP es una de las dos vías de acceso a las mismas capacidades, y no puede avisarle de que eligió la equivocada: la vía incorrecta es lenta y consume mucho contexto, pero no produce un error.

  • MCP sirve para una acción semántica, una consulta o cualquier cosa que requiera el criterio del servidor. La mayor parte del trabajo va aquí.
  • REST (https://portor.<tenant>.askalot.io/api/v1) sirve para el trabajo masivo y para todo lo que tenga una carga útil o un resultado grandes. Itere y filtre fuera de su contexto y conserve solo un resumen.

Qué credencial usar depende de quién llama. El token de acceso OAuth que autentica su sesión MCP se acepta en /api/v1 como Authorization: Bearer <token>. Un token de acceso personal (PAT) va en la cabecera X-Api-Token, nunca como Bearer; consulte Autenticación.

  • Un programa que tiene su propio token —un agente del SDK que gestiona su sesión OAuth— puede reutilizarlo en REST. Ya tiene la credencial en la mano, y una sesión es una misma identidad en ambas vías.
  • El código que genere para un entorno aislado (sandbox), o cualquier cosa que sobreviva al turno, usa un PAT. No es una preferencia: un sandbox no dispone de ninguna credencial propia que llegue a esta API. Además, un PAT se puede revocar por separado, cosa que no ocurre con un token de sesión.
  • Un modelo que maneja un cliente de chat nunca ve el token: lo guarda el cliente. Si está escribiendo código, se encuentra en el caso anterior.

Datos que es fácil entender al revés:

  • bulk_create_respondents tiene un límite de 100 por llamada en ambas vías. REST valida la misma entrada, así que 500 encuestados son cinco llamadas en cualquier caso. REST gana en idas y vueltas y en contexto, nunca en tamaño de lote.
  • Los trabajos del proceso code_open_ends y derive_silver solo existen en MCP. No hay un equivalente REST que buscar.
  • Los conjuntos de datos no son exclusivos de MCP. list_datasets, get_dataset, delete_dataset y export_dataset tienen rutas en /api/v1/datasets, y listar o exportar es precisamente el trabajo de resultados grandes para el que existe REST.
  • El contenido grande se devuelve como enlace. export_dataset, y get_qml_content por encima de 32 KB, devuelven un download_url firmado de corta duración; descárguelo por HTTPS normal.
  • Un guardado de QML indica la versión a partir de la cual se escribió. Lea con get_qml_content y pase su version_id como base_version_id a save_qml_file o finalize_upload. Después de un guardado, indique el version_id que devolvió ese guardado. Ante un overlap, vuelva a leer y aplique de nuevo su cambio; nunca reenvíe el mismo contenido. Detalles: Herramientas de cuestionario.
  • Consulte el estado en lugar de iterar. Sin un sandbox de código, no escriba a mano cientos de llamadas secuenciales a herramientas: inicie el trabajo y consulte periódicamente get_task_status con un identificador de tarea, o get_dataset para una etapa de un conjunto de datos.

Limitar las herramientas que ve una conexión

Sección titulada «Limitar las herramientas que ve una conexión»

El catálogo completo supera las 120 herramientas, más de las que cualquier investigación concreta necesita tener delante. Una conexión puede indicar en la URL las áreas que desea:

https://portor.<tenant>.askalot.io/mcp?toolsets=analysis,campaign

Los valores son nombres de conjuntos de herramientas separados por comas. Una conexión que no indica ninguno recibe todo, que es el comportamiento predeterminado y seguirá siéndolo.

Se pueden filtrar así nueve conjuntos de herramientas:

Conjunto Qué contiene
project Los proyectos y su propiedad
questionnaire Los cuestionarios y el ciclo de vida de QML
sampling Encuestados, grupos y estrategias de muestreo
campaign Las campañas y su configuración
fielding Encuestas, invitaciones, entrevistadores y el flujo de respuestas
analysis Paquetes, conjuntos de datos y el proceso Bronce/Plata/Oro
documents Sus documentos de referencia subidos
methodology La biblioteca compartida de metodología de encuestas
audit El registro de auditoría

Otros ocho se admiten en todas las conexiones, indique lo que indique, porque quitarlos dejaría a un agente sin poder corregir su propio rumbo: sus herramientas de sesión y de organización, el historial de conversaciones, los derechos de uso, la documentación, la propia herramienta list_toolsets, el artículo de investigación, las herramientas compuestas que se describen más abajo y get_task_status, de modo que una herramienta compuesta iniciada en una conexión limitada siempre se puede consultar desde ella.

Conviene dejar claras dos cosas que esto no es:

  • No es un límite de permisos. Usted elige su propia URL, así que indicar un conjunto de herramientas no impide el acceso a nada. Lo que puede hacer lo deciden su nivel de suscripción, su rol y la propiedad de los proyectos, y nada de eso cambia. Limita lo que tiene delante, no lo que puede hacer.
  • No es un rol. El parámetro admite estos nombres de conjuntos y nada más; no existe un atajo ?toolsets=analyst.

Llame a list_toolsets en cualquier momento para ver todos los conjuntos, las herramientas de cada uno, lo que indicó su conexión y los nombres que no se reconocieron. Si llama a una herramienta que su conexión dejó fuera, el rechazo indica el conjunto que la contiene y el parámetro de URL que la admitiría, de modo que una suposición equivocada se puede corregir sin leer esta página.

Cambiar el alcance implica volver a conectarse, ya que forma parte de la URL de conexión. Es una función del transporte HTTP; una conexión stdio no tiene URL y nunca está limitada.

Tres secuencias habituales están disponibles cada una como una única herramienta. No son atajos que se salten pasos: cada paso es la misma herramienta que llamaría a mano, que escribe los mismos registros y deja el mismo rastro en el registro de auditoría:

Una llamada Qué ejecuta
prepare_campaign_fielding Estrategia de muestreo → grupo de encuestados → asignación del grupo → publicación de la versión del cuestionario → creación de las encuestas
simulate_campaign_responses Creación de las encuestas → generación de respuestas sintéticas sobre ellas
run_bundle_pipeline Extracción Bronce → Plata (codificación + ponderación) → Oro

Tres cosas que debe saber antes de usarlas:

  • prepare_campaign_fielding se detiene antes de enviar las invitaciones. Nunca envía nada; eso sigue siendo una llamada aparte y deliberada a send_campaign_invitations, que usted hace después de revisar lo que ha construido la cadena. Un correo enviado no se puede recuperar.
  • Si una cadena se detiene a medias, lo ya construido se conserva. No se deshace nada. La respuesta indica el paso en stopped_at_step; un valor no nulo significa que la cadena no terminó, y usted continúa desde ahí con las herramientas individuales. run_bundle_pipeline comunica una detención en su envoltorio {success: false, error, detail}; las otras dos devuelven su resultado normal con error y detail rellenados y sin clave success.
  • Una cadena comprueba toda la secuencia de antemano. Si su suscripción no cubre un paso posterior, se le informa antes de construir nada, en lugar de entregarle un resultado a medio terminar.

simulate_campaign_responses y run_bundle_pipeline devuelven un identificador de tarea que se consulta con get_task_status. run_bundle_pipeline informa del paso que ha alcanzado su ejecución y, al terminar, del conjunto de datos de cada etapa; simulate_campaign_responses devuelve la misma tarea de relleno que devolvería la herramienta básica mass_fill_surveys, por lo que su consulta informa del progreso en lugar de los pasos.

La interfaz MCP ofrece herramientas organizadas por funcionalidad.

Herramienta Descripción
list_organizations Lista las organizaciones a las que esta sesión puede cambiar, indica la activa y señala las selladas
switch_organization Cambia la organización activa de la sesión; todas las llamadas posteriores se resuelven en ella
Herramienta Descripción
list_projects Lista todos sus proyectos
get_project Obtiene los detalles de un proyecto
create_project Crea un proyecto nuevo
add_project_owners Añade usuarios como propietarios del proyecto (deben ser miembros de la organización del proyecto)
remove_project_owners Retira usuarios de la propiedad del proyecto (se aplica la misma regla de membresía)
Herramienta Descripción
list_questionnaires Lista todos los cuestionarios
get_questionnaire Obtiene los detalles de un cuestionario
create_questionnaire Crea un cuestionario nuevo a partir de contenido QML o de una plantilla de la biblioteca (template, copiada en language con los demás idiomas de la biblioteca como traducciones); con contenido, también puede recibir el inventory a partir del cual se generó, que se guarda con la versión 1 (un inventario que no supera la validación hace que se rechace toda la creación)
list_questionnaire_templates Lista la biblioteca de plantillas de cuestionarios en uno de sus idiomas (language; el suyo por defecto, o inglés marcado con language_fallback cuando la biblioteca no ofrece el suyo), por categoría y con una búsqueda por nombre y descripción
rename_questionnaire Cambia el nombre de un cuestionario (la dirección no cambia)
delete_questionnaire Elimina un cuestionario de forma reversible (borrado lógico)
restore_questionnaire Restaura un cuestionario eliminado recientemente mediante borrado lógico
list_qml_files Lista los cuestionarios QML de la organización
inspect_qml_file Resumen rápido de la versión actual de un cuestionario
preview_qml_item Muestra un ítem del cuestionario tal como lo ve el encuestado; un host que renderiza MCP Apps muestra sus controles reales en un panel de solo lectura
get_qml_content Recupera el QML actual de un cuestionario y su version_id, la base que indica un guardado (por encima de 32 KB devuelve un enlace de descarga de corta duración en lugar del contenido)
validate_qml_file Ejecuta la validación SMT de Z3 sobre la versión actual de un cuestionario (alcanzabilidad, coherencia)
qml_quality_report Calcula la tabla de calidad de diseño D2–D8 de la versión actual de un cuestionario
save_qml_file Guarda QML escrito a partir de una versión que usted indica (base_version_id, obtenido con get_qml_content): se combina con un guardado más reciente si afecta a otras líneas y se rechaza como overlap si afecta a las mismas. Nunca se bloquea por borradores con errores (el contenido de más de 32 KB se rechaza; use el mecanismo de subida que se describe a continuación)
request_upload_url / finalize_upload Mecanismo en dos pasos para guardar contenido QML que supera el límite de 32 KB de save_qml_file; finalize_upload también indica base_version_id
request_import_upload_url Obtiene un enlace de un solo uso para subir un cuestionario impreso (PDF o Markdown) a un proyecto con el fin de importarlo; envíe el archivo con PUT a ese enlace
import_questionnaire Importa el archivo subido como un nuevo borrador de cuestionario. Es una operación larga y costosa: se ejecuta con su propio proveedor de IA y cuenta para su límite mensual de importaciones. Las respuestas rellenadas en el original se descartan y el archivo subido se elimina. Devuelve un task_id para get_task_status. Requiere el rol de diseñador o de gestor (o ser operador) y acceso de escritura al proyecto
get_questionnaire_inventory Lee el inventario a partir del cual se construyó un cuestionario: la versión que describe, cada número de pregunta impreso con su identificador de ítem y las comprobaciones que se añadieron en lugar de estar impresas (invented), junto con el informe de importación
get_questionnaire_import_source Lee en Markdown el original que leyó una importación de PDF: lo que se encontró y se eliminó (respuestas, encabezados y pies de página repetidos, números de página impresos) y, a continuación, páginas completas desde from_page hasta aproximadamente max_chars (32 000 por defecto), con next_page para la siguiente llamada. Cada página empieza con una marca que indica su página en el archivo, el número impreso en ella y si se leyó como texto o mediante visión; los números de página del inventario son los del archivo. Un cuestionario que no se importó de un PDF responde import_source_not_found
list_qml_translations Por idioma, si la traducción de una versión está completa, qué textos están sin traducir y si está congelada o editada por una persona
get_qml_translation La traducción de una versión a un idioma, con todos los textos de origen a partir de los cuales redactar y el updated_at que indica un guardado
save_qml_translation Guarda texto traducido para un idioma (parcial, combinado con lo almacenado; indica base_updated_at). Solo texto: se rechazan identificadores o códigos desconocidos y listas posicionales parciales
delete_qml_translation Elimina la traducción de una versión a un idioma (se rechaza una vez congelada)
publish_qml_file Publica un cuestionario en una campaña: lo valida formalmente y fija la versión exacta (el único paso sujeto a comprobación)
move_qml_to_project Traslada un cuestionario a otro proyecto (se conserva el historial de versiones)
unpublish_qml_file Elimina un cuestionario de forma reversible conservando su historial de versiones (bloqueado si hay campañas activas)

Referencia de parámetros: parámetros, esquemas de respuesta, ciclo de vida de QML, estructura de la salida de Z3

Herramienta Descripción
list_indexed_documents Lista todos los documentos indexados para la búsqueda semántica con IA, cada uno con su clave de documento (por ejemplo projects/<project-id>/report.pdf)
get_document_summary Obtiene el resumen en Markdown almacenado de un documento, identificado por su document_key
get_document_chunk Recupera un fragmento concreto de un documento indexado (document_key, chunk_index)
search_document_chunks_by_keyword Busca por palabra clave en los fragmentos de documentos indexados, opcionalmente limitada a document_keys
Herramienta Descripción
read_paper Lee el artículo de investigación de un proyecto: los capítulos ensamblados, más el token de edición actual de cada unidad
edit_paper_unit Sustituye un pasaje exacto dentro de una unidad del artículo y deja todo lo demás intacto, byte a byte
read_paper_translation Lee las traducciones del artículo a un idioma: sin unidad, el estado de cada unidad (actual, desfasada, ausente) y los tokens de edición; con una unidad, su texto de origen y su traducción en paralelo
edit_paper_translation Escribe la traducción de una unidad a un idioma, anclada como en edit_paper_unit; una traducción hecha a partir de un texto de origen anterior se sustituye por completo

El artículo se redacta en su idioma de origen (inglés). Una traducción es un texto aparte junto a cada unidad, que se muestra a quienes leen el artículo en ese idioma, y nunca se escribe en la unidad de origen. La skill translate-paper del plugin de Askalot guía a un agente a lo largo de una pasada de traducción.

Herramienta Descripción
list_campaigns Lista las campañas (opcionalmente por proyecto)
get_campaign Obtiene los detalles de una campaña
create_campaign Crea una campaña nueva
update_campaign Actualiza campos de la campaña (nombre, fechas, estado, admisión de voluntarios, la oferta del asistente de IA y sus textos)
delete_campaign Elimina una campaña
add_interviewers_to_campaign Añade entrevistadores (usuarios con el rol de entrevistador)
remove_interviewers_from_campaign Retira entrevistadores de una campaña
update_campaign_questionnaire Cambia el cuestionario asignado a una campaña
assign_pool_to_campaign Asigna un grupo de encuestados a una campaña
get_campaign_pool Obtiene el grupo de encuestados asignado a una campaña
send_campaign_invitations Envía a los encuestados los correos de invitación a la encuesta

Los encuestados no se añaden directamente a una campaña: asigne un grupo de encuestados con assign_pool_to_campaign y, a continuación, bulk_create_surveys crea una encuesta por cada encuestado del grupo.

Referencia de parámetros: parámetros, esquemas de respuesta, patrones de operaciones en bloque, requisitos para recibir invitaciones

Herramienta Descripción
list_respondents Lista todos los encuestados (destinatarios de las encuestas)
get_respondent Obtiene los detalles de un encuestado
create_respondent Crea un encuestado nuevo
update_respondent Actualiza la información de un encuestado
delete_respondent Elimina un encuestado
bulk_create_respondents Crea varios encuestados a la vez
bulk_delete_respondents Elimina encuestados según un filtro (flujo en dos pasos con dry_run)
generate_survey_access_token Genera un token de enlace mágico para la encuesta de un encuestado
send_survey_invitation Envía por correo a un encuestado una invitación a la encuesta con enlace mágico

Referencia de parámetros: parámetros, esquemas de respuesta, creación masiva, datos demográficos

Los grupos de encuestados permiten reunir a los encuestados en conjuntos reutilizables para las campañas.

Herramienta Descripción
list_respondent_pools Lista todos los grupos de encuestados
get_respondent_pool Obtiene los detalles de un grupo, incluida la lista de encuestados
create_respondent_pool Crea un grupo de encuestados nuevo
add_respondents_to_pool Añade encuestados a un grupo existente
remove_respondents_from_pool Retira encuestados de un grupo
generate_pool_from_strategy Selecciona un grupo a partir de una estrategia de muestreo con el tamaño solicitado; el grupo guarda su ajustes de selección
preview_pool_generation Previsualiza una extracción sin crear el grupo
plan_sample_size Solo lectura: dimensiona una extracción a partir de los objetivos de un proyecto (margen de error o potencia para dos grupos, bilateral, aproximación normal), la elegibilidad, la respuesta y el efecto de diseño; devuelve las encuestas completas necesarias, el factor de sobremuestreo y el número de personas que invitar, con la revisión de los objetivos guardados. También POST /api/v1/projects/{project_id}/sample-size-plan
save_sizing_targets Guarda el objetivo de cada meta en el artículo del proyecto, indicando la revisión que leyó; una revisión desfasada es un conflicto (REST 409). También PUT /api/v1/projects/{project_id}/sizing-targets
refresh_pool_from_strategy Vuelve a seleccionar un grupo existente con la ajustes de selección que tiene guardada
delete_respondent_pool Elimina un grupo de encuestados

Referencia de parámetros: parámetros, esquemas de respuesta, tratamiento de duplicados, generación a partir de estrategias

Las estrategias de muestreo definen distribuciones demográficas objetivo para crear muestras representativas de encuestados. Una estrategia no contiene ninguna configuración de tamaño ni de selección —son datos de entrada de cada extracción de grupo—, de modo que una misma estrategia puede alimentar grupos de cualquier tamaño.

Herramienta Descripción
list_sampling_strategies Lista todas las estrategias de muestreo
get_sampling_strategy Obtiene los detalles de una estrategia, incluidos sus factores
create_sampling_strategy Crea una estrategia con factores de encuestado personalizados
create_default_strategy Crea una estrategia con los factores estándar de género y edad
update_sampling_strategy Actualiza una estrategia existente
delete_sampling_strategy Elimina una estrategia de muestreo

Ejemplo: crear una estrategia de muestreo personalizada

AI Assistant: I'll create a sampling strategy targeting your demographics.
→ create_sampling_strategy(
name="Urban Millennials",
project_id="...",
factors=[
{"name": "Gender", "attribute_path": "gender",
"target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02}},
{"name": "Age Group", "attribute_path": "age",
"target_distribution": {"25-34": 0.60, "35-44": 0.40}}
]
)
Strategy created! Now generating a representative pool...
→ generate_pool_from_strategy(strategy_id, pool_name="Urban Millennials Pool",
requested_size=200)

Referencia de parámetros: parámetros, esquemas de respuesta, esquema de factores, validación de distribuciones

Herramienta Descripción
list_users Lista los usuarios de su organización activa (incluidos los entrevistadores); llame a switch_organization para ver los usuarios de otra organización
get_user Obtiene los detalles de un usuario

Nota: los entrevistadores son usuarios con el rol interviewer. Se gestionan como usuarios, no como encuestados.

En las campañas con entrevistadores (usuarios con el rol de entrevistador), gestione el reparto de la carga de trabajo:

Herramienta Descripción
assign_respondents_to_interviewer Asigna encuestados a un entrevistador concreto (usuario)
unassign_respondents_from_interviewer Retira asignaciones de entrevistadores
get_interviewer_workload Muestra los encuestados asignados y el estado de finalización
get_unassigned_respondents Busca los encuestados que aún no están asignados
Herramienta Descripción
list_surveys Lista las encuestas (filtradas por campaña o por encuestado)
create_survey Inicia una nueva sesión de encuesta
update_survey Actualiza el estado y el estado del flujo de una encuesta (las entidades vinculadas no se pueden modificar)
bulk_create_surveys Crea encuestas para todos los encuestados de una campaña
bulk_delete_surveys Elimina encuestas según un filtro (flujo en dos pasos con dry_run)
get_survey_current_item Obtiene la pregunta actual con sus opciones incluidas
submit_survey_response Envía una respuesta y avanza (incluye el paso siguiente)
finish_survey Completa explícitamente una encuesta
mass_fill_surveys Pone en cola una tarea asíncrona en segundo plano que rellena encuestas con respuestas de prueba sintéticas (devuelve {task_id, status})
get_task_status Consulta una tarea asíncrona por su task_id: una ejecución de mass_fill_surveys, una cadena simulate_campaign_responses o run_bundle_pipeline, o una ejecución de import_questionnaire (los trabajos de codificación de conjuntos de datos se consultan con get_dataset)

Referencia de parámetros: parámetros, esquemas de respuesta, máquina de estados, modos de distribución, perfiles de persona

Un paquete vincula un proyecto, un cuestionario y un subconjunto de campañas a una única cadena lineal de conjuntos de datos Bronce → Plata → Oro. Las herramientas de paquetes gestionan ese vínculo y ofrecen el resumen de calidad del paquete; las herramientas de conjuntos de datos ejecutan cada etapa del paquete: extracción, codificación + ponderación, refinamiento y exportación.

Herramienta Descripción
create_bundle Crea un paquete del proceso
list_bundles Lista los paquetes, opcionalmente filtrados por un proyecto
get_bundle Detalle del paquete, incluidas las recetas de sus etapas (objetivos de calibración de Plata, operaciones de Oro)
clone_bundle Copia en profundidad los conjuntos de datos listos y las recetas de un paquete en una variante independiente
delete_bundle Elimina un paquete y su cadena de conjuntos de datos
get_bundle_quality El resumen de representatividad del paquete (selección, trabajo de campo, ponderación, desviación durante el trabajo de campo, respuesta)
compare_bundle_quality Mejora de Plata frente a Bronce respecto a la estrategia vigente del paquete
get_bundle_coding Estado de la codificación de respuestas abiertas: los candidatos que ofrece el conjunto de datos Bronce, el tipo de respuesta que el analista asignó a cada uno (descriptiva, nominal o identificador; si falta, sin clasificar), la selección de preguntas y, por pregunta, las dimensiones propuestas, sus categorías y cuáles están seleccionadas
set_coding_selection Define qué unidades de texto abierto codifica el paquete (rol de gestor, se requiere un usuario identificado); rechaza una unidad sin clasificar o de tipo identificador, y ninguna herramienta clasifica unidades
assign_bundle_strategy Asigna (o retira) la estrategia de muestreo vigente del paquete
set_calibration_targets Edita los objetivos de calibración del paquete —la especificación de ponderación de Plata—, cada uno raked (se pondera con él) o benchmark (solo se evalúa); cada guardado comprueba los códigos de respuesta con el cuestionario del paquete
preview_calibration_targets_copy Previsualiza la copia de los objetivos de calibración de otro paquete en este: cuáles encajan (con su papel) y cuáles no, con el motivo; no escribe nada
list_datasets Lista los conjuntos de datos de la cadena de un paquete
get_dataset Obtiene los detalles, las métricas y el estado de un conjunto de datos: el punto de consulta acotado al que remiten los pasos del proceso
get_dataset_schema Obtiene el esquema de columnas de un conjunto de datos, o solo los nombres de las columnas y los tipos de control, opcionalmente limitado a las columnas indicadas
create_bronze_dataset Extrae el conjunto de datos Bronce de un paquete
code_open_ends (alias derive_silver) Codifica el texto de las respuestas abiertas y después pondera con los objetivos de calibración, generando el conjunto de datos Plata del paquete
create_gold_dataset Refina el conjunto de datos Plata de un paquete hasta obtener su conjunto de datos Oro, mediante el catálogo de operaciones de Oro
export_dataset Exporta un conjunto de datos listo (CSV, XLSX, SPSS, Parquet, R, JSON)
delete_dataset Elimina un conjunto de datos

Referencia de herramientas de paquetes: parámetros del ciclo de vida y de la calidad de los paquetes, esquemas de respuesta

Referencia de herramientas de conjuntos de datos: parámetros de las etapas, esquemas de respuesta, formatos de exportación

Herramienta Descripción
query_audit_events Busca en el registro de auditoría con filtros
get_entity_history Muestra el historial completo de cualquier entidad
get_audit_stats Recuento de eventos por tipo de entidad

Las tres solo leen su inquilino y su organización activa. Para leer el registro de otra organización, cambie antes a ella. Los eventos registrados sin organización, como las acciones del sistema y de los servicios, no se devuelven.

Dentro de la organización, lo que ve depende de su rol:

Quién Qué devuelven las herramientas de auditoría
Administrador (org_admin de la organización, u operador de Askalot) Todo el registro de la organización, incluido get_audit_stats
manager Sus propias acciones, más el historial completo de los proyectos, cuestionarios, campañas y encuestas de los proyectos de los que es propietario
Cualquier otra persona Solo sus propias acciones

Se rechaza solicitar las acciones de otro usuario o el historial de una entidad fuera de su alcance. get_audit_stats está reservado a los administradores, y una conexión que no actúa en nombre de ningún usuario no puede leer nada del registro de auditoría. En una organización en la que todos los miembros leen todos los proyectos, como la organización pública Askalot Demo, el registro de auditoría está reservado a los administradores: poder leer la investigación no implica poder leer quién hizo qué, porque los eventos de auditoría contienen datos como las direcciones IP.

El visor de auditoría del navegador aplica los mismos roles, pero allí un operador de Askalot y un usuario normal llegan más lejos:

Quién Qué muestra el visor de auditoría del navegador
Operador de Askalot (tenant_admin) Todos los eventos del inquilino, en todas las organizaciones
Administrador de la organización (org_admin) Todos los eventos de la organización activa
manager Dentro de la organización activa: sus propias acciones, más el historial de los proyectos, cuestionarios, campañas y encuestas de los proyectos de los que es propietario
Cualquier otra persona Solo sus propias acciones, incluidos sus inicios de sesión

Un inicio de sesión se registra en la organización en la que empieza la sesión, y un cierre de sesión o un cambio de contraseña en la organización en la que está trabajando la sesión, de modo que forman parte del registro de esa organización como cualquier otra acción.

Herramienta Descripción
list_documentation Lista la documentación disponible
get_documentation Carga un documento concreto
search_documentation Busca en la documentación por palabra clave

Los recursos ofrecen acceso de solo lectura a los datos de la plataforma:

URI del recurso Descripción
repository://overview Estadísticas y recuentos de la plataforma
repository://schema Relaciones y estructura de las entidades
qml://files Los cuestionarios QML de la organización
docs://primer Visión general de la plataforma
docs://qml-syntax Referencia del lenguaje QML
docs://getting-started Guía de inicio rápido

Otros recursos de documentación reflejan la base de conocimiento (docs://guide, docs://glossary, docs://campaign-management, docs://survey-execution, docs://creating-surveys, docs://data-analysis, docs://quality-metrics).

AI Assistant: I'll help you set up a customer satisfaction survey.
1. First, let me create a project...
→ create_project("Customer Research 2026", "Annual satisfaction study")
2. Now I'll register your questionnaire...
→ create_questionnaire("CSAT Survey", qml_content, project_id)
3. Creating the campaign...
→ create_campaign("Q1 CSAT", project_id, questionnaire_id, admits_volunteers=false, offers_ai_channel=false)
4. Adding your respondent list...
→ bulk_create_respondents(100, generate_demographics=true)
→ create_respondent_pool("CSAT Sample", respondent_ids=[...])
→ assign_pool_to_campaign(campaign_id, pool_id)
→ bulk_create_surveys(campaign_id)
Your campaign is ready! 100 respondents have surveys waiting.
AI Assistant: I'll import your paper questionnaire into the project.
1. Getting an upload link for the PDF...
→ request_import_upload_url(project_id, "application/pdf")
PUT the file to upload_url with Content-Type: application/pdf
2. Starting the import (this takes a few minutes)...
→ import_questionnaire(project_id, upload_id, "visitor-survey.pdf")
→ get_task_status(task_id) # until completed or failed
3. Reading what it built...
→ get_questionnaire_inventory(result.questionnaire_id)
Each printed question number maps to its item id; the checks marked
invented were added and are worth reviewing before you publish.
4. Checking a question against what the import read (PDF only)...
→ get_questionnaire_import_source(result.questionnaire_id, from_page=12)

Una importación rechazada no inicia nada e indica qué lo resuelve: unsupported_type (por ahora solo se leen PDF y Markdown), too_large, invalid_request, no_ai_slot (conecte una clave de la API de Anthropic o Amazon Bedrock, y un modelo de LLM directo, en Configuración del perfil) o fair_use_exceeded (el límite mensual de importaciones). Una importación rechazada requiere una nueva subida, porque el archivo se elimina en cualquier caso.

AI Assistant: I'll create a demographically balanced sample for your study.
1. Creating a sampling strategy with your target demographics...
→ create_sampling_strategy(
name="National Representative",
project_id,
factors=[
{"name": "Gender", "attribute_path": "gender",
"target_distribution": {"male": 0.49, "female": 0.51}},
{"name": "Age", "attribute_path": "age",
"target_distribution": {"18-34": 0.30, "35-54": 0.40, "55+": 0.30}}
]
)
2. Generating a pool that matches your targets...
→ generate_pool_from_strategy(strategy_id, pool_name="Q1 Sample Pool",
requested_size=500)
3. Assigning the pool to your campaign...
→ assign_pool_to_campaign(campaign_id, pool_id)
Done! Your campaign now has 500 respondents balanced to match
national demographics.

Ejecutar una encuesta mediante programación

Sección titulada «Ejecutar una encuesta mediante programación»
AI Assistant: I'll walk through the survey and show you each question.
→ create_survey(questionnaire_id, respondent_id)
→ get_survey_current_item(survey_id)
Question 1: "What is your age?"
Type: Integer input (18-100)
User: 35
→ submit_survey_response(survey_id, "q_age", 35)
→ get_survey_current_item(survey_id)
Question 2: "How satisfied are you with our service?"
Type: Scale (1-5)
...

Gestionar la carga de trabajo de los entrevistadores

Sección titulada «Gestionar la carga de trabajo de los entrevistadores»
AI Assistant: Let me distribute the 50 respondents among your 5 interviewers (Users with interviewer role).
→ get_unassigned_respondents(campaign_id)
Found 50 unassigned respondents
→ assign_respondents_to_interviewer(campaign_id, interviewer_user_1, respondents[0:10])
→ assign_respondents_to_interviewer(campaign_id, interviewer_user_2, respondents[10:20])
...
→ get_interviewer_workload(campaign_id, interviewer_user_1)
Assigned: 10 respondents
Completed: 0
In Progress: 0

Comprender el modelo de entidades ayuda a trabajar con la interfaz MCP:

Project
├── Questionnaire (owns a QML version chain)
└── Campaign
├── Respondents (survey targets)
├── Interviewers (Users with interviewer role, optional)
└── Surveys (individual sessions)

Todo cuestionario pertenece a un proyecto, y todo usuario tiene un proyecto predeterminado (is_default: true). Cuando una solicitud no indica ningún proyecto, busque el predeterminado con list_projects y use su identificador.

  • Encuestados: destinatarios de las encuestas, con datos demográficos. Las encuestas que completan determinan el avance de la campaña. Acceden a las encuestas mediante enlaces mágicos (sin necesidad de autenticarse en la plataforma).
  • Entrevistadores (opcionales): usuarios con el rol interviewer que realizan las encuestas con los encuestados. Tienen acceso a la plataforma y ayudan a los encuestados a completar las encuestas, pero no las rellenan ellos mismos.

Se puede asignar entrevistadores para ayudar a los encuestados en persona o por teléfono. Cuando hay entrevistadores asignados, las encuestas registran qué entrevistador realizó la encuesta de cada encuestado.

  • Los encuestados son los destinatarios de las encuestas, con datos demográficos (edad, género, ubicación). No tienen cuenta en la plataforma.
  • Los usuarios son cuentas de la plataforma para la autenticación y la gestión. Los usuarios con el rol interviewer pueden realizar encuestas con los encuestados.
  • Encuestados y usuarios son entidades distintas. Los entrevistadores son usuarios, no encuestados.

Las herramientas MCP devuelven mensajes de error estructurados. Dos de ellos se aplican a todas las categorías:

  • not_found: la entidad no está en la organización activa de la sesión. El mensaje indica la organización en la que se buscó; consulte Su organización activa.
  • org_sealed: la organización activa está sellada. Las lecturas funcionan; este rechazo solo procede de una herramienta que habría modificado su registro de investigación.

Los patrones de error detallados se documentan por categoría: