Herramientas y recursos

Descripción general

El server MCP de Zabbix expone la funcionalidad de Zabbix a los clientes MCP como tools y resources.

Los nombres de las tools describen la actividad. Si se establece el parámetro ToolPrefix, el prefijo se añade a cada nombre de tool; las reglas de acceso a las tools coinciden con los nombres simples que se indican a continuación.

Herramientas de lectura

Tenga en cuenta lo siguiente:

• host_get y template_get también devuelven los triggers de cada objeto (un conjunto limitado de campos), las etiquetas y los templates vinculados. Los items, las reglas de descubrimiento, las interfaces y las macros se devuelven mediante las herramientas correspondientes.
• history_get requiere un intervalo de tiempo no superior a 7 días y cuyo inicio no sea anterior a hace 7 días. El argumento type debe ser uno de float, unsigned, character, text, log o json, y debe coincidir con el tipo de valor de los items; si el tipo es incorrecto, se devuelve un resultado vacío, que no puede distinguirse de un item sin datos. El historial de los items binarios (tipo de valor 5) no se puede recuperar mediante el servidor MCP.
• Las herramientas de lectura solicitan una lista fija de campos; nunca se solicitan todos los campos (output: extend).
• Los resultados de las herramientas que tienen un recurso contienen el campo uri, de modo que un agent puede pasar de una lista a una entidad individual.

Formato de respuesta

Todas las herramientas de lectura devuelven la respuesta en el mismo formato:

{
  "results": [ ... ],
  "count": 2,
  "truncated": true,
  "truncated_by": "count",
  "limit": 2,
  "note": "Se alcanzó el límite de cantidad de resultados ..."
}

La respuesta está limitada por el argumento limit (valor predeterminado: 100, máximo: 1000) y por el tamaño serializado de la respuesta (MaxResponseSize, valor predeterminado: 64K). La respuesta se detiene cuando se alcanza cualquiera de los límites. La respuesta se trunca únicamente entre resultados, nunca dentro de un resultado, y una respuesta truncada indica qué límite se alcanzó. Cada herramienta tiene un orden de clasificación fijo, por lo que una respuesta truncada siempre contiene el principio del conjunto completo de resultados. No se admite la paginación; para obtener otros resultados, limite la consulta.

Herramientas de problemas

Todas las herramientas de problemas llaman a event.acknowledge con las marcas de acción correspondientes.
El argumento eventids es obligatorio; los ID de evento se pueden obtener con problem_get.
Se puede añadir un mensaje (comentario) con cualquier herramienta de problemas.
El argumento message es opcional, excepto para problem_annotate, donde es obligatorio; si se especifica, el mensaje se registra en la misma llamada a la API de Zabbix.

No se pueden crear ni eliminar problemas; todas las herramientas de problemas actualizan problemas existentes.

Herramientas de mantenimiento

Cuando se actualiza un período de mantenimiento, los argumentos de tipo lista (como hostids, groupids y timeperiods) reemplazan los valores existentes en lugar de añadirse a ellos. Por ejemplo, si un período de mantenimiento incluye los hosts A y B, y se llama a maintenance_update con hostids que contiene únicamente el host C, el período de mantenimiento incluirá solo el host C.

maintenance_create es la única operación que no es idempotente, y maintenance_delete es la única operación que no se puede revertir. Para impedir su uso, deniegue estas herramientas mediante el parámetro DenyTool.

Comportamiento de las herramientas de escritura

Las herramientas de problemas y mantenimiento son herramientas de escritura. Funcionan de la siguiente manera:

• Los argumentos se validan antes de realizar cualquier llamada a la API de Zabbix; si la validación falla, el error indica la restricción que no se cumplió.
• Si el cliente lo admite, el cambio se aplica únicamente después de que el usuario lo apruebe.
• Zabbix realiza el cambio utilizando el token del autor de la llamada. Zabbix comprueba los permisos y registra el cambio en el registro de auditoría asociado al propietario del token.
• Los errores de Zabbix, incluidos los errores de permisos, se devuelven sin modificar como un objeto de error con los campos code, message y data.
• Las herramientas de escritura devuelven directamente el resultado de Zabbix; los límites de respuesta de las herramientas de lectura no se aplican.
• El servidor MCP nunca vuelve a intentar las llamadas de escritura.

Recursos

Los recursos utilizan el esquema de URI zabbix://<kind>/<id>. Solo zabbix://about se incluye en la respuesta de resources/list; los ID de las entidades no se pueden enumerar y se obtienen de los resultados de las herramientas. La respuesta de resources/templates/list muestra los tipos de entidades.

Un recurso cuya herramienta correspondiente está denegada no existe. Tanto una entidad inexistente como una entidad a la que el propietario del token no tiene acceso se notifican como resource not found; estos casos son deliberadamente indistinguibles. El recurso zabbix://about no se ve afectado por las reglas de acceso a las herramientas.