server MCP

Panoramica

Il server MCP di Zabbix è un processo che consente agli agenti AI di lavorare con Zabbix utilizzando il Model Context Protocol (MCP). Il server MCP comunica con i client MCP e con l'API di Zabbix.

Utilizzando il server MCP, un agent AI può:

  • Recuperare gruppi di host, gruppi di template, host, template, item, regole LLD, interfacce, macro, trigger, problemi, periodi di manutenzione e dati storici degli item (ad eccezione degli item binari);
  • Eseguire aggiornamenti dei problemi: aggiungere commenti, riconoscere o annullare il riconoscimento, modificare la gravità, sopprimere o annullare la soppressione oppure chiudere i problemi;
  • Creare, aggiornare ed eliminare periodi di manutenzione.

I token API di Zabbix vengono utilizzati per l'autorizzazione; i token vengono inviati con ogni richiesta. L'accesso è limitato dalle autorizzazioni del proprietario del token: sono visibili solo i dati dei gruppi di host disponibili per tale utente e le azioni che l'utente non è autorizzato a eseguire vengono rifiutate.

Il server MCP è stateless: tra le richieste non viene mantenuta alcuna sessione.

Sebbene il server MCP di Zabbix possa funzionare con versioni precedenti o successive di Zabbix, la compatibilità è ufficialmente supportata solo con la stessa versione di Zabbix del server MCP.

Vedere anche:

Installazione

Il pacchetto ufficiale zabbix-mcp-server è disponibile nel repository Zabbix.

Per installare Zabbix MCP server dai sorgenti, compilarlo con make.

Per configurare Zabbix MCP server, aggiornare i parametri del file di configurazione del server MCP. È necessario impostare almeno i parametri FrontendURL e AllowedIP.

Il file di configurazione predefinito (zabbix_mcp_server.conf) si trova in /etc/zabbix/; nega gli strumenti che più spesso espongono dati sensibili. Per abilitare uno strumento, rimuovere la riga DenyTool corrispondente.

Vedere anche: Procedure consigliate per la sicurezza

Esecuzione

Per avviare il server MCP, eseguire:

zabbix_mcp_server -c /etc/zabbix/zabbix_mcp_server.conf

Per verificare il file di configurazione e uscire senza avviare il server, utilizzare l'opzione -T:

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

Sono supportate le seguenti opzioni della riga di comando:

Opzione Descrizione
-c <file> Il percorso del file di configurazione.
Il valore predefinito è /etc/zabbix/zabbix_mcp_server.conf.
-T Convalida il file di configurazione ed esce.
-h Visualizza le informazioni della guida.
-V Visualizza il numero di versione.

Quando il server MCP viene installato dai sorgenti, è necessario creare manualmente un'unità systemd, ad esempio:

[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

Connessione di un client MCP

Qualsiasi client MCP che supporti il trasporto HTTP Streamable può essere connesso al server MCP. Sono necessarie le seguenti impostazioni:

Impostazione Valore
Trasporto HTTP Streamable
URL https://<host>:<ListenPort>/mcp
Header Authorization: Bearer <Zabbix API token>, inviato con ogni richiesta

Ogni utente deve configurare il proprio token API.

Per verificare la configurazione, inviare una singola richiesta al server 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"}'

Il codice di stato HTTP 200 e un elenco degli strumenti disponibili nella risposta confermano che il server MCP è raggiungibile e accetta il token; l'elenco mostra quali strumenti sono esposti. Gli altri codici di stato indicano i seguenti problemi:

  • 400 - l'header Accept non include entrambi i tipi di contenuto richiesti dal trasporto;
  • 401 - manca l'header Authorization con il token;
  • 403 - l'indirizzo del client non è elencato nel parametro AllowedIP.

Approvazione e accesso agli strumenti

Se il client MCP supporta la richiesta di compilazione di moduli, ogni modifica deve essere approvata dall'utente prima di essere inviata a Zabbix. Il client MCP mostra all'utente cosa verrà modificato e la modifica viene applicata solo se l'utente la conferma; se l'utente rifiuta o ignora la richiesta, in Zabbix non viene modificato nulla. Un'approvazione è valida per cinque minuti e solo per la modifica esatta mostrata; durante questo periodo, l'approvazione può essere riutilizzata.

Se il client MCP non supporta la richiesta di compilazione di moduli (inclusi i client che supportano solo la richiesta tramite URL), le modifiche vengono applicate immediatamente, senza approvazione. In questo caso, limitare gli strumenti di scrittura e le autorizzazioni dell'API Zabbix.

L'approvazione è particolarmente importante perché l'output degli strumenti può contenere testo non attendibile proveniente dai sistemi monitorati, che potrebbe influenzare un agent.

Utilizzare AllowTool, DenyTool, AllowToolRegexp e DenyToolRegexp per controllare quali strumenti espone il server MCP. Gli strumenti negati non possono essere chiamati né elencati e non è possibile accedere alle risorse a essi associate.

Le regole AllowTool, DenyTool, AllowToolRegexp e DenyToolRegexp limitano l'accesso MCP, ma non modificano le autorizzazioni del token Zabbix. Se l'indirizzo del frontend è esposto a un agent AI, l'agent potrebbe tentare di inviare chiamate API dirette. Mantenere la posizione del frontend Zabbix e la configurazione del server MCP inaccessibili all'agent, in modo che le richieste debbano passare attraverso il server MCP e i relativi controlli di sicurezza.

Procedure consigliate per la sicurezza

Token API

L'autenticazione e l'autorizzazione sono gestite interamente da Zabbix. Il client MCP invia un token API Zabbix con ogni richiesta; il server MCP lo inoltra senza memorizzarlo né registrarlo nei log, mentre Zabbix convalida il token, applica le autorizzazioni e registra le azioni nel registro di audit.

Utilizzare un token separato, con privilegi minimi e in scadenza, per ogni agent e utente. Conservare i token in un luogo sicuro e ruotare regolarmente i token API.

Crittografia TLS

Per impedire l'invio dei token in testo non crittografato, impostare TLSAccept=cert e specificare il certificato e la chiave (TLSCertFile e TLSKeyFile), oppure eseguire il server MCP dietro un reverse proxy affidabile con terminazione TLS e impostare TLSAccept=unencrypted. HTTP non crittografato è accettabile solo in una rete affidabile.

Restrizioni di accesso

Limitare il parametro AllowedIP agli indirizzi dei client MCP attendibili e utilizzare le autorizzazioni di Zabbix per limitare le operazioni che i token API possono eseguire.

Il server MCP non fornisce la limitazione della frequenza delle richieste. Ogni richiesta MCP normalmente comporta una chiamata all'API di Zabbix, sebbene un agent in esecuzione in un ciclo possa comunque generare un carico significativo.

Protezione dei dati sensibili

Le chiavi degli item possono contenere credenziali (ad esempio negli item SSH, JMX, ODBC e HTTP agent), i valori delle macro possono contenere password e stringhe di community, le interfacce rivelano indirizzi interni e i valori degli item di tipo log o testo possono contenere qualsiasi dato. Per questo motivo, gli strumenti item_get, lld_get, interface_get, macro_get e history_get sono negati per impostazione predefinita nel file di configurazione fornito.

Per evitare l'esposizione dei valori sensibili delle macro al provider LLM dell'agent connesso, utilizzare le macro segrete; i relativi valori non vengono mai restituiti dall'API.