MCP server

Descripción general

El server MCP de Zabbix es un proceso que permite a los agentes de IA trabajar con Zabbix mediante el Model Context Protocol (MCP). El server MCP se comunica con los clientes MCP y la API de Zabbix.

Mediante el server MCP, un agente de IA puede:

• Recuperar grupos de hosts, grupos de templates, hosts, templates, items, reglas LLD, interfaces, macros, triggers, problemas, períodos de mantenimiento y datos históricos de los items (excepto los items binarios);
• Realizar actualizaciones de problemas: añadir comentarios, reconocer o dejar de reconocer, cambiar la gravedad, suprimir o dejar de suprimir, o cerrar problemas;
• Crear, actualizar y eliminar períodos de mantenimiento.

Los tokens de la API de Zabbix se utilizan para la autorización; los tokens se envían con cada solicitud. El acceso está limitado por los permisos del propietario del token: solo son visibles los datos de los grupos de hosts disponibles para ese usuario, y se rechazan las acciones que el usuario no tiene permitido realizar.

El server MCP no mantiene estado: no se conserva ninguna sesión entre solicitudes.

Véase también:

• Parámetros de configuración: server MCP
• Herramientas y recursos

Instalación

El paquete oficial zabbix-mcp-server está disponible en el repositorio de Zabbix.

Para instalar Zabbix MCP server desde las fuentes, compílelo con make.

Para configurar Zabbix MCP server, actualice los parámetros del archivo de configuración del MCP server. Como mínimo, deben configurarse los parámetros FrontendURL y AllowedIP.

El archivo de configuración predeterminado (zabbix_mcp_server.conf) se encuentra en /etc/zabbix/; deniega las herramientas que con mayor frecuencia exponen datos confidenciales. Para habilitar una herramienta, elimine la línea DenyTool correspondiente.

Consulte también: Prácticas recomendadas de seguridad

Ejecución

Para iniciar el servidor MCP, ejecute:

zabbix_mcp_server -c /etc/zabbix/zabbix_mcp_server.conf

Para comprobar el archivo de configuración y salir sin iniciar el servidor, utilice la opción -T:

zabbix_mcp_server -c /etc/zabbix/zabbix_mcp_server.conf -T

Se admiten las siguientes opciones de línea de comandos:

Cuando el servidor MCP se instala desde el código fuente, se debe crear manualmente una unidad de systemd, por ejemplo:

[Unit]
Description=Zabbix MCP server
After=network-online.target

[Service]
User=zabbix
ExecStart=/usr/local/sbin/zabbix_mcp_server -c /etc/zabbix/zabbix_mcp_server.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target

Conexión de un cliente MCP

Cualquier cliente MCP compatible con el transporte HTTP transmitible puede conectarse al servidor MCP. Se requieren los siguientes ajustes:

Cada usuario debe configurar su propio token de API.

Para verificar la configuración, envíe una única solicitud al servidor MCP:

curl -sS https://mcp.example.com:8443/mcp \
  -H "Authorization: Bearer $ZABBIX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

El código de estado HTTP 200 y una lista de las herramientas disponibles en la respuesta confirman que se puede acceder al servidor MCP y que acepta el token; la lista muestra qué herramientas están expuestas. Otros códigos de estado indican los siguientes problemas:

• 400: el encabezado Accept no incluye ambos tipos de medios requeridos por el transporte;
• 401: falta el encabezado Authorization con el token;
• 403: la dirección del cliente no aparece en el parámetro AllowedIP.

Aprobación y acceso a las herramientas

Si el cliente MCP admite la solicitud de formularios, el usuario debe aprobar cada cambio antes de que se envíe a Zabbix. El cliente MCP muestra al usuario qué se cambiará, y el cambio se aplica únicamente si el usuario lo confirma; si el usuario rechaza o descarta la solicitud, no se realiza ningún cambio en Zabbix. La aprobación es válida durante cinco minutos y únicamente para el cambio exacto que se mostró; durante este tiempo, la aprobación se puede reutilizar.

Si el cliente MCP no admite la solicitud de formularios (incluidos los clientes que solo admiten la solicitud mediante URL), los cambios se aplican inmediatamente, sin aprobación. En este caso, restrinja las herramientas de escritura y los permisos de la API de Zabbix.

La aprobación es especialmente importante porque el resultado de las herramientas puede contener texto no confiable procedente de sistemas supervisados, que podría influir en un agent.

Utilice AllowTool, DenyTool, AllowToolRegexp y DenyToolRegexp para controlar qué herramientas expone el server MCP. Las herramientas denegadas no se pueden llamar ni enumerar, y no se puede acceder a los recursos asociados a ellas.

Mejores prácticas de seguridad

Tokens de API

La autenticación y la autorización son gestionadas íntegramente por Zabbix. El cliente MCP envía un token de API de Zabbix con cada solicitud; el server MCP lo reenvía sin almacenarlo ni registrarlo, mientras que Zabbix valida el token, aplica los permisos y registra las acciones en el registro de auditoría.

Utilice un token independiente, con los privilegios mínimos necesarios y con fecha de expiración, para cada agent y usuario. Almacene los tokens en una ubicación segura y rótelos periódicamente.

Cifrado TLS

Para evitar que los tokens se envíen en texto sin cifrar, establezca TLSAccept=cert y especifique el certificado y la clave (TLSCertFile y TLSKeyFile), o ejecute el servidor MCP detrás de un proxy inverso de terminación TLS de confianza y establezca TLSAccept=unencrypted. El protocolo HTTP sin cifrar solo es aceptable en una red de confianza.

Restricciones de acceso

Restrinja el parámetro AllowedIP a las direcciones de los clientes MCP de confianza y utilice los permisos de Zabbix para limitar lo que pueden hacer los tokens de API.

El servidor MCP no proporciona limitación de la tasa de solicitudes. Cada solicitud MCP normalmente da lugar a una llamada a la API de Zabbix, aunque un agent que se ejecute en un bucle aún puede generar una carga considerable.

Protección de datos confidenciales

Las claves de los item pueden contener credenciales (por ejemplo, en los item de SSH, JMX, ODBC y HTTP agent), los valores de las macros pueden contener contraseñas y cadenas de comunidad, las interfaces revelan direcciones internas y los valores de los item de registro o de texto pueden contener cualquier dato. Por este motivo, las herramientas item_get, lld_get, interface_get, macro_get y history_get están denegadas de forma predeterminada en el archivo de configuración incluido.

Para evitar que los valores confidenciales de las macros queden expuestos al proveedor de LLM del agent conectado, utilice macros secretas; sus valores nunca son devueltos por la API.