Connect TOPdesk to ChatGPT: Manage Incidents & Assets via MCP

If you need to connect TOPdesk to ChatGPT to automate IT service management, provision assets, or orchestrate facility reservations, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's JSON-RPC tool calls and TOPdesk's REST API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses Claude, check out our guide on connecting TOPdesk to Claude or explore our broader architectural overview on connecting TOPdesk to AI Agents.

Giving a Large Language Model (LLM) read and write access to a complex ITSM platform like TOPdesk is a serious engineering challenge. You have to handle rigid operator vs requester endpoint splits, parse complex FIQL filtering syntaxes, and map dynamic asset templates to MCP tool definitions. Every time an admin adds a new custom field or alters a grid widget in TOPdesk, your custom server code must be updated, redeployed, and tested.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for TOPdesk, connect it natively to ChatGPT, and execute complex service desk workflows using natural language.

Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds. :::

The Engineering Reality of the TOPdesk API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, implementing it against TOPdesk's heavily segmented API is painful.

If you decide to build a custom MCP server for TOPdesk, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with TOPdesk:

The FIQL and RSQL Filtering Barrier

Unlike SaaS platforms that use standard query parameters (e.g., ?status=open&department=IT), TOPdesk relies heavily on FIQL (Feed Item Query Language) and RSQL for its search and list endpoints. To find an active incident for a specific caller, an API request must format the query as archived==false;caller.id==12345. If you expose raw endpoints to ChatGPT without strict JSON Schema definitions and prompt instructions, the LLM will hallucinate query syntax, resulting in HTTP 400 Bad Request errors.

Operator vs. Requester Contexts

TOPdesk strictly enforces a dichotomy between "Operators" (IT/helpdesk staff) and "Requesters" (Self Service Portal users). This split exists at the API path level. There are entirely separate endpoints for list_all_to_pdesk_incidents (Operator) and list_all_to_pdesk_requester_incidents (Requester). A custom MCP server must carefully scope the tools it exposes so the LLM knows exactly which context it is acting under; otherwise, it will attempt to execute operator actions using a requester identity, resulting in HTTP 403 Forbidden errors.

Grid Fields and Partial Updates

TOPdesk asset management relies on complex templates where fields are often nested inside "grid widgets". You cannot simply update a flat JSON object to change an asset. You have to use specialized endpoints (like updating grid field values via merge-patch semantics) and pass specific If-Match ETags to prevent concurrent modification errors.

Strict Rate Limiting (No Auto-Retries)

TOPdesk enforces strict rate limits to protect its database. When building an MCP server, you must design your architecture to handle rejection. Truto does not retry, throttle, or apply backoff on rate limit errors. When the TOPdesk API returns an HTTP 429, Truto passes that error directly back to the caller. Truto normalizes the upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The LLM client is strictly responsible for reading these headers and executing exponential backoff logic.

Creating the Managed TOPdesk MCP Server

Instead of forcing your engineering team to build a custom JSON-RPC router, parse TOPdesk's OpenAPI specs, and maintain FIQL translation logic, you can use Truto to generate a managed MCP server.

Truto's MCP servers are dynamic and documentation-driven. Rather than hand-coding tool definitions, Truto derives them automatically from the TOPdesk integration's resource definitions and schema records. A tool only appears in the MCP server if it has a corresponding documentation entry, acting as a strict quality gate.

You can create a TOPdesk MCP server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected TOPdesk instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (name, allowed methods, tags, and an optional expiry date).
5. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For automated provisioning, you can generate an MCP server dynamically by making an authenticated POST request to the Truto API. This validates that the TOPdesk integration has documented tools available, generates a secure cryptographic token, and stores it in Truto's distributed KV storage.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TOPdesk IT Agent MCP",
    "config": {
      "methods": ["read", "write"],
      "tags": ["incidents", "assets"]
    }
  }'

The response will contain the url required by ChatGPT:

