CloudOps MCP

CloudOps MCP es un servidor de solo lectura del Model Context Protocol que expone contexto operacional de infraestructura normalizado (logs, métricas, despliegues, estado) a agentes de IA a través de un pequeño conjunto de herramientas tipadas y acotadas.

Por qué existe

Un agente que investiga un incidente necesita contexto operacional: qué cambió recientemente, cómo se ve la tasa de error, qué dicen los logs. No necesita acceso sin restricciones a las APIs de la nube, y no debería ser quien decida qué constituye una causa raíz.

CloudOps MCP se sitúa entre los dos:

Cloud APIs / observability systems
        |
Provider adapters
        |
Normalized operational domain
        |
Deterministic services
        |
MCP tools
        |
AI agent

Cada capa normaliza aún más y reduce lo que el agente puede solicitar. Los adaptadores de proveedor traducen las APIs de los proveedores a un modelo de dominio compartido. Los servicios aplican límites, ordenación y agregación de manera determinista, de la misma forma para cada proveedor. Las herramientas MCP exponen eso como una superficie pequeña y tipada.

CloudOps MCP devuelve hechos operacionales, no conclusiones de causa raíz. Una herramienta puede decir "la tasa de error aumentó del 0,4% al 8% a las 14:06"; no dirá "el despliegue causó la interrupción". Ese juicio pertenece al agente, con los hechos que CloudOps MCP le entrega como evidencia.

Related MCP server: cloud-chat-assistant

Capacidades

Seis herramientas, todas de solo lectura y acotadas:

get_operational_snapshot compone los mismos servicios primitivos que usan las otras cinco herramientas, ejecutando las cuatro consultas independientes de forma concurrente. Nunca habla directamente con un proveedor y nunca falla en su conjunto porque una sección no esté disponible; cada sección reporta su propio estado.

Principios de diseño

• Solo lectura por construcción. Las interfaces de proveedor no exponen métodos de mutación. No existe ninguna ruta de código hacia una API de escritura.

• Identidad de servicio neutral respecto al proveedor. Un servicio se identifica por (service, environment). Los identificadores específicos de proveedor (un grupo de logs de CloudWatch, un nombre de objeto de Kubernetes) permanecen internos a los enlaces del proveedor y nunca forman parte del contrato público.

• Métricas canónicas y extensibles. error_rate, latency_p99 y nombres similares son nuestros, no del proveedor. La correspondencia de un nombre canónico a una métrica real reside en la configuración, por servicio. El vocabulario es abierto, no una enumeración fija.

• Consultas acotadas. Cada consulta de telemetría tiene un límite de rango de tiempo y un límite de cantidad. Un solicitante puede pedir menos; no puede pedir datos sin límite.

• Disponibilidad de datos explícita. Cada recolección reporta uno de SUCCESS, EMPTY, PARTIAL, o FAILED. Los datos faltantes nunca se tratan silenciosamente como "saludable" o "no pasó nada".

• Disponibilidad separada del resultado. NOT_CONFIGURED (ningún proveedor conectado) y EMPTY (consultado con éxito, cero coincidencias) son estados diferentes y nunca se confunden.

• Procedencia sin filtrar internos. Los resultados individuales llevan provider y source cuando un adaptador de proveedor los proporciona. La referencia interna utilizada para llamar a un proveedor nunca se copia en la salida pública.

• UTC en todas partes. Todas las marcas de tiempo son conscientes de la zona horaria y están normalizadas a UTC; las fechas y horas ingenuas se rechazan en el límite del modelo.

• Sin LLM dentro del servidor MCP. Sin resumen, sin clasificación, sin inferencia sobre el contenido de los logs. Los mensajes de log se tratan como texto opaco y no confiable.

• Sin razonamiento causal. Las herramientas reportan qué cambió y cuándo. Interpretar el por qué se deja al agente.

Inicio rápido: modo fake

El modo fake es el predeterminado y la forma principal de probar CloudOps MCP. No necesita ninguna cuenta en la nube.

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Ejecuta el servidor (transporte stdio):

python -m cloudops_mcp.server

