Ferramentas do servidor MCP
O Zammad responde ao Model Context Protocol (MCP) em um servidor próprio, ao lado da API REST. Um cliente de IA, por exemplo um aplicativo de chat ou uma ferramenta de programação, lê, encontra, atualiza e cria tickets por meio dele. O servidor faz parte de toda instalação: nada precisa ser instalado ou executado além disso.
Esta página descreve as ferramentas que o servidor oferece e os limites que se aplicam a elas. Como um usuário conecta um cliente está descrito no guia do servidor MCP. Se o servidor responde ou não é uma decisão do administrador, que o ativa nas configurações de API do Zammad.
Acesso
O servidor responde em https://{fqdn}/mcp pelo transporte MCP Streamable HTTP, e apenas a requisições POST. Um cliente precisa enviar um cabeçalho fixo Authorization: Bearer {your_token} em toda requisição. Suportar só o transporte não basta: um cliente que não consegue definir o cabeçalho fica de fora.
As requisições só chegam ao servidor no Fully Qualified Domain Name, no Alternative fully qualified domain name ou em um endereço de loopback (localhost, 127.0.0.1, ::1). Requisições em outro endereço são recusadas, assim como requisições de navegador vindas de outra origem, o que protege o servidor contra DNS rebinding.
A chave MCP server vem desativada por padrão. Enquanto estiver desativada, o servidor recusa toda requisição, seja qual for o token que ela traga. Os clientes se autenticam apenas com tokens de acesso pessoal: nem senha nem token OAuth2 entram, nem uma requisição agindo em nome de outro usuário. O token e o dono dele mantêm seus limites, então um cliente pode fazer exatamente o que eles podem fazer, e nada além disso. Toda ferramenta exige a permissão ticket.agent, e um usuário sem permissão de agente, um cliente por exemplo, não recebe nenhuma ferramenta.
Ferramentas
O cliente recebe as ferramentas a seguir, na ordem que ele mesmo decidir. A coluna de acesso indica o que uma ferramenta faz com os dados: read não altera nada, write altera um ticket.
| Ferramenta | Acesso | O que faz |
|---|---|---|
add_internal_note | write | Adiciona uma nota interna a um ticket. O cliente nunca a vê. |
create_article | write | Adiciona um artigo a um ticket ou envia uma resposta ao cliente. |
create_ticket | write | Cria um ticket com uma primeira mensagem de uma ligação telefônica ou de um email, ou como nota interna. |
get_current_user | read | Lê o usuário com que a conexão trabalha, com os grupos e o acesso à base de conhecimento dele. |
get_knowledge_base_answer | read | Lê uma resposta da base de conhecimento por completo, no idioma pedido. |
get_organization | read | Lê uma organização com o domínio, a marcação VIP, a observação, os campos personalizados e os membros dela. |
get_overview_tickets | read | Lê os tickets de uma visão geral, como "My Assigned Tickets". |
get_shared_draft | read | Lê o rascunho compartilhado salvo para um ticket. |
get_ticket | read | Lê um ticket com o cliente, a organização, o responsável, os vínculos e as mensagens dele. |
get_ticket_articles | read | Lê as mensagens de um ticket: um índice, uma pesquisa nelas ou as escolhidas, com o texto. |
get_ticket_fields | read | Lista os campos de um ticket, com os valores disponíveis para escolha. |
get_ticket_history | read | Lê o que mudou em um ticket, quando e por quem ou por qual automação. |
get_user | read | Lê um usuário com email, telefone, celular, organizações e campos personalizados. |
link_knowledge_base_answer | write | Vincula uma resposta da base de conhecimento a um ticket. |
link_tickets | write | Vincula dois tickets. |
list_overviews | read | Lista as visões gerais com a quantidade de tickets de cada uma. |
list_tags | read | Lista as tags existentes, as mais usadas primeiro. |
read_attachment | read | Lê o texto de um arquivo anexado a uma mensagem de ticket. Veja Limites para saber quais arquivos ela lê. |
save_shared_draft | write | Salva uma resposta como rascunho compartilhado de um ticket. Nada é enviado. |
search_knowledge_base | read | Pesquisa a base de conhecimento por palavras ou por significado. |
search_organizations | read | Encontra organizações pelo nome ou pelo domínio. |
search_tickets | read | Pesquisa tickets por uma consulta, por filtros ou pelos dois. |
search_users | read | Encontra usuários por nome, email, login ou número de telefone. |
send_shared_draft | write | Envia o rascunho compartilhado de um ticket como está salvo. |
set_ticket_tags | write | Adiciona tags a um ticket e remove tags dele. |
update_ticket | write | Altera o estado, a prioridade, o grupo, o responsável, o horário de pendência ou os campos personalizados de um ticket. |
As três ferramentas da base de conhecimento, get_knowledge_base_answer, link_knowledge_base_answer e search_knowledge_base, só aparecem onde há uma base de conhecimento ativa.
Limites
Uma ferramenta lê o texto de um arquivo de texto: texto simples, logs, CSV, JSON, XML ou HTML, de até 10 MB. Qualquer outro arquivo, e um maior que isso, não é lido. A ferramenta então informa o motivo e devolve o link de download do arquivo, para que o cliente possa repassar o link ao usuário. Um texto longo chega em partes, uma parte por chamada.
Não é possível enviar arquivos pelo servidor. create_article e create_ticket aceitam apenas texto; um usuário que queira enviar um arquivo o adiciona à mensagem no próprio Zammad.
Quais mensagens um cliente envia sem aprovação adicional, e quando o Zammad pede uma ao usuário, está descrito na documentação de administração das configurações de API.