{
  "id": "mcp-789",
  "name": "TOPdesk IT Agent MCP",
  "config": { "methods": ["read", "write"], "tags": ["incidents", "assets"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting the MCP Server to ChatGPT

Once you have your TOPdesk MCP server URL, you can connect it directly to ChatGPT. Because the URL contains a secure, hashed cryptographic token, it is fully self-contained. The URL alone authenticates the request and routes it to the specific TOPdesk tenant.

Method 1: Via the ChatGPT UI (Custom Connectors)

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Toggle Developer mode on (MCP support requires this feature flag).
3. Under MCP servers / Custom connectors, click Add a new server.
4. Enter a name (e.g., "TOPdesk (Truto)").
5. Paste the Truto MCP URL into the Server URL field.
6. Click Save. ChatGPT will perform an initialization handshake and automatically discover the TOPdesk tools.

Method 2: Via Manual Configuration File (CLI / Desktop)

If you are running a local MCP client or using a framework that relies on the @modelcontextprotocol/server-sse transport, you can connect via a JSON configuration file:

{
  "mcpServers": {
    "topdesk_truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}

Hero Tools for TOPdesk

Truto automatically generates over 150 tools for TOPdesk based on the underlying API documentation. Here are the highest-leverage tools for IT automation workflows.

list_all_to_pdesk_incidents

This is your primary discovery tool for ticket triage. It supports FIQL filtering, field selection, and pagination. ChatGPT uses this to find open tickets, search for specific callers, or filter by SLA status.

"Find all unassigned incidents created in the last 24 hours that have an escalation status of 'escalated' and list their brief descriptions."

update_a_to_pdesk_incident_by_id

This tool allows the LLM to modify an existing incident. It is critical for routing tickets, updating priorities, or assigning an operator group. The LLM must supply the internal id of the incident.

"Assign incident UUID 550e8400-e29b-41d4-a716-446655440000 to the 'Network Infrastructure' operator group and set the status to 'In Progress'."

create_a_to_pdesk_asset

Use this tool to provision new hardware or software records in the TOPdesk Asset Management module. The LLM must supply the type_id (template ID) along with any mandatory template-specific fields required by your TOPdesk configuration.

"Create a new asset record for a MacBook Pro M3. Set the status to 'In Stock' and assign it to the 'IT Hardware' template ID."

to_pdesk_incident_attachments_upload_by_id

Automated triage often requires analyzing logs. This tool allows the LLM to upload diagnostic files, scripts, or error reports directly to an incident thread, keeping all context inside TOPdesk.

"Upload this parsed system error log as a text file attachment to incident 98765432."

list_all_to_pdesk_reservations

Facility and fleet management teams use this to query current reservations. The LLM can retrieve bookings by requester, operator, or processing status to resolve scheduling conflicts.

"List all active reservations for the 'Main Boardroom' for today, and tell me who the requester is for the 2:00 PM slot."

get_single_to_pdesk_incident_by_id

When the LLM needs deep context on a specific ticket before taking action, it calls this tool to retrieve the full incident object, including the request body, action trail, caller metadata, and SLA details.

"Get the full details for incident ID 12345-abcde, including the history of operator replies and the current SLA target date."

(Note: Truto exposes the complete TOPdesk REST API surface. For the full inventory of tools, schemas, and required parameters, visit the Truto TOPdesk Integration page.)

Workflows in Action

When you connect TOPdesk to ChatGPT via an MCP server, the LLM acts as an autonomous IT agent. It can chain multiple tools together to resolve complex workflows without human intervention.

Here are two real-world examples of how ChatGPT orchestrates TOPdesk tools.

Workflow 1: VIP Incident Triage and Escalation

When a critical service goes down, IT admins need immediate context. A user can prompt ChatGPT to investigate and prioritize tickets based on caller identity.

"Find all open incidents related to 'VPN Access'. Check if any of the callers are marked as VIPs or C-Level in their person profile. If they are, escalate the incident and assign it to the Tier 3 Network Team."

Execution Steps:

1. list_all_to_pdesk_incidents: ChatGPT queries TOPdesk using FIQL to find open incidents containing "VPN Access" in the brief description.
2. get_single_to_pdesk_person_by_id: For each incident returned, the agent extracts the caller.id and fetches their full person profile to check their job title or VIP flag.
3. to_pdesk_incidents_escalate: If a VIP match is found, the agent calls the escalation endpoint with the incident ID.
4. update_a_to_pdesk_incident_by_id: Finally, the agent updates the incident record, reassigning the operatorGroup to Tier 3.

sequenceDiagram
    participant User as ChatGPT User
    participant LLM as ChatGPT
    participant MCP as Truto MCP Server
    participant Upstream as TOPdesk API

    User->>LLM: "Find VPN incidents and escalate VIPs"
    LLM->>MCP: Call list_all_to_pdesk_incidents(FIQL query)
    MCP->>Upstream: GET /api/incidents?query=...
    Upstream-->>MCP: Returns 5 incidents
    MCP-->>LLM: JSON array of incidents
    
    Note over LLM: LLM identifies 1 VIP caller
    
    LLM->>MCP: Call to_pdesk_incidents_escalate(id: 123)
    MCP->>Upstream: POST /api/incidents/id/123/escalate
    Upstream-->>MCP: 200 OK
    MCP-->>LLM: Escalation confirmed
    
    LLM->>User: "Escalated 1 VIP incident to Tier 3."

Workflow 2: Employee Onboarding and Asset Provisioning

Helpdesk teams spend hours manually provisioning hardware records. ChatGPT can automate the entire asset creation and assignment lifecycle.

"We have a new hire, Jane Doe, starting in Engineering. Create a new Laptop asset for her in TOPdesk, link it to her person record, and create a setup task for the IT provisioning team."

Execution Steps:

1. list_all_to_pdesk_people: ChatGPT searches for "Jane Doe" to retrieve her internal TOPdesk person_id.
2. create_a_to_pdesk_asset: The agent creates a new asset record using the standard Engineering Laptop template ID.
3. to_pdesk_asset_assignments_bulk_update: The agent links the newly created asset ID to Jane Doe's person_id.
4. create_a_to_pdesk_operational_activity: The agent creates a tracked task for the IT provisioning team to image the laptop and deploy it to her desk.

Security and Access Control

Exposing an ITSM platform like TOPdesk to an LLM requires strict governance. Truto MCP servers operate at the integrated account level and provide four layers of security to ensure agents only access what they should.

• Method Filtering: You can restrict an MCP server to specific operations. By passing methods: ["read"] during server creation, Truto will strip all create, update, and delete tools from the LLM's context, ensuring the agent acts in a strictly read-only capacity.
• Tag Filtering: You can scope the MCP server to specific functional areas using tags. For example, applying tags: ["incidents"] guarantees the agent can triage tickets but cannot touch asset records, reservations, or HR data.
• Additional API Token Auth: By default, the cryptographically hashed MCP URL acts as the authentication token. For higher-security environments, you can enable require_api_token_auth: true. When active, the client must also pass a valid Truto API token in the Authorization header. Possession of the URL alone is insufficient.
• Ephemeral Servers: You can attach an expires_at ISO datetime to any MCP server. Truto's distributed alarm system will automatically revoke the credentials and destroy the token in KV storage exactly when the timestamp is reached, ensuring no zombie access remains.

Stop Writing Custom API Boilerplate

Building a reliable, secure connection between ChatGPT and TOPdesk doesn't have to be a multi-week engineering project. Instead of reading OpenAPI specs, reverse-engineering FIQL queries, and writing pagination wrappers, you can use Truto to generate a production-ready MCP server instantly.

Truto handles the underlying schema generation, token security, and request routing. You get standard JSON-RPC tools, and your AI agents get immediate, safe access to the data they need to automate your IT operations.

Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds. :::