O, si el paquete está instalado con su script de consola:

cloudops-mcp

El servidor habla MCP sobre stdio y espera un cliente al otro lado. Para probarlo directamente desde Python, usando el cliente del SDK oficial:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="python", args=["-m", "cloudops_mcp.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            result = await session.call_tool(
                "get_operational_snapshot",
                {"service": "checkout-api", "environment": "production"},
            )
            print(result.structured_content)

asyncio.run(main())

Escenarios fake

Selecciona un escenario con CLOUDOPS_MCP_SCENARIO (por defecto healthy):

CLOUDOPS_MCP_SCENARIO=bad_deploy python -m cloudops_mcp.server

bad_deploy siembra tres hechos correlacionados en marcas de tiempo fijas: un despliegue, luego un cambio en las métricas unos minutos después, luego líneas de log de timeout poco después. CloudOps MCP reporta esos tres hechos y nada más. No afirma que el despliegue causó los errores; esa inferencia se deja enteramente al agente consumidor.

Modo AWS CloudWatch

pip install -e ".[aws]"        # runtime only
pip install -e ".[dev,aws]"    # development

CLOUDOPS_MCP_MODE=aws CLOUDOPS_MCP_CONFIG=/path/to/cloudops.toml cloudops-mcp

Consulta examples/aws-cloudwatch.toml para un ejemplo completo de configuración. Solo utiliza valores de relleno; ningún ID de cuenta real, ARN o credencial debe estar en ese archivo.

Las credenciales provienen enteramente de la cadena de proveedores estándar de boto3: AWS_PROFILE, AWS_REGION / AWS_DEFAULT_REGION, credenciales de entorno, o un rol de IAM. CloudOps MCP nunca lee, almacena ni registra una clave de acceso o secreto.

Implementado en modo AWS:

• Logs: CloudWatch Logs FilterLogEvents.

• Métricas: CloudWatch GetMetricData (consultas MetricStat únicamente).

Aún no implementado: despliegues y estado respaldados por AWS. Un servicio configurado sin esas secciones simplemente reporta NOT_CONFIGURED para ellas, igual que cualquier otra capacidad no configurada. Consulta docs/aws.md para el esquema de configuración, comportamiento de paginación y limitaciones.

IAM de AWS

Política de solo lectura mínima para esta integración (cuenta y grupo de logs ficticios):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "logs:FilterLogEvents",
      "Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/checkout-api"
    },
    {
      "Effect": "Allow",
      "Action": "cloudwatch:GetMetricData",
      "Resource": "*"
    }
  ]
}

FilterLogEvents puede acotarse al ARN específico del grupo de logs. Para las consultas MetricStat que emite esta integración, GetMetricData no tiene ámbito a nivel de recurso en el modelo de autorización IAM de AWS, por lo que esa declaración usa Resource: "*". Eso es una propiedad de la API, no una elección tomada aquí.

Consultas acotadas

Cada resultado acotado reporta tanto requested_bounds como applied_bounds, para que un solicitante pueda ver exactamente qué se ajustó. Ajustar una solicitud al límite máximo no es lo mismo que PARTIAL: una consulta ajustada pero completamente satisfecha sigue siendo SUCCESS. PARTIAL significa que la extracción en sí misma está incompleta, por ejemplo, un proveedor paginó y se detuvo antes de agotar todas las coincidencias dentro de la ventana aplicada.

Semántica de disponibilidad de datos

Dos preguntas ortogonales, nunca fusionadas en una:

1. ¿Está una capacidad configurada para este servicio? (CONFIGURED / NOT_CONFIGURED)

2. Si se consultó, ¿qué sucedió? (SUCCESS / EMPTY / PARTIAL / FAILED)

Una verificación de estado para un servicio sin proveedor de estado configurado es NOT_CONFIGURED, no EMPTY ni FAILED. Una consulta de log que legítimamente no encontró nada en la ventana de tiempo es EMPTY, no FAILED. Una llamada de métricas que alcanzó un límite de tasa antes de devolver algo utilizable es FAILED con una razón, no datos vacíos silenciosos.

