Integración MCP (acceso para herramientas de IA)

Canopy incluye un servidor MCP (Model Context Protocol) integrado que permite a herramientas de IA — como Claude Desktop, GitHub Copilot, Cursor y VS Code — consultar y actualizar los datos de EA directamente. Las herramientas de IA también pueden cargar artefactos (hojas de cálculo, diagramas BPMN, diagramas DrawIO, documentos libres) y convertirlos en fichas, relaciones y diagramas que encajan en el metamodelo existente. Los usuarios se autentican a través de su proveedor SSO existente, y cada acción respeta sus permisos individuales.

Esta función es opcional y no se inicia automáticamente. Requiere que SSO esté configurado, que el perfil MCP esté activado en Docker Compose y que un administrador lo active en la interfaz de configuración.

Cómo funciona

Herramienta de IA (Claude, Copilot, etc.)
    │
    │  Protocolo MCP (HTTP + SSE)
    ▼
Servidor MCP de Canopy (:8001, interno)
    │
    │  OAuth 2.1 con PKCE
    │  delega al proveedor SSO
    ▼
Backend de Canopy (:8000)
    │
    │  RBAC por usuario
    ▼
PostgreSQL

Un usuario agrega la URL del servidor MCP a su herramienta de IA.
En la primera conexión, la herramienta abre una ventana del navegador para la autenticación SSO.
Tras el inicio de sesión, el servidor MCP emite su propio token de acceso (respaldado por el JWT del usuario en Canopy). El token se renueva de forma proactiva aproximadamente una hora antes de que expire.
La herramienta de IA usa este token para todas las solicitudes posteriores.
Cada consulta pasa por el sistema de permisos normal de Canopy — los usuarios solo ven los datos a los que tienen acceso.

Requisitos previos

Antes de habilitar MCP, debe tener:

SSO configurado y funcionando — MCP delega la autenticación a su proveedor SSO (Microsoft Entra ID, Google Workspace, Okta o OIDC genérico). Consulte la guía de Autenticación y SSO.
HTTPS con un dominio público — El flujo OAuth requiere una URI de redirección estable. Despliegue detrás de un proxy inverso con terminación TLS (Caddy, Traefik, Cloudflare Tunnel, etc.).

Configuración

Paso 1: Iniciar el servicio MCP

El servidor MCP es un perfil opcional de Docker Compose. Agregue --profile mcp a su comando de inicio:

docker compose --profile mcp up -d

Esto inicia un contenedor Python ligero (puerto 8001, solo interno) junto al backend y al frontend. Nginx redirige automáticamente las solicitudes /mcp/ hacia él — si el contenedor no está en ejecución, las solicitudes reciben un 502 limpio en lugar de bloquear el proxy de borde.

Paso 2: Configurar variables de entorno

Agregue estas a su archivo .env:

CANOPY_PUBLIC_URL=https://su-dominio.ejemplo.com
MCP_PUBLIC_URL=https://su-dominio.ejemplo.com/mcp

Variable	Predeterminado	Descripción
`CANOPY_URL`	`http://backend:8000`	URL interna del backend con la que se comunica el contenedor MCP (nombre del servicio Docker — rara vez necesita cambiarse).
`CANOPY_PUBLIC_URL`	`http://localhost:8920`	La URL pública de su instancia de Canopy.
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	La URL pública del servidor MCP (usada en las URIs de redirección OAuth y en los metadatos).
`MCP_PORT`	`8001`	Puerto interno del contenedor MCP (rara vez necesita cambiarse).

Paso 3: Agregar la URI de redirección OAuth a su aplicación SSO

En el registro de aplicación de su proveedor SSO (el mismo que configuró para el inicio de sesión de Canopy), agregue esta URI de redirección:

https://su-dominio.ejemplo.com/mcp/oauth/callback

Esto es necesario para el flujo OAuth que autentica a los usuarios cuando se conectan desde su herramienta de IA.

Paso 4: Habilitar MCP en la configuración de administrador

Vaya a Configuración en el área de administración y seleccione la pestaña IA.
Desplácese hasta la sección Integración MCP (Acceso a herramientas IA).
Active el interruptor para habilitar MCP.
La interfaz mostrará la URL del servidor MCP e instrucciones de configuración para compartir con su equipo.

