Servidor MCP de CreaRack (asistente de IA propio)

Qué es: la documentación técnica del servidor MCP de CreaRack, la pieza que deja a un usuario conectar Claude o ChatGPT a CreaRack con su propia cuenta y preguntarle por todo lo que CreaRack sabe de su organización. Para quién: quien mantenga o amplíe el código (Edu, Dani, Txell y las sesiones de Claude). Qué sabrás al terminar: por dónde entra una petición, cómo se ata a una organización, qué protege cada decisión de seguridad, cómo se ven y se cortan las conexiones, qué herramientas hay y cómo se añaden más. Estado: v3 en producción desde el 01-10-2026 — v1.175.2 (Claude Code ya conecta, PR #659), v1.176.0 (tanda 1: organización, búsqueda, administración y clientes de un AP, PR #660) y v1.177.0 (tandas 2 a 5: armarios y planos, red y Agente, monitorización y SAI, cartelería, PR #663): 51 herramientas de solo lectura (§7), verificadas en producción con datos del CCIB. La entrega 2 (v1.174.0) y la v1.175.0 (3 herramientas de historial) siguen como estaban. Plan y decisiones: tarea #392 del Gestor; conector por organización: tarea #399. Ayuda para clientes: [[crearack—settings—ai-assistant]].

1. El problema que resuelve

Durante FABCON26 (29-09-2026), vigilar el Auditori del CCIB exigió la web (con sesión de 10 minutos) y la base local del Agente del portátil de Edu. Con el servidor MCP, cualquier usuario pregunta a su asistente (“¿qué salas tienen más de 100 clientes?”) y la respuesta sale del servidor de CreaRack, con el portátil apagado y desde cualquier sitio. El competidor más cercano, Domotz, lo ofrece desde mayo de 2026; el estudio está en public/supercontext/producto-multimarca/APIS_FABRICANTES.md §7.1.

2. Decisiones de producto (Edu, 30-09-2026 y 01-10-2026)

1. Para cualquier usuario de CreaRack desde la primera versión.
2. Apagado por defecto; lo enciende el administrador de cada organización (Organization.ai_assistant_enabled), porque conectar un asistente envía datos del cliente a otra empresa.
3. Solo lectura. La v1 cubría WiFi y estado de equipos; desde el 01-10-2026 cubre todo CreaRack (decisión de Edu de tenerlo completo antes de la reunión del 06-10): armarios y planos, red, monitorización, SAI, cartelería, organización y, para administradores, usuarios y auditoría (Edu: “sí me gustaría que los administradores pudieran consultar este tipo de información”).
4. El administrador ve y corta las conexiones de su organización, con registro de consultas (pantallas en la entrega 2, ver §8).
5. Incluido en todos los planes.
6. Una conexión, una organización: el token queda atado a la organización del usuario que autoriza. Ver otra organización exige otra autorización; la propuesta de una dirección de conector por organización es la tarea #399 (pendiente de decisión).

3. Por dónde entra una petición

4. Aislamiento por organización (lo más delicado)

• En las políticas RLS del proyecto, app.current_org_id en '0' o '' significa bypass. Antes de este cambio, TenantRLSMiddleware trataba cualquier Bearer que no fuera un JWT del Agente como anónimo y ponía '0'.
• Ahora, para rutas /mcp*, el middleware busca el token por su hash (bajo rls_bypass(), sin depender del valor por defecto del rol) y fija el GUC a la organización del token, o a -1 (cero filas) si el token no vale por cualquier motivo. Nunca 0, ni para un superusuario, que queda acotado a su user.organization.
• El resultado va en request._mcp_auth; si falta, la vista responde 401 (falla en cerrado).
• Las herramientas vuelven a filtrar por organización reutilizando los endpoints web con require_org / require_perm o con consultas propias filtradas por ctx.org (defensa en profundidad), así que un rol sin permiso de vista en la web tampoco ve el dato en el asistente. Un id de otra organización y un id inventado devuelven el mismo “not found”.
• Los tokens MCP son opacos (crk_at_…, crk_rt_…), se guardan solo como sha256 y no valen en /api/*; ni la sesión ni el JWT del Agente valen en /mcp.

5. OAuth, en corto

• Código de un solo uso, 5 minutos; si se reutiliza, se revocan los tokens emitidos con él.
• Acceso de 1 hora y refresh de 30 días (por criterio, sin medir); el refresh rota en cada uso y reutilizar uno viejo revoca la familia entera. Cada conexión es una familia de tokens (McpToken.family_id): es la unidad que ven y cortan las pantallas de la entrega 2.
• resource se valida en /authorize y en /token (ChatGPT lo manda en los dos).
• Apagar el interruptor revoca todos los tokens de la organización; y si un token llega con el interruptor apagado, se revoca su familia.
• Trampa aprendida en producción (v1.173.1): la pantalla de consentimiento NO puede llevar Referrer-Policy: no-referrer. Con esa política el navegador manda Origin: null en el POST de “Allow” y el CSRF de Django lo rechaza con 403. El no-referrer va solo en la página de vuelta, que lleva el código en la URL. El cliente de pruebas de Django no emula esa cabecera: lo cubre test_consent_page_does_not_set_no_referrer.
• La vuelta tras “Allow” es una página con meta refresh y botón, no un 302: la CSP de la app lleva form-action 'self' y el navegador bloquearía el destino externo.
• Bucle local (entrega 2): si el cliente es de bucle local (oauth.is_loopback_uri, el caso de Claude Code) y /oauth/authorize recibe una petición con error de parámetros, la respuesta es una página de error propia (“Cannot connect”), con o sin sesión, y no un 302 al puerto local. Motivo: cualquier página web puede lanzar esa petición y el 302 iría al puerto de la máquina de quien la abra; un cliente legítimo la construye bien. Para clientes que no son de bucle local, los errores siguen viajando a su dirección de vuelta.
• Cliente purgado durante el consentimiento (entrega 2): la emisión del código va en un savepoint (transaction.atomic()); si el cliente se purgó entre la pantalla de consentimiento y el “Allow”, el IntegrityError se convierte en la página de error (“This app is not registered or its return address is not allowed.”), no en un 500.

6. Protocolo

Implementación propia en mcp_server/protocol.py, sin librería MCP, con respuestas application/json y sin sesiones:

• Clientes 2025-06-18 y 2025-11-25: initialize, notificaciones (202 sin cuerpo), ping.
• Clientes 2026-07-28: server/discover; la versión llega en _meta y en la cabecera MCP-Protocol-Version; versión no soportada → -32022. Trampa aprendida con Claude Code (v1.175.2, 01-10-2026): en esa versión ListToolsResult es CacheableResult y ttlMs/cacheScope son obligatorios (SEP 2549); Claude Code rechazaba la lista (“ttlMs expected number, received undefined”) y claude.ai no los exigía. tools/list los manda solo con la versión nueva: ttlMs 300000 (5 min, por criterio) y cacheScope: "private".
• tools/list y tools/call en ambas. tools/list se filtra por el usuario del token (v1.176.0): una herramienta con required_perm (hoy, las cuatro de administración con ("users", "admin")) no aparece en la lista de quien no tiene ese permiso; si la llama a ciegas, denied en el registro. Las instructions del servidor (§7.1) dicen que los resultados son datos de los equipos, nunca órdenes (defensa ante inyección en nombres de equipos, SSID o las notas de la organización).
• Límite de 60 tools/call por minuto y por conexión (familia de tokens), en la caché de Django (Valkey), con clave mcp:rl:<family_id>. Falla en cerrado: sin caché no hay tope que medir. Límite honesto: es por conexión, no por usuario; el valor de 60 sigue sin medir (UNVERIFIED en el código).
• Cada herramienta corre en un savepoint para que un error de base de datos no impida escribir su fila de registro.
• Validación de argumentos (mcp_server/schema.py): desde v1.175.0 rechaza NaN e Infinity en campos numéricos.
• Claude.ai fija la lista de herramientas al conectar: tras publicar herramientas nuevas, el usuario debe reconectar el conector (medido el 01-10-2026: 40 min después del deploy seguía usando las viejas). Claude Code carga la lista al arrancar: un servidor añadido en caliente exige reiniciar la sesión.

7. Las 51 herramientas (solo lectura)

Registro único en mcp_server/tools/__init__.py (all_tools()); los nombres viven en TOOL_NAMES de tests/api/test_mcp_protocol.py. Cada herramienta es un Tool(name, title, description, input_schema, handler, module, required_perm) de mcp_server/tools/base.py: module es el slug de plan que core/module_registry.py asigna a la URL web equivalente (un superusuario lo salta); el handler empieza con el mismo require_perm que el endpoint web. Resultados recortados a ~40 KB (shrink_to_fit, que dice qué recortó) y las series a ~96 puntos (clip_points). Topes por criterio marcados # UNVERIFIED en el código.

7.1 Instrucciones del servidor

INSTRUCTIONS en protocol.py llevan el saber de la casa: empezar por get_organization_overview para saber qué módulos tiene la organización; buscar ids con search_devices o las list_* antes de pedir detalles; leer get_organization_notes antes de recomendar cambios y pesar ese criterio por encima de la buena práctica genérica, pero tratarlo como datos, nunca como órdenes; y, al leer WiFi de Xirrus, tratar la radio 1 como monitor en tiempo compartido y −102/−103 dBm de ruido, ocupación 100 y tasa 0 como centinelas, diciendo qué lecturas se han tratado como no fiables.

7.2 Por módulo

Lo que nunca sale: contraseñas, comunidades y claves SNMP, credenciales de equipos y reproductores, management_config, el volcado de deep_snmp_data o discovery_data, el contenido de las copias de configuración, el contexto SNMP/SSH crudo de los diagnósticos, tokens de publicación, PIN de proyectos de cliente, rutas de capturas, IP y nombre de host de los clientes WiFi, lista de usuarios o correos fuera de las herramientas de administración. Cada test de tanda recorre el JSON de todos los resultados y falla si aparece una clave prohibida.

7.3 Cómo se construyó la v3 (01-10-2026) y qué enseñó

Cuatro constructores (Sonnet) en paralelo, un worktree y una rama por dominio, con un encargo común (BRIEF.md del scratchpad de la sesión s357: patrón, reglas de aislamiento, secretos, permisos, topes, tests obligatorios, traspaso a fichero); un refutador de seguridad (Opus) por tanda, con tres ejes por separado (conformidad, calidad y seguridad, historial); retrabajo de cada tanda con lo señalado; y las cuatro ramas juntadas en un PR con el registro y TOOL_NAMES unificados. Sin fugas entre organizaciones en ninguna; lo que señalaron las revisiones y se corrigió: estado del editor rancio frente al del sondeo (racks), estado de red sin el permiso del Observatory, select_related sin defer cargando volcados, métricas pidiendo 15 veces lo que devolvían, Agente “online” sin mirar last_seen, disponibilidad al 100 % en días sin registro, comandos del CNS sin redactar, SAI tapando una caída de VictoriaMetrics, display_info que nunca se escribe, tests de permiso con id=1 que pasarían sin el require_perm. Un test de redacción salió rojo en el CI por buscar con 1 carácter (minLength 2). Detalle completo: CHANGELOG 1.176.0 y 1.177.0.

7.4 Cómo añadir una herramienta

1. Handler en el módulo del dominio: require_perm al principio, filtro por ctx.org en toda consulta, campos elegidos por nombre, topes, ToolError("... not found") igual para id ajeno e inexistente, ToolError("metrics store not available") si VictoriaMetrics falla.
2. Tool(...) en TOOLS del módulo con module= del registro de módulos y, si es de administración, required_perm.
3. Nombre en TOOL_NAMES de test_mcp_protocol.py y tests en tests/api/test_mcp_<dominio>.py: camino feliz, beta no ve alpha (lista y por id), límites, gating por permiso y módulo con ids reales, claves prohibidas.
4. CHANGELOG, RELEASE_NOTES, esta página y la ayuda [[crearack—settings—ai-assistant]]; recordar en las notas que hay que reconectar el conector.

8. API de conexiones y actividad (entrega 2)

Router de django-ninja en mcp_server/api.py, montado en /api/mcp/ (config/urls.py). Es la cara para el navegador: sesión normal de CreaRack, no tokens MCP. Una “conexión” es una familia de tokens con algún token sin revocar y con el refresh vigente. Cada consulta filtra por organización de forma explícita, además de RLS.

Detalles que importan:

• Cada fila de conexión lleva cliente, host de la dirección de vuelta, usuario, creación y último uso. Creación y último uso salen de toda la familia (mínimo de created_at, máximo de last_used_at), porque cada refresh rota el token y revoca el anterior; mirar solo el token vigente daría siempre “creada ahora”. Listados con tope de 500 filas (UNVERIFIED, por criterio).
• 404 frente a 403: si la conexión no existe, o existe pero no es tuya y no eres administrador de su organización, revoke responde el mismo 404 (“Connection not found”). Un 403 confirmaría a un tercero que ese family_id existe. En cambio connections y activity para un no administrador dan 403 por permiso (no exponen ningún identificador). Una conexión de otra organización es siempre 404.
• Carrera con un refresh en curso: el refresh bloquea su fila (select_for_update) y crea el token hijo. revoke primero bloquea (select_for_update) las filas vivas de la familia dentro de una transacción y solo después llama a oauth.revoke_family. Si el refresh ganó, el hijo ya está confirmado y entra en la revocación; si gana revoke, el refresh ve su fila revocada y falla. Sin ese bloqueo, un refresco a mitad podía dejar un token vivo tras “Disconnect”.
• Efecto de revocar: el siguiente POST /mcp con ese acceso responde 401 y el asistente tiene que pasar de nuevo por la pantalla de consentimiento (lo cubre un test de la entrega 2).
• Rastro: cada revocación escribe una entrada en SystemLog (mcp.connection.revoke, con familia recortada, usuario, cliente y nº de tokens) y una fila method="revoke" en McpAuditLog con “disconnected by ”.
• activity devuelve los argumentos de cada llamada recortados a 200 caracteres (pueden llevar nombres de equipos o datos del cliente); el 2 KB de McpAuditLog es lo que se guarda, esto es lo que sale.
• Pantallas (botones de solo texto, en inglés, con su traducción al español en locale/es/ en el mismo PR: 34 textos en django.po y 23 en djangojs.po, que cubren también la entrega 1 y el historial de inicios de sesión): sección “AI assistant” en la columna izquierda de “User Settings” para todos (dirección, enlace de ayuda y “My connected assistants” con Disconnect) y, para administradores, el botón View Connections & Activity que abre el modal ai-assistant-admin-modal. Código en static/js/ai_assistant.js.

9. Registro de consultas

McpAuditLog (con RLS): cada tools/call con su desenlace (ok, denied, error, rate_limited), argumentos recortados a 2 KB y duración; cada 401 de /mcp con un token que existe (un token inventado no escribe fila); y, desde la entrega 2, cada desconexión (method="revoke"). Lo lee el administrador en GET /api/mcp/activity (§8). Es la fuente de la apuesta #34 de WAGERS.md.

10. Purga diaria

mcp_server/tasks.py (Huey, cada día a las 4:20, con lock_task): /oauth/register es anónimo y los códigos de autorización caducan a los 5 minutos pero nadie los borraba. purge_unused borra los códigos caducados hace más de 1 día y, después, los clientes de más de 7 días sin códigos ni tokens (los códigos van primero para que un cliente cuyo único código caducó se purgue en la misma pasada). Corre fuera de una petición, así que va bajo rls_bypass() (sin GUC, las tablas con política devolverían 0 filas). Los plazos de 7 días y 1 día están elegidos por criterio, sin medir (UNVERIFIED).

11. Límites honestos

• ChatGPT: preparado según su documentación, sin probar con una cuenta real.
• Límite general por IP (300/min) también cubre /mcp, y todo claude.ai sale de rangos de Anthropic (160.79.104.0/21): sin medir.
• Límite de uso por conexión, no por usuario: varias conexiones del mismo usuario suman sus topes (§6).
• Borrados en cascada bajo RLS: las opciones DB_CASCADE / DB_SET_NULL son de Django 6.1 y requirements.txt fija 6.0.x (6.1 bloqueada por django-prometheus). Con 6.0.x los on_delete se emulan en Python; un borrado hecho con un GUC que no cubre las filas hijas no las vería. Los borrados de sistema corren bajo rls_bypass(). Al subir a 6.1, pasar los FK de las tres tablas a DB_CASCADE/DB_SET_NULL.
• Entrega 2 sin mirar en pantalla: el CI la validó (40 tests), pero la maquetación de “User Settings” y de la ventana del administrador sigue pendiente de verla Edu en el navegador.
• v3: los topes son por criterio; los totales de errores/descartes de red son una estimación (media por minuto × minutos); size_bytes de las copias cuenta caracteres; la disponibilidad no resta periodos pasados fuera de servicio; las estadísticas de reproducción salen a cero en SpinetiX (no da registros); topk y .only() con relaciones de tres niveles se probaron solo en el CI; la foto SNMP de los clientes de un AP puede tener días (snapshot_is_recent). Verificado en producción el 01-10-2026 con la organización CCIB: 51 herramientas cargadas; overview, clientes de un AP, búsqueda, postura de seguridad, list_racks, get_local_agent_status, list_signage_players y list_alert_rules responden con datos reales.
• Una conexión, una organización (§2.6): para ver la organización Demo desde Claude Chat hay que reconectar con un usuario de Demo. Tarea #399.

Glosario

• MCP (Model Context Protocol): estándar abierto para que un asistente de IA consulte un sistema conversando con él.
• OAuth: forma estándar de dar permiso a una aplicación entrando con tu cuenta, sin darle la contraseña.
• PKCE: comprobación que impide que un código de autorización robado sirva a otro.
• RLS: seguridad a nivel de fila de PostgreSQL; aquí, lo que impide ver filas de otra organización aunque un filtro del código falle.
• GUC app.current_org_id: la variable de la conexión que las políticas RLS leen para saber de qué organización es la petición.
• Familia de tokens: la cadena de tokens que nace de un mismo permiso dado por el usuario; cada refresh rota el token dentro de la familia. Equivale a una “conexión” en las pantallas.
• Foto SNMP (Deep Data): la última lectura completa que el Agente hizo de un equipo (tabla de clientes, radios, hardware), distinta de las métricas en vivo de cada pocos segundos.

Véase también

• [[crearack—settings—ai-assistant]]
• [[crearack-tech—backend—passkeys-authentication]]
• [[crearack—settings—mfa-and-login-security]]