From e4527b818a5f59893b4d19482fbe02b79bef94ca Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Wed, 11 Nov 2026 12:56:33 +0100 Subject: [PATCH] Fixes admin-1372 - Add the MCP server tool reference The tool list moves out of the admin API settings page into the system documentation, next to the REST API. It names the access of each tool and the limits that apply, verified against Service::AI::Tool::Runtime::Router and Service::AI::Tool::ReadAttachment on develop (298de2efad). Relates to zammad/zammad-admin-documentation#1372 --- api/mcp.rst | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++ index.rst | 8 +++ 2 files changed, 161 insertions(+) create mode 100644 api/mcp.rst diff --git a/api/mcp.rst b/api/mcp.rst new file mode 100644 index 00000000..6138b15f --- /dev/null +++ b/api/mcp.rst @@ -0,0 +1,153 @@ +MCP Server +========== + +Zammad answers the *Model Context Protocol* (MCP) on a server of its own, next +to the REST API. An AI client, a chat application or a coding tool for example, +reads, finds, updates and creates tickets through it. The server is part of +every installation, nothing has to be installed or run in addition. + +This page describes the tools the server offers and the limits that apply to +them. Switching the server on and the tokens it accepts are described in the +:admin-docs:`API settings `, connecting a client in the +:user-docs:`user documentation `. + +Access +------ + +The server answers at ``https://{fqdn}/mcp`` over the MCP transport +*Streamable HTTP*, and only to ``POST`` requests. A client has to send a fixed +``Authorization: Bearer {your_token}`` header with every request. Supporting the +transport alone is not enough, a client that cannot set the header stays out. + +Requests reach the server only at the **Fully Qualified Domain Name**, the +**Alternative fully qualified domain name** or a loopback address +(``localhost``, ``127.0.0.1``, ``::1``). Requests at another address are +refused, as are browser requests from another origin, which protects the +server against DNS rebinding. + +The **MCP server** toggle is off by default. While it is off the server refuses +every request, whatever token the request carries. Clients authenticate with +personal access tokens only: neither a password nor an OAuth2 token gets in, +and neither does a request acting on behalf of another user. The token and its +owner both keep their limits, so a client can do exactly what they may do and +nothing more. Every tool requires the ``ticket.agent`` permission, and a user +without agent permissions, a customer for example, gets no tools at all. + +Tools +----- + +The client gets the following tools, in an order it decides itself. The access +column names what a tool does with the data: ``read`` changes nothing, +``write`` changes a ticket. + +.. list-table:: + :widths: 30 8 62 + :header-rows: 1 + + * - Tool + - Access + - What it does + * - ``add_internal_note`` + - write + - Adds an internal note to a ticket. The customer never sees it. + * - ``create_article`` + - write + - Adds an article to a ticket or sends a reply to the customer. + * - ``create_ticket`` + - write + - Creates a ticket with a first message from a phone call or an email, or + as an internal note. + * - ``get_current_user`` + - read + - Reads the user the connection works as, with their groups and their + knowledge base access. + * - ``get_knowledge_base_answer`` + - read + - Reads one knowledge base answer in full, in the locale asked for. + * - ``get_organization`` + - read + - Reads an organization with its domain, VIP flag, note, custom fields and + members. + * - ``get_overview_tickets`` + - read + - Reads the tickets of an overview, such as "My Assigned Tickets". + * - ``get_shared_draft`` + - read + - Reads the shared draft saved for a ticket. + * - ``get_ticket`` + - read + - Reads a ticket with its customer, organization, owner, links and + messages. + * - ``get_ticket_articles`` + - read + - Reads the messages of a ticket: an index, a search in them or chosen + ones with their text. + * - ``get_ticket_fields`` + - read + - Lists the fields a ticket has, with the values to choose from. + * - ``get_ticket_history`` + - read + - Reads what changed on a ticket, when and by whom or by which automation. + * - ``get_user`` + - read + - Reads a user with email, phone, mobile, organizations and custom fields. + * - ``link_knowledge_base_answer`` + - write + - Links a knowledge base answer to a ticket. + * - ``link_tickets`` + - write + - Links two tickets. + * - ``list_overviews`` + - read + - Lists the overviews with their number of tickets. + * - ``list_tags`` + - read + - Lists the tags that exist, the most used first. + * - ``read_attachment`` + - read + - Reads the text of a file attached to a ticket message. See + `Limits`_ for which files it reads. + * - ``save_shared_draft`` + - write + - Saves a reply as the shared draft of a ticket. Nothing is sent. + * - ``search_knowledge_base`` + - read + - Searches the knowledge base by words or by meaning. + * - ``search_organizations`` + - read + - Finds organizations by their name or their domain. + * - ``search_tickets`` + - read + - Searches tickets by a query, by filters or both. + * - ``search_users`` + - read + - Finds users by name, email, login or phone number. + * - ``send_shared_draft`` + - write + - Sends the shared draft of a ticket as it is saved. + * - ``set_ticket_tags`` + - write + - Adds tags to a ticket and removes tags from it. + * - ``update_ticket`` + - write + - Changes state, priority, group, owner, pending time or custom fields of + a ticket. + +The three knowledge base tools, ``get_knowledge_base_answer``, +``link_knowledge_base_answer`` and ``search_knowledge_base``, appear only +where a knowledge base is active. + +Limits +------ + +A tool reads the text of a text file: plain text, logs, CSV, JSON, XML or +HTML, up to 10 MB. Any other file, and a larger one, is not read. The tool then +says why and returns the file's download link, so the client can hand the link +to the user. A long text arrives in parts, one part per call. + +Files cannot be sent through the server. ``create_article`` and +``create_ticket`` take text only, a user who wants to send a file adds it to +the message in Zammad itself. + +Which messages a client sends without a further approval is described in the +:admin-docs:`API settings `. diff --git a/index.rst b/index.rst index 8ff1647c..c03ac61f 100644 --- a/index.rst +++ b/index.rst @@ -92,6 +92,14 @@ Zammad System Documentation /api/webhook +.. toctree:: + :maxdepth: 2 + :glob: + :caption: MCP Server + + /api/mcp + + .. toctree:: :maxdepth: 2 :glob: