itglue-mcp

Servidor MCP de solo lectura sobre el tenant de IT Glue de Example Corp / examplecorp (your-company.itglue.com). Responde "¿qué sabemos de este cliente" desde el chat, y responde "¿cuáles son las credenciales para X" con un enlace de IT Glue en lugar de un secreto.

Construido sobre el estándar remoto-MCP de la casa: servidor de recursos fastmcp + autenticación Entra ID, detrás de Nginx Proxy Manager en Portainer. Ver ~/.claude/context/mcp-server-playbook.md.

Los hallazgos de la API y la auditoría de contenido que dieron forma a este diseño están en FEASIBILITY.md. Lea §0 y §1 antes de cambiar cualquier cosa.

Las dos garantías

1. Nunca se escribe nada en IT Glue

La clave API en uso tiene derechos completos de escritura y borrado. Verificado, no asumido:

PATCH  /configurations/999999999  -> 404 "Record not found"
PATCH  /passwords/999999999       -> 404 "Record not found"
DELETE /configurations/999999999  -> 404

Una clave sin permiso de escritura falla con 401/403 antes de la búsqueda del registro. Un 404 significa que la mutación fue autorizada y simplemente no tenía nada sobre lo que actuar. IT Glue no emite claves API clásicas con solo lectura, por lo que no hay permiso del lado del servidor en el que apoyarse — la garantía está completamente en este código:

• client.py expone exactamente un método de solicitud, get(), que codifica method="GET".

• No existe un helper post/patch/put/delete. Agregar uno es una regresión de seguridad, no una característica.

• Un tripwire WriteAttemptError se dispara si se construye algo que no sea GET.

• tests/smoke_local.py verifica tanto los métodos ausentes como los verbos ausentes.

Si alguna vez se construye la escritura (Opción C en FEASIBILITY.md), irá en un proceso separado con una clave separada. Esa separación es todo el argumento de seguridad, porque los documentos de IT Glue son texto creado por el cliente que un modelo resume — es decir, entrada no confiable.

2. Nunca se devuelve ningún valor de credencial

itglue_find_credential devuelve un puntero: el nombre de la credencial, la categoría, a qué dispositivo pertenece, cuándo se rotó por última vez, si OTP está activado, y un enlace profundo de IT Glue. El humano hace clic en el enlace e inicia sesión en IT Glue para revelar el secreto.

La redacción ocurre en el camino hacia el espejo (redact.py), por lo que ninguna herramienta posterior puede filtrar un campo al olvidar eliminarlo. Los registros que IT Glue marca como restricted se descartan por completo.

Related MCP server: invgate-mcp

Por qué hay un espejo local

El filter[name] de IT Glue es solo coincidencia exacta, y algunos filtros se ignoran silenciosamente en lugar de rechazarse:

Por lo tanto, la búsqueda del lado del servidor o necesita la cadena exacta que el modelo no tiene, o miente silenciosamente. Por eso todo se refleja en RAM y se busca localmente (search.py, index.py).

Costo de sincronización, medido: ~10 solicitudes para ~7,000 registros estructurados; ~400 solicitudes para 300 cuerpos de documentos (95 listados de organizaciones + búsquedas por documento), contra un límite de 3,000 por 5 minutos. El núcleo se calienta en segundos; los documentos se calientan en segundo plano durante unos minutos, y las herramientas de documentos reportan status: indexing en lugar de colgarse.

Nada se persiste en disco — el corpus es pequeño, por lo que un reinicio simplemente re-sincroniza y no hay modo de fallo por caché obsoleta.

La búsqueda es deliberadamente tolerante porque las consultas reales se ven como "EF Vista Del Mar Unified Controller": un acrónimo, un nombre completo y un producto escrito Unifi en los datos. Se maneja con coincidencia de acrónimos (EF → Example Foundation), coincidencia difusa por palabra (unified ≈ unifi, ratio 0.83), resta de tokens de organización, y manejo de identificadores atómicos para que 192.0.2.51 no se desmenuce en ['10','105','251'].

Herramientas

Todas están anotadas con readOnlyHint: true.

La consulta para la que fue construido

"¿Cuáles son las credenciales para el controlador UniFi de Example Foundation?"

itglue_find_credential infiere la organización de la frase, resta las palabras de su nombre, hace coincidencia difusa de unified→unifi en los 460 registros de credenciales de EF, y devuelve cinco punteros — los dos en el actual Unifi Controller (New Staging) y los tres inicios de sesión más antiguos de VDM_Cloudwifi — cada uno con un enlace clicable, la URL del dispositivo y la fecha de última rotación. Ningún secreto sale del servidor.

Desarrollo local

python -m venv .venv && .venv/Scripts/activate    # Windows
pip install -r requirements.txt
cp .env.example .env      # fill in ITGLUE_API_KEY; set MCP_AUTH_ENABLED=false
python -m itglue_mcp

Nunca exponga un servidor sin autenticación. MCP_AUTH_ENABLED=false es solo para MCP Inspector en localhost.

Prueba de humo (en vivo, solo lectura)

python tests/smoke_local.py

47 aserciones contra el tenant en vivo. Lee ~/.claude/credentials/itglue.env si ITGLUE_API_KEY no está configurada en el entorno, y no necesita instalación de fastmcp. Las aserciones de credenciales son las importantes — si alguna falla, deténgase y corrija antes de desplegar.

Despliegue

1. App Entra + grupo + duración del token — scripts/setup_entra_app.ps1 (modo de prueba por defecto; -Apply para ejecutar). Aprovisiona la app, el grupo de seguridad ITGlue-MCP-Users con los cinco miembros iniciales, aplicación de asignación, y una política de duración de token de acceso de 23h59m. Ver docs/ENTRA_SETUP_CHECKLIST.md.

2. Stack de Portainer + NPM — PORTAINER_DEPLOY.md. Puerto de host 8111 (probado libre en 10.0.0.10, 2026-07-29 — 8100 y 8110 están en uso). Host público itglue-mcp.example.com.

Mantenimiento

• Rotar la clave de IT Glue — aún pendiente. Ahora vive en ~/.claude/credentials/itglue.env en formato KEY=VALUE de la casa (migrado 2026-07-30 desde un .itglueapicreds.txt en texto plano), pero eso fue un cambio de formato, no una rotación — el valor de la clave no ha cambiado. Tiene derechos de escritura + borrado y estuvo en un .txt en texto plano por un período desconocido. Para rotar: cree una nueva clave en IT Glue → Cuenta → Configuración → Claves API, actualice itglue.env y la variable ITGLUE_API_KEY del stack de Portainer, luego revoque la antigua.

• IT Glue revoca automáticamente las claves API no utilizadas por más de 90 días. La actualización del espejo mantiene esta caliente; si el servidor se estaciona, espere un 401 al despertar.

• Agregue y elimine acceso a través del grupo ITGlue-MCP-Users, no en el código.