MCP
Referencia · Tools · forms

Tools de forms

Las 19 tools del dominio forms montadas en https://mcp.dynamotech.co/mcp. Actúan siempre como vos — con tu identidad de Entra ya resuelta (Gateway.asUser sobre pg-dynamo-<env>), nunca con una clave de servicio — y el permiso real de cada una lo decide la RLS de la base y el acceso por proyecto de Dynamo Auth, no el gateway.

gateway remoto 7 lectura 12 escritura

Mirá el ambiente antes de escribir. Las 12 tools de escritura de esta lista modifican datos reales si tu sesión apunta a PROD. Antes de crear, modificar, clonar, reencolar o enviar una respuesta, pedile a Claude dynamo_session_status (documentada en Tools de auth — vive en el dominio del gateway, no en forms) y confirmá que el ambiente que marca es el que esperás. No hay un "modo QA" separado: el mismo conjunto de tools opera contra el ambiente de la sesión con la que te logueaste.

Qué decide el permiso de cada tool

Dos capas, y solo una de las dos es real:

Flag de runtime — entitlement_enforcement. Si este kill-switch está apagado en el ambiente, el chequeo de "¿la app forms está habilitada para vos en este proyecto?" es un no-op y el único gate que queda es RLS puro (rol project-admin/global-admin o menú delegado, sin la capa de entitlement encima). Se reporta en dynamo_session_status con ⚠️ para que no asumas más validación de la que realmente corre.

forms_session_status no está acá. En el gateway la reemplaza dynamo_session_status — una sola tool que responde "quién soy / qué ambiente es / qué permisos tengo" para los cuatro dominios a la vez. Documentada en Tools de auth.

Lectura (10)