aviso

El interruptor está deshabilitado si SSO no está configurado. Configure SSO primero.

Conectar herramientas de IA

Una vez habilitado MCP, comparta la URL del servidor MCP con su equipo. Cada usuario la agrega a su herramienta de IA:

Claude Desktop

Abra Configuración > Conectores > Agregar conector personalizado.
Ingrese la URL del servidor MCP: https://su-dominio.ejemplo.com/mcp
Haga clic en Conectar — se abre una ventana del navegador para el inicio de sesión SSO.
Tras la autenticación, Claude puede consultar y actualizar sus datos de EA.

VS Code (GitHub Copilot / Cursor)

Agregue a su .vscode/mcp.json del espacio de trabajo:

{
  "servers": {
    "canopy": {
      "type": "http",
      "url": "https://su-dominio.ejemplo.com/mcp/mcp"
    }
  }
}

El doble /mcp/mcp es intencional — el primer /mcp/ es la ruta del proxy Nginx, el segundo es el punto de acceso del protocolo MCP.

Prueba local (modo stdio)

Para desarrollo local o pruebas sin SSO/HTTPS, puede ejecutar el servidor MCP en modo stdio — Claude Desktop lo inicia directamente como proceso local.

1. Instalar el paquete del servidor MCP:

pip install ./mcp-server

2. Agregar a la configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "canopy": {
      "command": "python",
      "args": ["-m", "canopy_mcp", "--stdio"],
      "env": {
        "CANOPY_URL": "http://localhost:8000",
        "CANOPY_EMAIL": "[email protected]",
        "CANOPY_PASSWORD": "su-contraseña"
      }
    }
  }
}

En este modo, el servidor se autentica directamente con correo y contraseña (sin OAuth) y renueva el token de Canopy automáticamente en segundo plano.

Capacidades disponibles

El servidor MCP expone 47 herramientas: 30 herramientas de lectura repartidas en nueve clusters, y 17 herramientas de escritura (13 aditivas, 4 destructivas). Cada herramienta incorpora ToolAnnotations (readOnlyHint / destructiveHint / idempotentHint) para que los conectores, como Claude Desktop, puedan mostrar el carácter destructivo de una llamada en su interfaz antes de que el usuario la apruebe.

Seguridad mediante ejecución en seco en las escrituras

Cada herramienta de escritura usa por defecto dry_run=true. En este modo, el backend ejecuta cada validador y resolutor, construye el plan completo y luego revierte la transacción, de modo que nada se persiste. La herramienta de IA devuelve la vista previa al usuario; solo después de una confirmación explícita debe volver a llamar a la herramienta con dry_run=false para confirmar. Esto evita que un agente entusiasta inserte silenciosamente cientos de fichas a partir de una hoja de cálculo mal interpretada.

Para confirmaciones más grandes existe un segundo control: cualquier confirmación por encima de MCP_BATCH_CONFIRMATION_THRESHOLD (20 filas por defecto) debe repetir un confirm_token de un solo uso, emitido por la ejecución en seco previa. El token tiene un TTL de 15 minutos. Esto se aplica dos veces — primero por el wrapper de MCP, antes incluso de llamar al backend, y de nuevo por el propio backend en el endpoint de confirmación — de modo que un cliente que se salte el paso de ejecución en seco no pueda colar un lote grande sin revisar.

Lotes de mutación (registro de auditoría)

Toda llamada de escritura — sea ejecución en seco o no — abre una fila en mutation_batches antes de tocar cualquier dato, y cada evento que emite (ficha creada, relación insertada, comentario publicado, …) queda etiquetado con el id de ese lote, el nombre de la herramienta que lo invocó y el usuario autenticado. La herramienta get_change_history reconstruye el diff completo de un lote, evento por evento, a partir de su id, y rollback_batch puede revertir las escrituras de un lote (ver más abajo). Esto significa que cualquier cambio impulsado por MCP se puede rastrear exactamente hasta quién ejecutó qué herramienta y cuándo — a diferencia de la misma acción realizada desde la interfaz web.

Herramientas de lectura

El servidor expone 30 herramientas de lectura repartidas en nueve clusters.

Fichas y metamodelo

