Tools and resources

Overview

Zabbix MCP server exposes Zabbix functionality to MCP clients as tools and resources.

Tool names describe the activity. If the ToolPrefix parameter is set, the prefix is added to every tool name; the tool access rules match the plain names listed below.

Read tools

Note that:

• host_get and template_get also return the triggers of each object (a limited set of fields), tags and linked templates. Items, discovery rules, interfaces and macros are returned by the corresponding tools.
• history_get requires a time range that is not wider than 7 days and starts no earlier than 7 days ago. The type argument must be one of float, unsigned, character, text, log or json, and must match the value type of the items; if the type is wrong, an empty result is returned, which cannot be distinguished from an item without data. The history of binary items (value type 5) cannot be retrieved through the MCP server.
• Read tools request a fixed list of fields; all fields (output: extend) are never requested.
• The results of tools that have a resource contain the uri field, so that an agent can proceed from a list to a single entity.

Response format

All read tools return the response in the same format:

{
  "results": [ ... ],
  "count": 2,
  "truncated": true,
  "truncated_by": "count",
  "limit": 2,
  "note": "The result count limit was reached ..."
}

A response is limited by the limit argument (default: 100, maximum: 1000) and by the serialized size of the response (MaxResponseSize, default: 64K). The response is stopped when either of the limits is reached. The response is truncated only between results, never inside a result, and a truncated response indicates which limit was reached. Every tool has a fixed sort order, so a truncated response is always the beginning of the full result set. Paging is not supported; to get other results, narrow the query.

Problem tools

All problem tools call event.acknowledge with the corresponding action flags. The eventids argument is required; event IDs can be retrieved with problem_get. A message (comment) can be added with any problem tool. The message argument is optional, except for problem_annotate, where it is required; if specified, the message is recorded in the same Zabbix API call.

Problems cannot be created or deleted; all problem tools update existing problems.

Maintenance tools

When a maintenance period is updated, list arguments (such as hostids, groupids and timeperiods) replace the existing values instead of adding to them. For example, if a maintenance period covers hosts A and B, and maintenance_update is called with hostids containing only host C, the maintenance period will cover only host C.

maintenance_create is the only operation that is not idempotent, and maintenance_delete is the only operation that cannot be reversed. To prevent them from being used, deny these tools with the DenyTool parameter.

Behavior of write tools

Problem and maintenance tools are write tools. They work as follows:

• The arguments are validated before any Zabbix API call; if the validation fails, the error names the constraint that was not met.
• If the client supports it, the change is applied only after it is approved by the user.
• The change is performed by Zabbix using the token of the caller. Zabbix checks the permissions and records the change in the audit log against the token owner.
• Zabbix errors, including permission errors, are returned unchanged as an error object with the code, message and data fields.
• Write tools return the Zabbix result directly; the response limits of read tools do not apply.
• Write calls are never retried by the MCP server.

Resources

Resources use the zabbix://<kind>/<id> URI scheme. Only zabbix://about is included in the resources/list response; entity IDs cannot be enumerated and are obtained from the results of tools. The resources/templates/list response lists the kinds of entities.

A resource whose corresponding tool is denied does not exist. A nonexistent entity and an entity that the token owner has no access to are both reported as resource not found; these cases are deliberately indistinguishable. The zabbix://about resource is not affected by the tool access rules.