byteforge-aegis-mcp

Un servidor MCP de solo lectura sobre la API de administración de ByteForge Aegis, desplegado como un contenedor detrás de nginx con autenticación Gatekeeper.

Por qué

Los agentes que trabajan en Aegis y en integraciones de inquilinos necesitan responder repetidamente a la pregunta "¿qué está realmente configurado en producción?" — si la URL del webhook está establecida, si allow_self_registration está activado, qué sitios existen, si este usuario existe. Antes de este servidor, esa pregunta se respondía con curls improvisados que llevaban la clave maestra de la API, o no se respondía en absoluto — una solicitud de aprovisionamiento de inquilino se aprobó una vez basándose en parte en una afirmación, porque la configuración del sitio no se podía leer.

Related MCP server: readonly-mcp-akamai

Solo lectura por construcción

Cada herramienta se asigna a un GET. El cliente de Aegis que esto envuelve también expone create_site, update_site, delete_site, delete_user y similares — ninguno es accesible aquí, y no se deberían añadir. El valor de este servidor es que se puede entregar a un agente sin posibilidad de cambiar el estado de producción. Un servidor mutante, si alguna vez se desea, pertenece a un despliegue separado y con autorización separada.

Herramientas

aegis_get_site y aegis_list_users aceptan un dominio además de un UUID. La API de administración direcciona los sitios solo por UUID (utils/identifiers.py resolve_site rechaza no-UUIDs), por lo que un dominio se resuelve primero a través de la búsqueda pública by-domain — los llamadores casi siempre conocen el dominio, no el UUID.

Secretos en las respuestas

Las lecturas de sitios incluyen tenant_api_key, webhook_secret y mailgun_api_key completos. Esta fue una decisión deliberada de @jmazzahacks en lugar de devolver booleanos de presencia. La consecuencia: cualquier cosa leída aquí termina en la transcripción del agente llamante, por lo que las respuestas no deben pegarse en tickets u otras superficies compartidas. AEGIS_MASTER_API_KEY abarca todos los sitios de la instancia.

Configuración

Ver example.env.

Desarrollo local

uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install -r requirements.txt

AEGIS_API_URL=https://aegis.example.com \
AEGIS_MASTER_API_KEY=... \
MCP_TRANSPORT=stdio \
python aegis_mcp_server.py

El entorno virtual reside en .venv/ en lugar de en la raíz del repositorio como hacen los repositorios hermanos de Aegis — uv venv se niega a crear uno en un directorio no vacío.

Para probarlo a través de la red como se despliega:

MCP_TRANSPORT=streamable-http FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8931 \
AEGIS_API_URL=... AEGIS_MASTER_API_KEY=... python aegis_mcp_server.py &

curl -s -X POST http://127.0.0.1:8931/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Un tools/list que tenga éxito sin un initialize previo es la señal de que el modo sin estado está activo.

Compilar y publicar

./build-publish.sh            # or --no-cache

Publica ghcr.io/jmazzahacks/byteforge-aegis-mcp:<n> y :latest, luego avanza VERSION. VERSION está en .gitignore y es propiedad exclusiva del script — nunca editarlo a mano.

A diferencia de byteforge-aegis, esta imagen no incorpora VERSION en sí misma, por lo que el orden de escritura después de la compilación del script es correcto aquí. Si alguna vez se añade un endpoint de versión, la escritura debe moverse a antes de docker build o cada imagen reportará una versión por detrás.

Despliegue

Se ejecuta detrás de un vhost paraguas mcp.<domain> con autenticación auth_request de Gatekeeper. Ver nginx-mcp-aegis.conf para el bloque de ubicación. El contenedor no publica ningún puerto del host — nginx lo alcanza por nombre de contenedor en la red docker compartida, lo cual importa porque la clave maestra hace que la exposición directa sea inaceptable.

Transporte

streamable-http con stateless_http=True. No SSE: cuando el SSE GET de larga duración de Claude Code muere, se reconecta sin volver a ejecutar initialize, el servidor ve tools/call primero, y el -32602 resultante bloquea al cliente hasta una recarga manual de /mcp. El streamable-http sin estado no tiene estado por sesión que perder, por lo que ese fallo es estructuralmente imposible.