Herramienta	Descripción
`search_cards`	Buscar y filtrar fichas por tipo, estado o texto libre
`get_card`	Obtener los detalles completos de una ficha por UUID
`get_card_relations`	Obtener todas las relaciones conectadas a una ficha
`get_card_hierarchy`	Obtener los ancestros e hijos de una ficha
`list_card_types`	Listar todos los tipos de ficha del metamodelo, con sus campos y configuración
`get_relation_types`	Listar los tipos de relación, opcionalmente filtrados por tipo de ficha
`resolve_card_refs`	Prevalidar referencias a fichas basadas en nombre (p. ej. «Ventas / Gestión de clientes / CRM») antes de una importación masiva — muestra las coincidencias resueltas, ambiguas o ausentes
`analyze_impact`	Análisis de impacto multi-salto — recorre el grafo de relaciones hacia afuera desde una ficha hasta 3 saltos, agrupado por profundidad, con filtros opcionales por tipo de relación y tipo de ficha

Paneles

Herramienta	Descripción
`get_dashboard`	Panel de KPIs (conteos, calidad de datos, aprobaciones, actividad)
`get_landscape`	Fichas de un tipo agrupadas por un tipo relacionado

GRC — Registro de riesgos

Herramienta	Descripción
`list_risks`	Listado paginado y filtrable del registro de riesgos EA (TOGAF Fase G)
`get_risk`	Detalle de un riesgo con fichas vinculadas y pista de auditoría
`get_risk_metrics`	KPIs + matrices 4×4 de probabilidad × impacto inicial y residual
`get_card_risks`	Todos los riesgos actualmente vinculados a una ficha concreta

GRC — Cumplimiento

Herramienta	Descripción
`list_compliance_findings`	Hallazgos de cumplimiento agrupados por regulación (EU AI Act, RGPD, NIS2, DORA, SOC 2, ISO 27001)
`get_compliance_overview`	Puntuaciones de cumplimiento + matriz de estado por regulación + metadatos del último escaneo

Gobernanza y entrega

Herramienta	Descripción
`list_principles`	Principios EA publicados (declaración, justificación, implicaciones)
`list_adrs`	Architecture Decision Records, filtrables por iniciativa / ficha / estado / búsqueda
`get_adr`	ADR individual con secciones, fichas vinculadas, ADR relacionados y trazado de firmas
`list_soaws`	Statements of Architecture Work de una iniciativa

Informes

Herramienta	Descripción
`get_portfolio_report`	Datos de gráfico de burbujas para un tipo de ficha (por defecto, ajuste funcional × técnico)
`get_cost_treemap`	Mapa de árbol (treemap) del coste de las fichas, opcionalmente agrupado por un tipo relacionado
`get_capability_heatmap`	Mapa de calor jerárquico de capacidades de negocio
`get_data_quality_report`	Desglose de completitud por tipo de ficha

Contexto de ficha

Herramienta	Descripción
`get_card_stakeholders`	Usuarios y roles asignados a una ficha
`get_card_comments`	Hilo de comentarios de una ficha
`get_card_documents`	Enlaces a documentos adjuntos a una ficha

Diagramas

Herramienta	Descripción
`list_diagrams`	Listar diagramas de dibujo libre, opcionalmente filtrados a una ficha
`get_diagram`	Obtener un diagrama concreto por id, incluyendo su XML de DrawIO

Auditoría e historial de cambios

Herramienta	Descripción
`get_change_history`	Buscar un lote de mutación por id (devuelve el lote y todos los eventos emitidos bajo él, en orden), o explorar lotes recientes por actor, nombre de herramienta u origen (`mcp` / `web` / `api`)

Todas las herramientas de lectura están sujetas al RBAC del usuario autenticado — una persona con rol de visualización simplemente recibirá una lista vacía (o un 403) en las áreas que no puede ver; no hace falta configurar nada por herramienta a nivel de MCP.

Herramientas de escritura

El servidor expone 17 herramientas de escritura: 13 aditivas (acciones de creación/actualización que no destruyen datos) y 4 destructivas (pueden sobrescribir o eliminar datos, aunque varias de ellas son en sí mismas recuperables — ver notas más abajo).

Fichas y ciclo de vida

Herramienta	Anotación	Descripción
`create_cards_bulk`	Aditiva	Crea varias fichas en una sola llamada a partir de filas extraídas de un artefacto (p. ej. filas de una hoja de cálculo). Admite referencias al padre por nombre dentro del mismo lote, con ordenación topológica en el servidor.
`update_cards_bulk`	Aditiva	Actualiza varias fichas en una sola llamada — parches a nivel de campo con un diff antes/después por fila en la ejecución en seco. `attributes` es un reemplazo completo por fila; `strict_attributes=true` rechaza claves de campo desconocidas con una sugerencia de recuperación.
`transition_card_lifecycle`	Aditiva	Hace avanzar una ficha a través de acciones de aprobación (`approve` / `reject` / `reset`), fases del ciclo de vida (`phaseIn` / `active` / `phaseOut` / `endOfLife`) o valores de estado (`ACTIVE` / `PHASING_IN` / `PHASING_OUT` / `END_OF_LIFE` / `ARCHIVED`). Devuelve una respuesta `pending` con un enlace directo a la interfaz si quien llama carece del permiso, en lugar de fallar directamente.
`archive_cards`	Destructiva	Archiva (elimina de forma reversible) una o varias fichas, con una vista previa en cascada en la ejecución en seco (hijos, relaciones huérfanas). Las fichas archivadas son recuperables durante 30 días antes de su purga automática. La eliminación permanente (hard delete) se omite intencionadamente en MCP.

Relaciones y diagramas

Herramienta	Anotación	Descripción
`upsert_relations_bulk`	Destructiva	Crea o elimina relaciones entre fichas. `action: "delete"` se rechaza por defecto (ver las salvaguardas más abajo) — esto es lo que hace que esta herramienta lleve la anotación destructiva, aunque la creación sea el caso más habitual.
`create_diagram`	Aditiva	Crea un diagrama libre de DrawIO, opcionalmente vinculado a fichas existentes por UUID.
`update_diagram`	Destructiva	Actualiza el XML, nombre, descripción o fichas vinculadas de un diagrama existente — `drawio_xml` reemplaza el lienzo de forma literal.
`import_bpmn`	Aditiva	Guarda un diagrama BPMN 2.0 en una ficha de Proceso de negocio existente, recorriendo el flujo de trabajo borrador → enviar → aprobar. Si no existe una ficha coincidente, devuelve un error `card_not_found` que apunta a `create_cards_bulk`, en lugar de crear silenciosamente una ficha incompleta.

GRC — Registro de riesgos

Herramienta	Anotación	Descripción
`create_risks`	Aditiva	Crea uno o varios riesgos, vinculando opcionalmente las fichas afectadas en la misma llamada.
`update_risks`	Aditiva	Aplica parches a riesgos existentes por id; `linked_card_ids` reemplaza el conjunto de fichas afectadas vinculadas cuando se proporciona.

Gobernanza y entrega

Herramienta	Anotación	Descripción
`create_soaw`	Aditiva	Crea un Statement of Architecture Work para una iniciativa.
`create_adr`	Aditiva	Crea un Architecture Decision Record (queda en estado `draft` por defecto).
`update_adr`	Aditiva	Actualiza el título, las secciones, el estado o las fichas vinculadas de un ADR existente.
`sign_adr`	Aditiva	Firma un ADR. Devuelve una respuesta `pending` con un enlace directo si quien llama carece de `adr.sign`.

Colaboración

Herramienta	Anotación	Descripción
`add_card_comment`	Aditiva	Publica un comentario (opcionalmente en hilo) en una ficha.
`assign_stakeholders`	Aditiva	Asigna o elimina roles de partes interesadas en fichas. El backend no tiene un endpoint masivo para esto, así que la herramienta reparte cada operación dentro de un único lote de mutación.

Auditoría

Herramienta	Anotación	Descripción
`rollback_batch`	Destructiva	Revierte las escrituras realizadas bajo un lote de mutación, recorriendo sus eventos en orden inverso y aplicando el inverso de cada uno. Cubre `card.created` / `card.updated` / `card.archived` / `card.restored` / `relation.created` / `relation.upserted`; otros tipos de evento aparecen como `unsupported_events` en el plan de la ejecución en seco. La propia reversión se registra como un lote nuevo, de modo que el historial nunca se borra. Se rechaza si un lote posterior tocó las mismas entidades, salvo que se indique `force=true`, lo cual requiere `admin.events`.

