---
url: https://next.zammad.org/pt_BR/reference/mcp-tools.md
---

# 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](/pt_BR/documentation/use/guides/mcp-server). 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](#limits) 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.