Salidas estructuradas de MCP

Cada herramienta toma argumentos tipados y devuelve un modelo Pydantic tipado. El SDK oficial de MCP para Python deriva structuredContent y el esquema de salida de la herramienta directamente de ese tipo de retorno; las respuestas de las herramientas son datos estructurados reales, no una cadena JSON envuelta en un bloque de texto.

Arquitectura

flowchart TD
    subgraph Providers
        Fake[Fake providers]
        AWS[AWS CloudWatch providers]
    end

    Fake --> Services
    AWS --> Services

    Registry[ServiceRegistry] --> Services

    subgraph Services[Deterministic services]
        Catalog[catalog_service]
        Health[health_service]
        Deploy[deployment_service]
        Logs[logs_service]
        Metrics[metrics_service]
        Snapshot[snapshot_service]
    end

    Snapshot --> Deploy
    Snapshot --> Logs
    Snapshot --> Metrics
    Snapshot --> Health

    Services --> Tools[MCP tools]
    Tools --> Agent[AI agent]

get_operational_snapshot compone los servicios primitivos, no los elude ni habla directamente con proveedores. Consulta docs/architecture.md para el desglose técnico completo.

Pruebas

• Escenarios fake deterministas ejercitan toda la superficie de las herramientas de extremo a extremo.

• Las pruebas a nivel de proveedor utilizan proveedores stub deliberadamente mal comportados (orden incorrecto, límites ignorados) para demostrar que la capa de servicio defiende la salida en sí misma, no solo proveedores bien comportados.

• Las pruebas del proveedor de AWS utilizan pequeños clientes stub de CloudWatch, sin llamadas reales a AWS, sin moto, sin LocalStack.

• Una prueba impulsa el cliente real del SDK de MCP contra un servidor en proceso, confirmando el límite del protocolo en sí (descubrimiento de herramientas, salida estructurada) en lugar de solo la lógica interna.

ruff check src tests
mypy src tests --strict
pytest -q

Limitaciones actuales

• La validación en vivo de AWS se ha realizado con análisis de configuración tipado, pruebas de cliente stub y el límite real del cliente/servidor MCP, aún no contra una cuenta real de AWS. Eso requiere recursos seleccionados por el usuario y no se automatiza intencionalmente: CloudOps MCP no descubre ni sondea una cuenta por sí mismo.

• Aún no hay proveedor de despliegues o estado respaldado por AWS.

• Solo transporte stdio, sin MCP remoto.

• El registro de servicios es estático y respaldado por configuración; no hay descubrimiento automático de servicios desde una cuenta en la nube.

• No hay mutación, remediación ni ruta de escritura de ningún tipo.

Hoja de ruta

• Capacidades adicionales de solo lectura en proveedores existentes.

• Un segundo proveedor real, para probar el límite de normalización contra más de un vendedor.

• Un transporte remoto, si un escenario de despliegue realmente lo necesita.

• Consumo por agentes de respuesta a incidentes, como un ejemplo de cliente MCP genérico. CloudOps MCP no está acoplado a ningún consumidor específico.

Seguridad

• No hay métodos de mutación en ninguna de las interfaces del proveedor.

• No se ejecutan comandos de shell ni llamadas a subprocesos de CLI en la nube.

• IAM con mínimo privilegio: exactamente logs:FilterLogEvents y cloudwatch:GetMetricData, nada solicitado "por si acaso".

• Solo se utiliza la cadena de credenciales estándar de AWS, sin manejo personalizado de credenciales.

• Las referencias internas del proveedor (nombres de grupos de logs, dimensiones de CloudWatch) nunca aparecen en la salida de la herramienta.

• El contenido de los logs se trata como texto no confiable y opaco: nunca se analiza, ejecuta ni interpreta.

• Los fallos inesperados se sanean en el límite de la herramienta; solo un mensaje fijo y genérico lo cruza, nunca una cadena de excepción sin procesar.

• Cada consulta de telemetría está acotada, protegiendo tanto las API del proveedor como la ventana de contexto del agente.

Licencia

MIT, consulte LICENSE.