El contenido almacenado por estas herramientas (cuerpos de comentarios, texto de secciones de ADR/SoAW) se trata como datos no confiables en lecturas posteriores — el servidor nunca lo interpreta como instrucciones, solo lo muestra.

Flujo típico de importación de artefactos

Cuando un usuario comparte una hoja de cálculo con el agente de IA:

El agente llama a list_card_types y get_relation_types para entender el metamodelo.
El agente analiza la hoja de cálculo (en su propio contexto, no en MCP) y construye diccionarios de fila.
Opcionalmente, el agente llama a resolve_card_refs para comprobar que las referencias basadas en nombre a padres o relaciones se resuelven sin ambigüedad.
El agente llama a create_cards_bulk(cards=…, dry_run=True) y muestra la vista previa al usuario.
El usuario confirma; el agente vuelve a llamar con dry_run=False (repitiendo el confirm_token si el lote supera el umbral de confirmación) para confirmar los datos.
Si hay columnas de relación, el agente llama después a upsert_relations_bulk con el mismo ciclo de ejecución en seco / confirmación.

El propio servidor MCP nunca analiza los archivos subidos — la herramienta de IA que llama lee el artefacto de origen (hoja de cálculo, XML de BPMN, XML de DrawIO, PDF, imagen) en su propio contexto y envía filas ya estructuradas.

Salvaguardas de las herramientas de escritura

Defensa en profundidad sobre la ejecución en seco, para que un descuido del LLM no pueda causar daños masivos:

Límites de tamaño por llamada. Las herramientas de escritura de MCP aplican un límite mucho menor que los endpoints subyacentes del importador de Excel: 200 fichas para create_cards_bulk / update_cards_bulk / archive_cards, 500 operaciones para upsert_relations_bulk. Suficientemente grande para cualquier carga realista de un único artefacto, suficientemente pequeño para que una vista previa de ejecución en seco siga siendo revisable. Los propios endpoints del backend aceptan hasta 2000/5000 para el importador de Excel legítimo de la interfaz web.
Token de confirmación por encima del umbral. Las confirmaciones que afecten a más de MCP_BATCH_CONFIRMATION_THRESHOLD filas (20 por defecto) deben repetir el confirm_token emitido por la ejecución en seco previa. Se aplica tanto en el wrapper de MCP como en el backend.
Sin eliminación de relaciones por defecto. upsert_relations_bulk rechaza las operaciones action: "delete" — para eliminar relaciones, use la interfaz web, donde la acción queda registrada bajo la identidad del usuario con una pista de auditoría explícita. Los operadores pueden activarlo con MCP_ALLOW_RELATION_DELETE=true.
Sin eliminación permanente. El conjunto de herramientas omite deliberadamente el borrado permanente de fichas. archive_cards (eliminación reversible, con ventana de restauración de 30 días) y rollback_batch son las únicas formas de eliminar datos a través de MCP, y ambas están protegidas por la ejecución en seco y llevan la anotación destructiva. Cualquier herramienta futura que realice una mutación irreversible necesita antes una discusión de tipo RFC.
Interruptor de apagado. MCP_WRITES_ENABLED=false desactiva las 17 herramientas de escritura sin necesidad de redesplegar código. Las 30 herramientas de lectura siguen funcionando.
Etiqueta de origen para auditoría. Cada solicitud al backend desde el servidor MCP lleva un encabezado X-Canopy-Origin: mcp (con lista blanca en el servidor limitada a {mcp, web, api} — cualquier otro valor se descarta). Los eventos emitidos desde esas solicitudes se etiquetan con origin: "mcp" en el payload de auditoría, de modo que los administradores pueden filtrar de la línea de tiempo las escrituras impulsadas por MCP. El encabezado X-Canopy-Batch propaga el id del lote de mutación actual a través de todas las llamadas de una misma invocación de herramienta.

Las variables de entorno de salvaguarda en el contenedor MCP:

