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.
¿Qué es MCP?
Sección titulada «¿Qué es MCP?»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
Conexión a la interfaz MCP
Sección titulada «Conexión a la interfaz MCP»Punto de conexión
Sección titulada «Punto de conexión»https://portor.<tenant>.askalot.io/mcpSustituya <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.
Autenticación
Sección titulada «Autenticación»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):
- Apunte el cliente a su inquilino (
export ASKALOT_MCP_URL=https://portor.<tenant>.askalot.io/mcp). - Invoque cualquier herramienta MCP. El cliente abre el navegador en el punto de conexión
/authorizede Portor, que redirige al inicio de sesión OIDC de la plataforma. - 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.
- El intercambio en el navegador ocurre una sola vez; después, el token de actualización se canjea de forma transparente.
Su organización activa
Sección titulada «Su organización activa»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.
Organizaciones selladas
Sección titulada «Organizaciones selladas»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.
Su configuración de modelos de IA
Sección titulada «Su configuración de modelos de IA»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.
Usar siempre el modelo más reciente
Sección titulada «Usar siempre el modelo más reciente»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_configurationdevuelveauto_latest(por panel,direct_llmyreasoning: si la casilla está activada) yauto_status(por ranura: cuándo se comprobó por última vez, el resultado y el último modelo cuya llamada de prueba falló). Los resultados incluyenok,no_newer_model,pending_verification,no_credential,catalog_unreadable,session_expiredo el motivo de rechazo de la propia llamada de prueba.- En
update_model_configuration, indicar unmodel_idpara 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 elauto_latestresultante. - 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.
Elegir entre MCP y REST
Sección titulada «Elegir entre MCP y REST»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_respondentstiene 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_endsyderive_silversolo existen en MCP. No hay un equivalente REST que buscar. - Los conjuntos de datos no son exclusivos de MCP.
list_datasets,get_dataset,delete_datasetyexport_datasettienen 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, yget_qml_contentpor encima de 32 KB, devuelven undownload_urlfirmado 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_contenty pase suversion_idcomobase_version_idasave_qml_fileofinalize_upload. Después de un guardado, indique elversion_idque devolvió ese guardado. Ante unoverlap, 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_statuscon un identificador de tarea, oget_datasetpara 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,campaignLos 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.
Una secuencia completa en una sola llamada
Sección titulada «Una secuencia completa en una sola llamada»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_fieldingse detiene antes de enviar las invitaciones. Nunca envía nada; eso sigue siendo una llamada aparte y deliberada asend_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_pipelinecomunica una detención en su envoltorio{success: false, error, detail}; las otras dos devuelven su resultado normal conerrorydetailrellenados y sin clavesuccess. - 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.
Herramientas disponibles
Sección titulada «Herramientas disponibles»La interfaz MCP ofrece herramientas organizadas por funcionalidad.
Sesión y organizaciones
Sección titulada «Sesión y organizaciones»| 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 |
Gestión de proyectos
Sección titulada «Gestión de proyectos»| 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) |
Operaciones con cuestionarios
Sección titulada «Operaciones con cuestionarios»| 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
Búsqueda de documentos
Sección titulada «Búsqueda de documentos»| 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 |
Artículo de investigación
Sección titulada «Artículo de investigación»| 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.
Gestión de campañas
Sección titulada «Gestión de campañas»| 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
Gestión de encuestados
Sección titulada «Gestión de encuestados»| 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
Grupos de encuestados
Sección titulada «Grupos de encuestados»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
Estrategias de muestreo
Sección titulada «Estrategias de muestreo»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
Gestión de usuarios
Sección titulada «Gestión de usuarios»| 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.
Carga de trabajo de los entrevistadores
Sección titulada «Carga de trabajo de los entrevistadores»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 |
Ejecución de encuestas
Sección titulada «Ejecución de encuestas»| 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
Análisis de datos
Sección titulada «Análisis de datos»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
Auditoría y cumplimiento
Sección titulada «Auditoría y cumplimiento»| 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.
Acceso a la documentación
Sección titulada «Acceso a la documentació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 |
Recursos MCP
Sección titulada «Recursos MCP»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).
Ejemplos de flujos de trabajo
Sección titulada «Ejemplos de flujos de trabajo»Crear una campaña de encuestas con IA
Sección titulada «Crear una campaña de encuestas con IA»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.Importar un cuestionario impreso
Sección titulada «Importar un cuestionario impreso»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.
Crear una muestra representativa
Sección titulada «Crear una muestra representativa»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 matchnational 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: 0Conceptos de la plataforma
Sección titulada «Conceptos de la plataforma»Comprender el modelo de entidades ayuda a trabajar con la interfaz MCP:
Jerarquía de entidades
Sección titulada «Jerarquía de entidades»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 y entrevistadores
Sección titulada «Encuestados y entrevistadores»- 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
interviewerque 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.
Encuestados frente a usuarios
Sección titulada «Encuestados frente a usuarios»- 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
interviewerpueden realizar encuestas con los encuestados. - Encuestados y usuarios son entidades distintas. Los entrevistadores son usuarios, no encuestados.
Gestión de errores
Sección titulada «Gestión de errores»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:
- Herramientas de campaña: patrones de operaciones en bloque (added/skipped/reasons), requisitos para recibir invitaciones
- Herramientas de encuesta: transiciones de la máquina de estados, errores de flujo
- Herramientas de conjuntos de datos: validación de etapas, errores de formato
- Herramientas de grupos: tratamiento de duplicados, validación de estrategias
- Herramientas de muestreo: validación del esquema de factores, protección de la estrategia predeterminada
- Herramientas de cuestionario: restricciones del ciclo de vida, comprobación de campañas activas
- Herramientas de encuestados: errores de creación masiva