OTRS can act as a MCP server, allowing AI agents (such as Claude Desktop or Claude Code) to interact with OTRS through a defined set of tools: searching, reading, and updating tickets, FAQ articles, and configuration items, while respecting OTRS ACLs, dynamic fields, and user permissions.
An MCP server is added the same way as any other Web Services operation: add an operation to a web service and choose MCP::Handler as its backend.

Warning
An MCP tool call runs with exactly the permissions of the agent or customer user behind it, but without the pause a person has before clicking the same action by hand. See Security Considerations below before enabling this in production.
Enabling the MCP Server
Before an MCP operation can be used, it must be enabled in system configuration (System Configuration):
Important
MCP access also requires that your OTRS contract includes the MCP feature. This is independent of the settings below and cannot be configured locally; without it, requests are rejected with error code -32000 regardless of MCP::Enabled. Contact your OTRS account manager if this tool is not available on your system.
- MCP::Enabled
-
Enables or disables the MCP server. Disabled by default. While disabled, MCP requests are rejected with error code
-32003. - MCP::AllowedUserGroups
-
Comma-separated list of agent groups allowed to use the MCP server (default:
mcp_users). Leave empty to allow all authenticated agents.Important
mcp_usersis only the default value of this setting, OTRS does not create this group automatically. Create it under Groups and assign the relevant agents or service accounts to it (Agents ↔ Groups), or point this setting at an existing group instead. - MCP::ToolRegistry::CacheTTL
-
Cache time, in seconds, for the list of available tools and their schemas (default:
3600). - MCP::Protocol::SkipInitCheck
-
When enabled (default), tool and resource calls are accepted without a prior
initializecall. Keep this enabled for stateless clients such as Claude Desktop.
MCP Operation Settings
An MCP operation shares the common operation fields described in Web Services (Name, Description, Mapping for incoming/outgoing data), plus the following MCP-specific fields:
- Allowed Tools
-
Restricts which tools this operation exposes. Choose individual tools or entire groups (
ticket,faq,lookup,cmdb,link). Leave empty to expose every available tool, see Available Tools below. - Allowed Groups
-
Restricts which agent groups may use this specific MCP operation, overriding
MCP::AllowedUserGroupsfor this operation only. Leave empty to fall back to the global setting. - Allowed Dynamic Fields
-
Restricts which ticket dynamic fields this operation may discover, read, and write. Leave empty to allow every valid ticket dynamic field, the same as leaving Allowed Tools empty exposes every tool.
This can only narrow what a customer user already sees: a dynamic field hidden from customers by the Ticket Create screen’s dynamic field configuration (Dynamic Fields) stays hidden from customer MCP callers even if it is included here.
- Allow Impersonation / Impersonation Group
-
Only shown when
GenericInterface::Operation::Impersonationis enabled globally. Behaves the same way as impersonation on other operation types: a privileged agent (or service account) can act as another agent, with all tool calls, ticket ownership, and history entries attributed to the impersonated user.Note
Impersonating a customer user can additionally be bound to a short-lived, OTRS-issued identity token, sent in the
X-Identity-Tokenheader, whose verified subject must match the requested customer. This check is controlled by theRequireIdentityTokensetting on the web service (set it by editing the web service’s YAML configuration, see Web Services), and it is off by default. While off, customer impersonation is allowed with the service credential alone, no identity token required. EnableRequireIdentityTokenfor web services exposed to third parties that verify customer identity independently; leave it off for trusted first-party integrations or deployments where OTRS does not issue identity tokens.
Available Tools
The MCP server exposes a set of tools, grouped by domain below. Tool schemas are generated dynamically, any dynamic field configured on tickets (see Dynamic Fields) automatically appears as a parameter on the relevant ticket tools.
Ticket Tools
- search_tickets
-
Search tickets by queue, state, priority, customer user, owner, full text, or creation date.
- get_ticket
-
Get full ticket details, including articles and dynamic field values.
- get_ticket_history
-
Get a ticket’s change history (state changes, queue moves, owner changes, article additions).
- get_ticket_acl
-
Get the ACL-valid values for a ticket’s Queue, State, or Priority field in its current context, see Access Control Lists (ACL).
- create_ticket
-
Create a new ticket with an initial article. Requires a queue (Queues), state (States), and priority (Priorities); accepts optional service/SLA (Services) and dynamic field values.
- update_ticket
-
Update an existing ticket’s queue, state, priority, title, owner, or dynamic field values.
- add_note
-
Add an internal note or a customer-visible reply to a ticket.
- close_ticket
-
Close a ticket, optionally with a closing note and a specific close state.
All write tools (create_ticket, update_ticket, add_note, close_ticket) pre-validate Queue, State, and Priority values against ACLs before executing, and return a descriptive error instead of silently failing or writing an invalid value. Every tool also advertises risk metadata (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can apply their own approval policy; see Untrusted Content.
A dynamic field value outside what Allowed Dynamic Fields (see MCP Operation Settings above) permits is handled differently depending on the tool: create_ticket rejects the whole call and creates no ticket, while update_ticket still applies the rest of the update and reports the rejected field as a warning in its response, since the ticket already exists and there is nothing to undo.
FAQ Tools
- search_faq
-
Search FAQ articles by text, category, or language.
- get_faq
-
Get the full content of a FAQ article.
See also
FAQ Category and FAQ Language for managing the categories and languages these tools search against.
CMDB / Configuration Item Tools
- search_config_items
-
Search configuration items by name, class, deployment state, incident state, or CI number, see Configuration Items.
- get_config_item
-
Get full details of a configuration item, including version data and all class-defined attributes.
- list_config_item_classes
-
List available configuration item classes.
Lookup Tools
- list_queues
-
List available queues, see Queues.
- list_states
-
List available ticket states, see States.
- list_priorities
-
List available ticket priorities, see Priorities.
- list_services
-
List available services, see Services.
- list_agents
-
Search agents by name, login, or email; without a search term, lists all valid agents, see Agents.
- search_customer_users
-
Search customer users (contacts) by name, email, or login, see Customer Users.
Link Management Tools
- link_objects
-
Create a link between two objects (for example, a ticket and a configuration item).
- unlink_objects
-
Remove a link between two objects.
- get_ticket_links
-
List all objects linked to a ticket.
MCP Client Authentication
The MCP endpoint for a web service named OTRS-MCP is:
POST /otrs/nph-genericinterface.pl/Webservice/OTRS-MCP/Handler
MCP clients authenticate like any other Generic Interface request, using one of the following (checked in this order):
-
API key (recommended for AI agents), sent as an
X-API-Keyheader. Create and manage keys under Credentials. -
Access token, sent as an
Authorization: Bearerheader. -
Agent login and password, sent as an
Authorization: Basicheader, or asUserLogin/Passwordin the request body. -
Customer user login and password, sent as
CustomerUserLogin/Passwordin the request body.
Customer User Access
Customer users connecting via MCP only get access to a restricted subset of tools, scoped to their own tickets and company, and are subject to rate limiting.
Customers can use the following tools: search_tickets, get_ticket, create_ticket, add_note, search_faq, get_faq, search_config_items, get_config_item, and get_ticket_links. All other tools listed above are agent-only.
- RateLimit::MCP::Enabled
-
Enables per-customer-user rate limiting on tool calls (default: enabled). Does not apply to agents.
- RateLimit::MCP::Limit / RateLimit::MCP::WindowSeconds
-
Maximum number of tool calls (default
300) allowed per customer user within the configured time window in seconds (default3600).
When a customer user exceeds the limit, tool calls fail with a JSON-RPC error (code -32003) that includes a retryAfter field indicating how many seconds remain until the window resets.
Security Considerations
Because MCP tools can read and write ticket, FAQ, and configuration item data, restrict access carefully:
-
Assign only the agents or service accounts that need MCP access to the allowed group(s).
-
Use Allowed Tools to expose only the tools a given integration actually needs.
-
Use Allowed Dynamic Fields to expose only the ticket dynamic fields a given integration actually needs.
-
Review the system log for impersonation and rate-limit related entries regularly.
Untrusted Content
Ticket titles, article bodies, FAQ text, and configuration item attribute values are written by agents, customers, or other integrations, not by OTRS itself. The MCP server treats all of it as untrusted data:
-
The short text summary a tool returns alongside its structured result (for example the first line of a
get_ticketorget_faqresponse) never includes a ticket title, FAQ title, configuration item name, article body, or FAQ field content. It is built only from identifiers and status/category fields (ticket number, queue, state, priority, and equivalents for FAQ and CMDB tools). -
That same untrusted text is still returned in full in the tool’s structured result, since removing it would make the data unusable; only the short summary is restricted.
-
The server’s startup message to MCP clients (
initialize) instructs the connected model to never treat instructions found inside ticket, FAQ, or configuration item content as commands to follow. -
Future template and attachment content is covered by the same policy: it belongs in the tool’s structured result, never in a short text summary.
None of this enforces anything by itself. Tool annotations and the startup message are hints for a well-behaved client; they do not authorize or skip any server-side check, and they do not prevent or neutralize a prompt-injection attempt. The access controls above (allowed groups, Allowed Tools, customer-visibility rules) remain the actual security boundary.