Variable	Predeterminado	Efecto
`MCP_WRITES_ENABLED`	`true`	Interruptor maestro de las herramientas de escritura. `false` → MCP de solo lectura.
`MCP_MAX_CARDS_PER_CALL`	`200`	Límite estricto de filas por llamada para `create_cards_bulk`, `update_cards_bulk`, `archive_cards`.
`MCP_MAX_RELATIONS_PER_CALL`	`500`	Límite estricto de operaciones de `upsert_relations_bulk` por solicitud.
`MCP_ALLOW_RELATION_DELETE`	`false`	Cuando es `true`, `upsert_relations_bulk` acepta operaciones `action: "delete"`.
`MCP_BATCH_CONFIRMATION_THRESHOLD`	`20`	Número de filas por encima del cual una confirmación debe repetir un `confirm_token` de una ejecución en seco previa.
`MCP_REQUIRE_DRYRUN_FIRST`	`true`	Cuando es `true`, se rechaza una confirmación por encima del umbral que no tenga una ejecución en seco previa coincidente en la misma sesión. Los operadores pueden desactivarlo para flujos de automatización de confianza.

Recursos

URI	Descripción
`turbo-ea://types`	Todos los tipos de ficha del metamodelo
`turbo-ea://relation-types`	Todos los tipos de relación
`turbo-ea://dashboard`	KPIs del panel y estadísticas resumidas

Prompts guiados

Prompt	Descripción
`analyze_landscape`	Análisis en varios pasos: resumen del panel, tipos, relaciones
`find_card`	Buscar una ficha por nombre, obtener detalles y relaciones
`explore_dependencies`	Mapear de qué depende una ficha y qué depende de ella

Permisos

Rol	Acceso
Administrador	Configurar los ajustes de MCP (permiso `admin.mcp`). Acceso completo de lectura y escritura a través de MCP.
Todos los usuarios autenticados	Acceso de lectura regido por su RBAC existente. Las herramientas de escritura requieren el permiso de backend correspondiente a la acción que realizan.

El acceso a los datos a través de MCP — lectura o escritura — sigue el mismo modelo RBAC que la interfaz web. Si un usuario no puede crear fichas en la interfaz de inventario, tampoco puede crearlas a través de MCP; no existen permisos de datos específicos de MCP. Permisos seleccionados por herramienta:

Permiso	Rige
`inventory.create`	`create_cards_bulk`
`inventory.edit`	`update_cards_bulk`, transiciones de ciclo de vida/estado mediante `transition_card_lifecycle`
`inventory.approval_status`	Transiciones de aprobación (`approve` / `reject` / `reset`) mediante `transition_card_lifecycle`
`inventory.archive`	`archive_cards`
`relations.manage`	`upsert_relations_bulk`
`diagrams.manage`	`create_diagram`, `update_diagram`
`bpm.edit`	`import_bpmn` (borrador); publicar además requiere `card.approval_status` sobre el proceso, obtenido mediante el rol de parte interesada `process_owner`, admin o bpm_admin
`risks.manage`	`create_risks`, `update_risks`
`comments.create`	`add_card_comment`
`stakeholders.manage`	`assign_stakeholders`
`soaw.create`	`create_soaw`
`adr.create`	`create_adr`, `update_adr`
`adr.sign`	`sign_adr`
`admin.events`	`rollback_batch(force=True)` — para anular un conflicto de reversión con un lote posterior

El permiso admin.mcp controla quién puede gestionar la configuración de MCP. Por defecto solo está disponible para el rol Administrador. Los roles personalizados pueden recibir este permiso a través de la página de administración de Roles.

Varias herramientas de escritura se degradan con elegancia en lugar de fallar directamente cuando quien llama carece de un permiso: transition_card_lifecycle y sign_adr devuelven una respuesta pending con un enlace directo a la interfaz web para que una persona con el permiso adecuado pueda completar la acción allí.

Seguridad

Autenticación delegada por SSO: los usuarios se autentican a través de su proveedor SSO corporativo. El servidor MCP nunca ve ni almacena contraseñas (en modo HTTP).
OAuth 2.1 con PKCE: el flujo de autenticación utiliza Proof Key for Code Exchange (S256) para prevenir la interceptación de códigos de autorización.
RBAC por usuario: cada consulta MCP — de lectura o escritura — se ejecuta con los permisos del usuario autenticado. Sin cuentas de servicio compartidas.
Ejecución en seco por defecto en las escrituras: las herramientas de escritura ofrecen por defecto una vista previa de validar y revertir. La herramienta de IA debe volver a llamar explícitamente con dry_run=false antes de que se persista cualquier dato, y cada cambio queda auditado bajo la identidad del usuario como parte de un lote de mutación.
Control de token de confirmación en confirmaciones grandes: las confirmaciones por encima del umbral de filas configurable requieren un token emitido por una ejecución en seco previa, comprobado de forma independiente tanto por el wrapper de MCP como por el backend.
Pista de auditoría completa con reversión: get_change_history reconstruye el diff de cualquier lote a partir de su id; rollback_batch puede revertir los tipos de evento admitidos de un lote, quedando ella misma registrada como un nuevo lote auditable.
Sin análisis de archivos en MCP: el servidor MCP en sí mismo no acepta PDF, archivos Excel, imágenes ni otros artefactos binarios. La herramienta de IA que llama los analiza en su propio contexto y envía filas estructuradas. Esto mantiene la superficie de ataque reducida y evita exponer el servidor a entradas binarias malformadas.
Sin eliminación permanente a través de MCP: la eliminación permanente de fichas no se expone como herramienta. Las únicas vías de eliminación son archive_cards (eliminación reversible con ventana de 30 días) y rollback_batch.
Rotación de tokens: los tokens de acceso expiran después de 1 hora y se renuevan de forma proactiva. Los tokens de renovación duran 30 días. Los códigos de autorización son de un solo uso y expiran después de 10 minutos.
Puerto solo interno: el contenedor MCP expone el puerto 8001 solo en la red interna de Docker. Todo acceso externo pasa por el proxy inverso Nginx.
Almacén de tokens de instancia única: los tokens OAuth se mantienen en memoria en el contenedor MCP. Si ejecuta varias réplicas detrás de un balanceador de carga, fije las sesiones a una sola instancia o espere que los usuarios tengan que volver a autenticarse tras un failover — los tokens no se comparten entre réplicas.

Solución de problemas

Problema	Solución
El interruptor MCP está deshabilitado en la configuración	SSO debe estar configurado primero. Vaya a Configuración > pestaña Autenticación y configure un proveedor SSO.
«host not found» en los registros de Nginx	El servicio MCP no está en ejecución. Inícielo con `docker compose --profile mcp up -d`. La configuración de Nginx maneja esto de forma elegante (respuesta 502, sin caída).
La devolución de llamada OAuth falla	Verifique que agregó `https://su-dominio.ejemplo.com/mcp/oauth/callback` como URI de redirección en el registro de su aplicación SSO.
La herramienta de IA no puede conectarse	Verifique que `MCP_PUBLIC_URL` coincide con la URL accesible desde la máquina del usuario. Asegúrese de que HTTPS funciona.
El usuario obtiene resultados vacíos	MCP respeta los permisos RBAC. Si un usuario tiene acceso restringido, solo verá las fichas que su rol permite.
La herramienta de escritura devuelve `writes_disabled`	`MCP_WRITES_ENABLED=false` está activo en este despliegue. Las herramientas de lectura siguen funcionando; pida a un operador que reactive las escrituras si es necesario.
La confirmación se rechaza con `confirm_token_required`	El lote supera las filas de `MCP_BATCH_CONFIRMATION_THRESHOLD`. Vuelva a ejecutar primero con `dry_run=true` y luego pase el `confirm_token` devuelto en la llamada de confirmación.
La conexión se interrumpe después de 1 hora	La herramienta de IA debería manejar la renovación de tokens automáticamente. Si no, reconecte.

Cómo funciona​

Requisitos previos​

Configuración​

Paso 1: Iniciar el servicio MCP​

Paso 2: Configurar variables de entorno​

Paso 3: Agregar la URI de redirección OAuth a su aplicación SSO​

Paso 4: Habilitar MCP en la configuración de administrador​

Conectar herramientas de IA​

Claude Desktop​

VS Code (GitHub Copilot / Cursor)​

Prueba local (modo stdio)​

Capacidades disponibles​

Seguridad mediante ejecución en seco en las escrituras​

Lotes de mutación (registro de auditoría)​

Herramientas de lectura​

Herramientas de escritura​

Flujo típico de importación de artefactos​

Salvaguardas de las herramientas de escritura​

Recursos​

Prompts guiados​

Permisos​

Seguridad​

Solución de problemas​