MCP-Server-Werkzeuge
Zammad unterstützt das Model Context Protocol (MCP) auf dem eigenen Server, zusätzlich zur REST-API. Ein KI-Client, eine Chat-Anwendung oder beispielsweise ein Programmierwerkzeug kann über diese Schnittstelle Tickets lesen, suchen, aktualisieren und erstellen. Der Server ist Bestandteil jeder Installation, keine zusätzliche Installation ist notwendig.
Auf dieser Seite werden die vom Server bereitgestellten Werkzeuge sowie deren Einschränkungen beschrieben. Wie ein Benutzer einen Client verbindet, wird im MCP-Server-Leitfaden beschrieben. Ob der Server überhaupt antwortet, entscheidet der Administrator, der diese Funktion in den API-Einstellungen von Zammad aktiviert.
Zugriff
Der Server antwortet unter https://{fqdn}/mcp per MCP-Transport Streamable HTTP sowie ausschließlich auf POST -Anfragen. Ein Client muss bei jeder Anfrage einen festen Authorization: Bearer {ihr_token} Header senden. Die bloße Unterstützung des Transports reicht nicht aus. Ein Client, der den Header nicht setzen kann, wird nicht unterstützt.
Anfragen erreichen den Server ausschließlich unter dem vollqualifizierten Domainnamen, dem alternativen vollqualifizierten Domainnamen oder einer Loopback-Adresse (localhost, 127.0.0.1, ::1). Anfragen an eine andere Adresse werden ebenso abgelehnt wie Browseranfragen mit anderer Herkunft, wodurch der Server vor DNS-Rebinding geschützt wird.
Der Schalter MCP-Server ist standardmäßig deaktiviert. Solange er deaktiviert ist, lehnt der Server jede Anfrage ab, unabhängig davon, welches Token die Anfrage enthält. Clients authentifizieren sich ausschließlich mit persönlichen Zugangs-Token: Weder ein Passwort noch ein OAuth2-Token werden akzeptiert, ebenso wenig wie eine Anfrage, die im Namen eines anderen Benutzers erfolgt. Sowohl das Token als auch sein Besitzer behalten ihre jeweiligen Berechtigungen bei, sodass ein Client genau das tun kann, wozu er berechtigt ist, nichts darüber hinaus. Jedes Werkzeug erfordert die Berechtigung ticket.agent und Benutzer ohne Agenten-Berechtigungen (z.B. Kunden) haben überhaupt keinen Zugriff auf diese Werkzeuge.
Werkzeuge
Der Client erhält die folgenden Werkzeuge in einer von ihm selbst festgelegten Reihenfolge. Die Spalte Zugriff gibt an, was ein Werkzeug mit den Daten tun kann: read ändert nichts, write ändert ein Ticket.
| Werkzeug | Zugriff | Funktion |
|---|---|---|
add_internal_note | write | Fügt einem Ticket eine interne Notiz hinzu. Der Kunde sieht sie nie. |
create_article | write | Fügt einem Ticket einen Artikel hinzu oder sendet dem Kunden eine Antwort. |
create_ticket | write | Erstellt ein Ticket mit einer ersten Nachricht aus einem Telefonat oder einer E-Mail, oder als interne Notiz. |
get_current_user | read | Liest den Benutzer, mit dem die Verbindung arbeitet, mit seinen Gruppen und seinem Knowledge-Base-Zugriff. |
get_knowledge_base_answer | read | Liest eine Antwort der Knowledge Base vollständig, in der angefragten Sprache. |
get_organization | read | Liest eine Organisation mit ihrer Domain, dem VIP-Kennzeichen, der Notiz, den benutzerdefinierten Feldern und den Mitgliedern. |
get_overview_tickets | read | Liest die Tickets einer Übersicht, etwa "Meine zugewiesenen Tickets". |
get_shared_draft | read | Liest den für ein Ticket gespeicherten gemeinsamen Entwurf. |
get_ticket | read | Liest ein Ticket mit seinem Kunden, seiner Organisation, seinem Besitzer, seinen Verknüpfungen und seinen Nachrichten. |
get_ticket_articles | read | Liest die Nachrichten eines Tickets: eine Liste, eine Suche darin oder ausgewählte mit ihrem Text. |
get_ticket_fields | read | Listet die Felder eines Tickets mit den Werten zur Auswahl auf. |
get_ticket_history | read | Liest, was sich an einem Ticket geändert hat, wann und durch wen oder welche Automatisierung. |
get_user | read | Liest einen Benutzer mit E-Mail, Telefon, Mobiltelefon, Organisationen und benutzerdefinierten Feldern. |
link_knowledge_base_answer | write | Verknüpft eine Antwort der Knowledge Base mit einem Ticket. |
link_tickets | write | Verknüpft zwei Tickets. |
list_overviews | read | Listet die Übersichten mit ihrer Anzahl an Tickets auf. |
list_tags | read | Listet die vorhandenen Tags auf, die meistgenutzten zuerst. |
read_attachment | read | Liest den Text einer an eine Ticket-Nachricht angehängten Datei. Welche Dateien gelesen werden, steht unter Einschränkungen. |
save_shared_draft | write | Speichert eine Antwort als gemeinsamen Entwurf eines Tickets. Es wird nichts versendet. |
search_knowledge_base | read | Durchsucht die Knowledge Base nach Wörtern oder nach Bedeutung. |
search_organizations | read | Findet Organisationen anhand ihres Namens oder ihrer Domain. |
search_tickets | read | Durchsucht Tickets anhand einer Abfrage, anhand von Filtern oder beidem. |
search_users | read | Findet Benutzer anhand von Name, E-Mail, Login oder Telefonnummer. |
send_shared_draft | write | Sendet den gemeinsamen Entwurf eines Tickets so, wie er gespeichert ist. |
set_ticket_tags | write | Fügt einem Ticket Tags hinzu und entfernt Tags daraus. |
update_ticket | write | Ändert Status, Priorität, Gruppe, Besitzer, Wartezeit oder benutzerdefinierte Felder eines Tickets. |
Die drei Knowledge-Base-Werkzeuge get_knowledge_base_answer, link_knowledge_base_answer und search_knowledge_base erscheinen nur, wo eine Knowledge Base aktiv ist.
Einschränkungen
Ein Werkzeug liest den Text einer Textdatei: Klartext, Protokolle, CSV, JSON, XML oder HTML, bis 10 MB. Jede andere Datei und jede größere wird nicht gelesen. Das Werkzeug nennt dann den Grund und gibt den Download-Link der Datei zurück, damit der Client den Link an den Benutzer weitergeben kann. Ein langer Text kommt in Teilen an, ein Teil pro Aufruf.
Dateien können nicht über den Server gesendet werden. create_article und create_ticket nehmen nur Text an, wer eine Datei senden möchte, fügt sie der Nachricht in Zammad selbst hinzu.
Welche Nachrichten ein Client ohne weitere Genehmigung sendet und wann Zammad den Benutzer um eine solche bittet, ist in der Admin-Dokumentation der API-Einstellungen beschrieben.