MCP server

Visão geral

O MCP server do Zabbix é um processo que permite que agentes de IA trabalhem com o Zabbix usando o Model Context Protocol (MCP). O MCP server se comunica com clientes MCP e com a API do Zabbix.

Usando o MCP server, um agente de IA pode:

  • Recuperar grupos de hosts, grupos de templates, hosts, templates, itens, regras de LLD, interfaces, macros, triggers, problemas, períodos de manutenção e dados históricos de itens (exceto itens binários);
  • Executar atualizações de problemas: adicionar comentários, reconhecer ou cancelar o reconhecimento, alterar a severidade, suprimir ou cancelar a supressão ou fechar problemas;
  • Criar, atualizar e excluir períodos de manutenção.

Os tokens da API do Zabbix são usados para autorização; os tokens são enviados com cada solicitação. O acesso é limitado pelas permissões do proprietário do token: somente os dados dos grupos de hosts disponíveis para esse usuário ficam visíveis, e as ações que o usuário não tem permissão para executar são rejeitadas.

O MCP server não mantém estado: nenhuma sessão é mantida entre as solicitações.

Embora o MCP server do Zabbix possa funcionar com versões mais antigas ou mais recentes do Zabbix, a compatibilidade é oficialmente suportada somente com a mesma versão do Zabbix do próprio MCP server.

Veja também:

Instalação

O pacote oficial do zabbix-mcp-server está disponível no repositório do Zabbix.

Para instalar o Zabbix MCP server a partir do código-fonte, compile-o com make.

Para configurar o Zabbix MCP server, atualize os parâmetros do arquivo de configuração do MCP server. Pelo menos os parâmetros FrontendURL e AllowedIP devem ser definidos.

O arquivo de configuração padrão (zabbix_mcp_server.conf) está localizado em /etc/zabbix/; ele nega as ferramentas que mais frequentemente expõem dados confidenciais. Para habilitar uma ferramenta, remova a linha DenyTool correspondente.

Consulte também: Práticas recomendadas de segurança

Execução

Para iniciar o servidor MCP, execute:

zabbix_mcp_server -c /etc/zabbix/zabbix_mcp_server.conf

Para verificar o arquivo de configuração e sair sem iniciar o servidor, use a opção -T:

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

As seguintes opções de linha de comando são compatíveis:

Opção Descrição
-c <file> O caminho para o arquivo de configuração.
O padrão é /etc/zabbix/zabbix_mcp_server.conf.
-T Valida o arquivo de configuração e sai.
-h Exibe informações de ajuda.
-V Exibe o número da versão.

Quando o servidor MCP é instalado a partir do código-fonte, uma unidade do systemd deve ser criada manualmente, por exemplo:

[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

Conectando um cliente MCP

Qualquer cliente MCP que ofereça suporte ao transporte HTTP Streamable pode ser conectado ao servidor MCP. As seguintes configurações são necessárias:

Configuração Valor
Transporte HTTP Streamable
URL https://<host>:<ListenPort>/mcp
Cabeçalho Authorization: Bearer <Zabbix API token>, enviado com cada solicitação

Cada usuário deve configurar seu próprio token de API.

Para verificar a configuração, envie uma única solicitação ao 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"}'

O código de status HTTP 200 e uma lista das ferramentas disponíveis na resposta confirmam que o servidor MCP está acessível e aceita o token; a lista mostra quais ferramentas estão expostas. Outros códigos de status indicam os seguintes problemas:

  • 400 - o cabeçalho Accept não inclui os dois tipos de mídia exigidos pelo transporte;
  • 401 - o cabeçalho Authorization com o token está ausente;
  • 403 - o endereço do cliente não está listado no parâmetro AllowedIP.

Aprovação e acesso às ferramentas

Se o cliente MCP for compatível com elicitação de formulários, toda alteração deverá ser aprovada pelo usuário antes de ser enviada ao Zabbix. O cliente MCP mostra ao usuário o que será alterado, e a alteração é aplicada somente se o usuário a confirmar; se o usuário rejeitar ou dispensar a solicitação, nada será alterado no Zabbix. Uma aprovação é válida por cinco minutos e somente para a alteração exata que foi exibida; dentro desse período, a aprovação pode ser reutilizada.

Se o cliente MCP não for compatível com elicitação de formulários (incluindo clientes compatíveis apenas com elicitação por URL), as alterações serão aplicadas imediatamente, sem aprovação. Nesse caso, restrinja as ferramentas de gravação e as permissões da API do Zabbix.

A aprovação é particularmente importante porque a saída das ferramentas pode conter texto não confiável proveniente de sistemas monitorados, que pode influenciar um agent.

Use AllowTool, DenyTool, AllowToolRegexp e DenyToolRegexp para controlar quais ferramentas o servidor MCP expõe. As ferramentas negadas não podem ser chamadas nem listadas, e os recursos associados a elas não podem ser acessados.

As regras AllowTool, DenyTool, AllowToolRegexp e DenyToolRegexp limitam o acesso ao MCP, mas não alteram as permissões do token do Zabbix. Se o endereço do frontend for exposto a um agent de IA, o agent poderá tentar enviar chamadas diretas à API. Mantenha o local do frontend do Zabbix e a configuração do servidor MCP inacessíveis ao agent, para que as solicitações precisem passar pelo servidor MCP e por seus controles de segurança.

Práticas recomendadas de segurança

Tokens de API

A autenticação e a autorização são gerenciadas inteiramente pelo Zabbix. O cliente MCP envia um token da API do Zabbix com cada solicitação; o MCP server o encaminha sem armazená-lo ou registrá-lo em logs, enquanto o Zabbix valida o token, aplica as permissões e registra as ações no log de auditoria.

Use um token separado, com o mínimo de privilégios e com expiração, para cada agent e usuário. Armazene os tokens em um local seguro e alterne os tokens da API regularmente.

Criptografia TLS

Para evitar que os tokens sejam enviados em texto não criptografado, defina TLSAccept=cert e especifique o certificado e a chave (TLSCertFile e TLSKeyFile) ou execute o MCP server atrás de um proxy reverso confiável que encerre o TLS e defina TLSAccept=unencrypted. HTTP não criptografado é aceitável somente em uma rede confiável.

Restrições de acesso

Restrinja o parâmetro AllowedIP aos endereços de clientes MCP confiáveis e use as permissões do Zabbix para limitar o que os tokens de API podem fazer.

O MCP server não fornece limitação da taxa de solicitações. Cada solicitação MCP normalmente resulta em uma chamada à API do Zabbix, embora um agent em execução em um loop ainda possa gerar uma carga significativa.

Proteção de dados confidenciais

As chaves de item podem conter credenciais (por exemplo, em itens SSH, JMX, ODBC e HTTP agent), os valores de macro podem conter senhas e strings de comunidade, as interfaces revelam endereços internos e os valores de itens de log ou de texto podem conter quaisquer dados. Por esse motivo, as ferramentas item_get, lld_get, interface_get, macro_get e history_get são negadas por padrão no arquivo de configuração fornecido.

Para evitar a exposição de valores de macros confidenciais ao provedor de LLM do agent conectado, use macros secretas; seus valores nunca são retornados pela API.