MCP Server

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.

Add Web Service Operation Screen - MCP::Handler

Add Web Service Operation Screen – MCP::Handler

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_users is 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 initialize call. 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::AllowedUserGroups for 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::Impersonation is 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-Token header, whose verified subject must match the requested customer. This check is controlled by the RequireIdentityToken setting 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. Enable RequireIdentityToken for 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.

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):

  1. API key (recommended for AI agents), sent as an X-API-Key header. Create and manage keys under Credentials.

  2. Access token, sent as an Authorization: Bearer header.

  3. Agent login and password, sent as an Authorization: Basic header, or as UserLogin/Password in the request body.

  4. Customer user login and password, sent as CustomerUserLogin/Password in 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 (default 3600).

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_ticket or get_faq response) 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.

Scroll to Top