Tool Qué hace Inputs Permiso Ejemplo de prompt
forms_list_forms Los formularios de un proyecto (con sus roles), vía la Edge Function admin-forms. Es el único camino que respeta el acceso delegado por menú — leer la tabla directo con RLS mostraría menos. Paginado: devuelve total, count, has_more y next_offset; sin schema salvo que lo pidas con include_schema. project_id (uuid), limit (1..200, default 50), offset, include_schema (default false) Scope read. Gate real: la EF exige ser project-admin o tener delegado uno de sus 5 menús, y entitlement de forms en ese proyecto. "Mostrame todos los formularios del proyecto Mina Norte."
forms_get_form Un formulario por id, incluida toda su ventana de disponibilidad (fechas, horario, días, timezone) — la causa #1 de "no me deja responder" que no es un problema de permisos. form_id (uuid), include_schema (bool, default true) Scope read. Gate real: RLS de forms + entitlement. "Dame los datos del formulario de inspección diaria, sin el schema completo."
forms_list_form_responses Respuestas de un formulario, más recientes primero, con el response_data completo. Tope duro 500 — puede traer PII del cliente, no pidas más de lo que necesitás. form_id (uuid), limit (1-500, default 50), offset, since (fecha/hora ISO 8601), only_active (bool, default true) Scope read. Gate real: RLS de form_responses + entitlement. "Traeme las últimas 20 respuestas del formulario de inspección de esta semana."
forms_list_tasks Tareas, más recientes primero, filtrables por proyecto, formulario, estado y asignado. assignee_id solo matchea asignación directa a un usuario, no por email externo ni por rol. project_id, form_id, status (Pendiente/En Progreso/Completado/Rechazado), assignee_id — todos opcionales, más limit (1-200, default 50) Scope read. Gate real: RLS de tasks + entitlement. "¿Qué tareas tiene pendientes Juan en el proyecto Mina Norte?"
forms_list_notifications La tool de "¿por qué no llegó el correo?": status, intentos, próxima corrida programada. Con include_logs trae además la respuesta real del proveedor (entregado, rebotado, rate-limited). project_id, status (pending/processing/sent/failed/retrying) — opcionales, limit (1-200, default 50), include_logs (bool, default false) Scope read. Gate real: RLS de notifications. "¿Por qué no le llegó la notificación a este usuario? Mirá los logs del proveedor."
forms_webhook_timeout_report Mide los timeouts de webhooks y su desenlace leyendo notification_logs (la tabla notifications pierde la huella cuando el reintento sale bien). Devuelve el total de webhooks de la ventana, cuántos tuvieron timeout y su desenlace: recuperado con duplicado, recuperado como nuevo, en cola, agotado. Una tasa en null significa "no se pudo medir", nunca cero. project_id, since, until — opcionales; days (1-90, default 30) si no hay since Scope read. Gate real: RLS de notifications y notification_logs. "¿Qué porcentaje de los webhooks de este proyecto hizo timeout en los últimos 30 días?"
forms_list_deactivated_responses Lista los registros dados de baja que un form de alta (form_mode=activation) puede reactivar. form_id (el form de alta) Scope read. Ver la descripción de la tool en tools/list.
forms_submit_deactivation Ejecuta un form de baja: da de baja los registros activos del form destino cuya clave lógica coincide, y deja fila de auditoría. form_id, response_data Scope write. Ver la descripción de la tool en tools/list.
forms_submit_activation Ejecuta un form de alta: reactiva por clave lógica registros dados de baja del form destino. form_id, pk_values Scope write. Ver la descripción de la tool en tools/list.
forms_set_form_flags Enciende o apaga el modo offline y el modo prueba de un formulario. form_id Scope write. Ver la descripción de la tool en tools/list.
forms_update_shared_resource Edita nombre, columnas y filtro condicional de un recurso compartido existente. shared_resource_id Scope write. Ver la descripción de la tool en tools/list.
forms_list_my_inbox Lista la bandeja (campanita) de quien llama en un proyecto: tareas y notificaciones, sin marcar nada como leído. project_id Scope read. Ver la descripción de la tool en tools/list.
forms_export_data_dictionary Devuelve el diccionario de campos de un formulario (estructura, nunca datos). form_id Scope read. Ver la descripción de la tool en tools/list.
forms_restore_schema_version Restaura una versión anterior del schema de un formulario creando una versión nueva. form_id Scope write. Ver la descripción de la tool en tools/list.
forms_list_shared_resources El catálogo de datos maestros de un proyecto — nombre, form de origen, mapeo de columnas. Nunca el contenido de las tablas dinámicas que respaldan esos datos. project_id (uuid) Scope read. Gate real: RLS del schema shared_resources. "¿Qué recursos compartidos (datos maestros) tiene configurados el proyecto Mina Norte?"
forms_list_schema_versions Los snapshots inmutables del schema de un formulario (tabla form_schema_versions, RLS de solo lectura — la única vía de escritura es un trigger que dispara en cada cambio de schema). No restaura nada; para eso hace falta un forms_update_form explícito con el snapshot leído acá. form_id (uuid), version_number (opcional), include_snapshot (bool, default true) Scope read. Gate real: RLS de form_schema_versions. "¿Qué versiones del schema tiene este formulario, y cuándo cambió cada una?"
forms_check_shared_resource_values Confirma cuáles de hasta 100 valores candidatos existen en UNA columna de un recurso compartido — invierte la dirección de forms_list_shared_resources: vos aportás los valores, el server solo confirma. Nunca devuelve contenido del maestro. Cuando un valor no existe, sugiere near_match (única coincidencia normalizada — sin tildes/mayúsculas/espacios — si la hay). resource_id (uuid), column (nombre real de columna, no la key del mapeo), values (1 a 100 strings) Scope read. Gate real: RLS de la tabla dinámica del recurso (hereda la del rol del caller). "¿Estos 24 nombres de instrumento del sistema legado existen en el maestro de Instrumentos? Los que no, decime a cuál se parecen."
forms_list_custom_notifications La CONFIGURACIÓN de notificaciones de un formulario (tabla custom_form_notifications) — no confundir con forms_list_notifications, que lee la COLA de envíos ya disparados. Esta es la tool de "¿a quién le llega esto?": para cada notificación devuelve destinatarios (targets), si está activa, condiciones de disparo y la plantilla PDF adjunta. form_id (uuid) Scope read. Gate real: RLS de custom_form_notifications. "¿A quién le llega la notificación de este formulario, y con qué PDF adjunto?"
forms_list_task_templates Las Plantillas de Tarea de un proyecto (tabla task_templates) — la automatización que crea una tarea en un formulario destino cuando llega una respuesta a un formulario origen, con herencia de campos y filtros. Hasta ahora esta configuración era 100% UI. project_id (uuid), source_form_id, target_form_id, folder_id, is_active (bool) — opcionales, más limit (1-200, default 50) Scope read. Gate real: admin del proyecto, o delegado del menú "task-templates". "¿Qué plantillas de tarea tiene configuradas el proyecto Mina Norte?"

Escritura (18)

Con scope read las 5 fallan antes de tocar la base. Con write el pedido llega a pg-dynamo-<env>, y de ahí para adelante el gate real es siempre RLS/entitlement contra tu propio acceso.

Tool Qué hace Inputs Permiso Ejemplo de prompt
forms_create_form Crea un formulario, vía la Edge Function admin-forms. Nace en draft — para publicarlo, encadená forms_update_form con status: "active". project_id, title, schema (objeto de grupos/componentes), description, is_public (default false), folder_id — los tres últimos opcionales Scope write. Gate real: la EF exige ser project-admin o tener delegado forms-management, y entitlement de forms en el proyecto. "Creá un formulario nuevo llamado 'Inspección semanal' en el proyecto Mina Norte, como borrador."
forms_update_form Modifica un formulario vía la EF, con una whitelist estricta de campos. schema reemplaza la definición completa, no hace merge — leé el schema actual con forms_get_form antes de pisarlo si el form ya tiene respuestas. form_id, project_id, patch (solo: title, description, schema, is_public, status draft/active/closed, folder_id, is_favorite — cualquier otro campo se rechaza, no se ignora) Scope write. Gate real: la EF valida sobre el project_id real del form, no el que mandás vos. "Publicá el formulario de inspección semanal (pasalo a activo)."
forms_copy_form Clona un formulario con todas sus dependencias (plantillas de PDF, notificaciones configuradas) dentro del mismo proyecto. La copia nace con el título del original. form_id, project_id Scope write. Gate real: la EF valida entitlement sobre el proyecto del form origen. "Cloná el formulario de inspección semanal dentro del mismo proyecto."
forms_set_form_analytics Prende o apaga Analytics para un formulario (forms.has_analytics). UPDATE directo a la tabla, no pasa por Edge Function. Reversible y sin cascadas — no borra dashboards ni datos ya calculados. form_id, enabled (bool) Scope write. Gate real: RLS — project-admin o menú forms-management delegado, con forms habilitado en el proyecto. "Activá Analytics para el formulario de inspección semanal."
forms_retry_notification Reencola una notificación fallida: la deja pending con scheduled_at ahora. No se envía en el acto — el worker la toma en su próxima corrida. Por default no resetea el contador de intentos. notification_id, reset_attempts (bool, default false) Scope write. Gate real: RLS — project-admin o menú notifications-management delegado (ser el destinatario no alcanza). "Reintentá la notificación fallida de este usuario y resetéale los intentos."
forms_submit_public_response Envía una respuesta a un formulario público vía el RPC submit_public_form_response (SECURITY DEFINER). Queda como anónima (is_anonymous=true, user_id=NULL), igual que un submit público real. Valida server-side status, ventana de disponibilidad y que el form sea público — rechaza uno privado. form_id, response_data (objeto) Scope write. Gate real: el propio RPC. "Envía esta respuesta al formulario público de registro de visitantes."
forms_submit_private_response Envía una respuesta a un formulario privado (sin tarea) vía submit_private_form_response (SECURITY DEFINER) — existe porque el insert directo a form_responses no alcanza a validar rol/status/ ventana del lado servidor. Rechaza con NO_PERMISSION si no tenés el rol requerido en ese formulario, y redirige a forms_submit_public_response si el form es público. Con skip_notifications (cargas M2M) no encola notificaciones, no crea tareas ni escribe el ledger de consentimiento, y lo confirma en el retorno (tasks_suppressed, etc.). form_id, project_id, response_data (objeto), skip_notifications Scope write. Gate real: RLS + rol requerido del formulario (form_roles). "Completá el checklist de inspección de hoy con estos datos."
forms_submit_task_response Completa una tarea enviando la respuesta de su formulario, vía submit_task_form_authenticated (SECURITY DEFINER) — marca la tarea como Completado en la misma transacción. No intercambiable con las otras dos: un task_id siempre va por acá. task_id, response_data (objeto) Scope write. Gate real: el propio RPC — la tarea tiene que estar asignada a vos. "Marcá completa mi tarea de hoy con esta respuesta."
forms_submit_attachment Adjunta evidencia (imagen o archivo) a una form_response_id ya enviada — sube el archivo de verdad a Azure Blob (bucket formattachments) y escribe la fila en form_attachments, en un solo paso desde el MCP. Límite 50MB. Gate: dueño de la respuesta, o assignee de una tarea vinculada, o admin del proyecto. form_response_id, original_field_id, content_base64, file_name, mime_type Scope write. Gate real: el mismo predicado de ownership que submit_form_attachment. "Adjuntá esta foto de la evidencia a la respuesta que acabo de enviar."
forms_deactivate_responses Da de baja lógica una o varias respuestas ya enviadas de un formulario, vía forms_admin_deactivate_responses. Las tareas vinculadas en estado Pendiente/En Progreso pasan a Rechazado en la misma transacción. No hay operación inversa por MCP. project_id, response_ids (array), reason (obligatorio) Scope write. Gate real: admin del proyecto, o delegado de "project-dashboard"/"forms-management". "Dá de baja estas 3 respuestas duplicadas del formulario de inspección — motivo: carga duplicada."
forms_create_shared_resource Crea un "Recurso Compartido" (datos maestros) a partir de un formulario — hasta ahora solo posible desde la UI del form builder. Valida que el formulario origen pertenezca al mismo proyecto que el recurso: no se puede crear un recurso en un proyecto que en realidad refleje datos de otro. project_id, source_form_id, name, selected_columns (array), conditional_filter (opcional) Scope write. Gate real: admin del proyecto, o delegado de "forms-management". "Creá un recurso compartido con los estudiantes de este proyecto, usando el formulario de matrícula."
forms_set_form_mode Configura el "Modo del formulario": normal, o de baja/alta de un registro existente en OTRO formulario (necesita el formulario y campo destino). form_id, form_mode, form_mode_config (opcional) Scope write. Gate real: admin del proyecto, o delegado de "forms-management". "Poné este formulario en modo de desactivación, apuntando al formulario de estudiantes."
forms_set_form_pk Setea el "Campo clave (PK)" del formulario y el prefill "editar sin duplicar". Es el campo que apuntan los formularios de baja/reactivación de OTRO formulario. form_id, pk_field_id, pk_prefill_enabled (opcional) Scope write. Gate real: admin del proyecto, o delegado de "forms-management". "Poné la cédula como PK de este formulario de matrícula."
forms_create_custom_notification Crea una notificación de canal email (custom_form_notifications) sobre un formulario. El project_id se deriva del formulario, nunca se pasa. Nace activa por default y sin condiciones: dispara en CADA respuesta nueva y manda correos reales. Para apagarla, forms_update_custom_notification con is_active:false; para borrarla, forms_delete_custom_notification. form_id, name (único por form), targets (1-20), subject, body_content; opcionales is_active, include_pdf, pdf_template_id (del mismo form), pdf_filename_template Scope write. Gate real: admin del proyecto del form, o delegado de "notifications-management"/"forms-management". "Creá una notificación que le mande a calidad@empresa.com cada inspección nueva, con el PDF adjunto."
forms_update_custom_notification Edita destinatarios y/o activo/inactivo de una notificación de canal email (custom_form_notifications). targets es REEMPLAZO COMPLETO, nunca merge — lo que no mandás se pierde. Un webhook rechaza targets (solo is_active es editable ahí). Cambia a QUIÉN le llega un correo de verdad. notification_id, targets (array, opcional), is_active (bool, opcional) — al menos uno de los dos Scope write. Gate real: admin del proyecto de la notificación, o delegado de "notifications-management"/"forms-management". "Sacá a este usuario de los destinatarios de la notificación de inspección diaria."
forms_delete_custom_notification BORRA físicamente una notificación de canal email (custom_form_notifications) — irreversible, sin papelera. Segundo factor obligatorio: expected_name tiene que ser exactamente el nombre actual. Si hay plantillas de tarea vinculadas (centralized_notification_id), se rechaza listándolas salvo force:true, que las desvincula. El historial de envíos se conserva. notification_id, expected_name; opcional force (default false) Scope write. Gate real: admin del proyecto del form, o delegado de "notifications-management"/"forms-management"; además tiene que poder ver todas las plantillas del proyecto. "Borrá la notificación de prueba que creamos ayer en el form de inspecciones."
forms_create_task_template Crea una Plantilla de Tarea completa (General, Asignación, Herencia, Filtros) en un solo llamado: la automatización que dispara una tarea nueva en un formulario destino cuando llega una respuesta a un formulario origen. Valida antes de escribir que los ids de mapeo/filtros existan y sean compatibles. project_id, source_form_id, target_form_id, title, assignment (unión discriminada: static/static_email/static_role/dynamic), más inheritance_mapping, filters, min_days/due_days — opcionales Scope write. Gate real: admin del proyecto, o delegado del menú "task-templates". "Creá una plantilla que asigne una tarea de seguimiento cuando llegue una respuesta al formulario de matrícula."
forms_update_task_template Edita una Plantilla de Tarea existente con semántica de PATCH — solo se escriben los campos que mandás (project_id no es editable acá: mover una plantilla de proyecto es cambio de tenant, no una edición). Si el patch toca los forms/mapeos, corre el mismo pre-vuelo que la creación. template_id, patch (objeto con los campos a cambiar) Scope write. Gate real: admin del proyecto, o delegado del menú "task-templates". "Cambiá el asignado por default de esta plantilla de tarea a Juan."
forms_begin_attachment_upload Primer paso de la vía de adjuntos por referencia: devuelve una URL temporal y firmada a la que subir el archivo directamente, sin que su contenido pase por la conversación. Existe porque mandar el archivo dentro de la propia llamada se truncaba con cualquier archivo de tamaño real — forms_submit_attachment sigue disponible y sin cambios para archivos chicos. form_response_id, original_field_id, file_name, content_type, size_bytes Scope write. Gate real: quien pueda escribir esa respuesta. La URL es de un solo uso y vence. "Subí esta foto de la inspección a la respuesta del formulario."
forms_finish_attachment_upload Segundo paso: lee el archivo ya subido, compara su tamaño y su huella sha256 contra lo declarado, y solo entonces lo registra en la respuesta. Si no coinciden falla y no registra nada — es la verificación que impide el "éxito falso" que arrastraba la vía anterior. upload_id (el que devolvió begin), sha256 Scope write. Mismo gate que begin. "Ya subí el archivo, confirmá que llegó completo."
forms_request_attachment_upload Tercera vía de adjuntos, para cuando VOS no tenés salida de red hacia el storage: pide un link de un solo uso (30 min de vida) para que una PERSONA lo abra en su navegador y suba el archivo. Ni vos ni el archivo pasan por acá — solo el link. form_id, original_field_id, form_response_id (opcional) Scope write. Sin form_response_id: cualquiera con acceso a la app en el proyecto. Con él: mismo gate que begin. "Necesito que alguien me suba un comprobante — mandame un link."
forms_get_attachment_upload Consulta el estado de un link de forms_request_attachment_upload. Cuando la persona ya subió el archivo, esta tool lo verifica de verdad contra storage (nunca confía en lo que declaró el navegador) y recién ahí lo registra — mismo criterio de integridad que finish. upload_id Scope write. Anti-IDOR: solo quien pidió el link puede consultarlo. "¿Ya subieron el archivo? Fijate si está todo bien."
forms_list_consent_purposes Lista el catálogo cerrado de finalidades de consentimiento (code, controller, nature, active). Sin filtros — el catálogo es el mismo para cualquier proyecto. — (sin argumentos) Scope de lectura. Sin gate — el catálogo no es sensible. "¿Qué finalidades de consentimiento existen?"
forms_get_consent_status Reconstruye qué se le presentó y qué decidió el titular de UNA respuesta concreta: por finalidad, decisión, quién la capturó, canal, cuándo, y la política/label exactos que se le mostraron. form_response_id Scope de lectura. Gate real: admin del proyecto del form, resuelto DESDE la respuesta. "¿Qué consentimiento dio quien mandó esta respuesta?"
forms_list_consent_records Lista el ledger append-only de consentimiento de un formulario, para auditoría o para responder un requerimiento de la SIC. Filtros opcionales por finalidad y rango de fecha. form_id, purpose_code?, from?, to? Scope de lectura. Gate real: admin del proyecto. "Mostrame el historial de consentimiento de este formulario."
forms_set_form_consent_config Configura qué finalidades del catálogo se le presentan al titular en un formulario. Bloqueo duro: una finalidad bloqueada (dato sensible o menor de edad) no se puede configurar por acá bajo ninguna circunstancia. form_id, client_policy_id, purposes (lista de {purpose_code, display_order}) Scope write. Gate real: admin del proyecto. "Este formulario debe pedir consentimiento de marketing, además del de servicio."
forms_record_client_attestation Registra la atestación de un operador del cliente cuando quien carga los datos no es el propio titular — sustituye el registro de consentimiento por respuesta en ese caso. form_id, evidencia de la atestación (ver detalle del paquete) Scope write. Gate real: admin del proyecto. "El operador de campo cargó estos datos en nombre del titular — registrá la atestación."
forms_list_pdf_templates Lista las Plantillas PDF de un formulario (tabla form_pdf_templates), activas e inactivas si lo pedís. form_id, include_inactive? Scope de lectura. Gate real: admin del proyecto o menú delegado forms-management. "¿Qué plantillas PDF tiene este formulario?"
forms_create_pdf_template Crea una Plantilla PDF de un formulario — genérica completa, u overlay solo si ya tenés un pdf_storage_path existente (subir el PDF base es otra fase, todavía no por MCP). form_id, template_type, config de la plantilla Scope write. Gate real: admin del proyecto o menú delegado forms-management. "Creá una plantilla PDF genérica para este formulario."
forms_update_pdf_template Edita una Plantilla PDF existente con semántica de PATCH: solo se escriben los campos que mandás. No hay tool de borrado — la baja es esta misma tool con is_active:false. id, campos a modificar Scope write. Gate real: admin del proyecto o menú delegado forms-management. "Desactivá la plantilla PDF vieja de este formulario."

Lo que este dominio deliberadamente no puede hacer

No hay tools para borrar formularios ni respuestas, ni para cambiar roles de usuario: son operaciones irreversibles sobre datos reales de cliente y se hacen desde la interfaz, con una persona mirando. Si Claude dice que no puede borrar algo, está funcionando como se diseñó.