Connect TOPdesk to Claude: Automate Tickets, Assets & Visitor Logs

If you need to connect TOPdesk to Claude to automate IT incident management, track enterprise assets, or manage visitor registrations, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and TOPdesk's REST APIs. 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 ChatGPT, check out our guide on connecting TOPdesk to ChatGPT or explore our broader architectural overview on connecting TOPdesk to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling IT Service Management (ITSM) platform like TOPdesk is an engineering challenge. You have to handle API authentication lifecycles, map massive JSON schemas to MCP tool definitions, and deal with TOPdesk's highly specific query languages. Every time TOPdesk updates an endpoint or deprecates a field, you have to update your server code, redeploy, and test the integration.

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

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, the reality of implementing it against TOPdesk's APIs is painful. You are not just integrating "TOPdesk" - you are integrating the Incident Management API, Asset Management API, and Visitor Registration API, all of which have different design patterns, filtering syntaxes, and quirks.

If you decide to build a custom MCP server for TOPdesk, you own the entire API lifecycle. Here are the specific challenges you will face:

Complex Query Languages (FIQL and RSQL) TOPdesk does not use standard REST query parameters (like ?status=open) for most of its list endpoints. The Incidents API relies on FIQL (Feed Item Query Language), requiring exact syntax like query=operator.id==<uuid>;closed==false. Meanwhile, the Visitor API uses RSQL (Restful Service Query Language). If you expose raw query fields to Claude without strict schema guidance, the LLM will hallucinate syntax and fail to fetch data. A managed MCP server abstracts these requirements into typed schemas.

The Archiving Paradigm In TOPdesk, you rarely use the HTTP DELETE method. Instead, records like assets, branches, and locations are "archived". To archive an entity, the API requires a PATCH or PUT request containing a specific archiving_reason UUID. If your LLM tries to simply call a delete tool, it will fail. Your MCP layer must map standard "delete" intent into TOPdesk's specific archiving workflows.

Fragmented API Versions TOPdesk's API endpoints are split across multiple versions that behave differently. For example, the v2/persons endpoint requires different payload structures for the department field depending on how the customer configured their TOPdesk environment (dropdown list vs plain text). A custom MCP server requires you to build dynamic introspection to figure out which payload shape to send. Truto normalizes this automatically.

Strict Rate Limits TOPdesk enforces rate limits on API calls. Factual note: Truto does not retry, throttle, or apply backoff on rate limit errors. When TOPdesk returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (your MCP client or agent framework) is responsible for reading these headers and executing retry/backoff logic.

Creating the TOPdesk MCP Server

To bridge Claude and TOPdesk, you need to generate an MCP server URL. Truto dynamically generates this server based on the TOPdesk API documentation and your specific environment configurations. You can create this server in two ways.

Method 1: Via the Truto UI

If you prefer a visual interface, you can generate the server directly from the Truto dashboard:

1. Navigate to the Integrated Accounts page for your connected TOPdesk instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., restrict to read-only methods or specific tags).
5. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For teams building automated provisioning pipelines, you can generate the MCP server programmatically. Send a POST request to the /integrated-account/:id/mcp endpoint with your desired configuration.

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

The API provisions the server and returns a secure, ready-to-use URL:

{
  "id": "abc-123",
  "name": "TOPdesk ITSM Agent",
  "config": { "methods": ["read", "write"], "tags": ["incidents", "assets"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have your TOPdesk MCP server URL, you must connect it to Claude. The process differs slightly depending on whether you are using the desktop application UI or configuring it manually via code.

Method A: Via the Claude UI

If you are using the Claude Desktop application or a web interface that supports native UI configuration:

1. Open Claude and navigate to Settings.
2. Click on Integrations or Connectors.
3. Click Add MCP Server (or Add Custom Connector).
4. Paste the Truto MCP server URL into the provided field.
5. Click Add or Save.

Claude will immediately perform a handshake with the URL, exchange capabilities, and load the TOPdesk tools into its context window.

Method B: Via Manual Configuration File

If you are deploying Claude Desktop in a managed environment or prefer configuration as code, you can modify the claude_desktop_config.json file. Truto's remote MCP servers operate over Server-Sent Events (SSE), so you will use the official @modelcontextprotocol/server-sse transport.

Edit your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Restart Claude Desktop. The model will parse the configuration, start the SSE transport process, and fetch the available TOPdesk tools.

Security and Access Control

Exposing an enterprise ITSM platform to an LLM requires strict security boundaries. Truto provides four distinct mechanisms to lock down your TOPdesk MCP server:

• Method Filtering: Restrict the server to safe operation types. Passing methods: ["read"] ensures the LLM can only query incidents and assets, physically preventing it from creating, updating, or deleting records.
• Tag Filtering: Scope the server to specific operational domains. Passing tags: ["incidents"] exposes ticketing tools but hides the HR, Asset, and Visitor endpoints entirely.
• Require API Token Auth: By default, the cryptographically secure MCP URL is sufficient to authenticate requests. Setting require_api_token_auth: true forces the client to also pass a valid Truto API token in the Authorization header, adding a secondary layer of enterprise identity verification.
• Server Expiration: Use the expires_at parameter to generate ephemeral MCP servers. This is ideal for granting an AI agent temporary access to resolve a specific P1 incident, after which the server URL automatically self-destructs.

Core TOPdesk MCP Tools

Truto automatically generates descriptive, heavily-typed tools from TOPdesk's resources. Here are the highest-leverage tools available to Claude once connected.

list_all_to_pdesk_incidents

This tool allows Claude to query tickets using TOPdesk's FIQL syntax. It supports field selection, pagination, and complex filtering (e.g., fetching open high-priority tickets assigned to a specific operator group).

"Find all unassigned P1 incidents created in the last 24 hours. Extract their brief descriptions and current escalation status."

create_a_to_pdesk_incident

Used to log new tickets into the system. The tool schema enforces TOPdesk's required fields, ensuring the LLM categorizes the incident correctly before submission.

"Log a new hardware request incident for Sarah Connor. She needs a replacement MacBook charger. Route it to the IT Hardware operator group."

update_a_to_pdesk_incident_by_id

Allows the model to modify existing tickets. This is critical for automated triage, reassigning misrouted tickets, or updating the SLA target dates.

"Update incident ID 9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c. Change the status to 'Waiting for user' and add an action note saying we need the MAC address."

get_single_to_pdesk_asset_by_id

Retrieves the full configuration item (CI) record from TOPdesk Asset Management. This exposes hardware specs, linked users, current status, and warranty information.

"Pull the details for asset ID 1a2b3c4d-5e6f. Is it currently assigned to an employee, and what is its network IP address?"

to_pdesk_incident_attachments_upload_by_id

Enables Claude to attach files (like server logs, error screenshots, or parsed PDF reports) directly to a TOPdesk incident. Truto handles the multipart/form-data translation under the hood.

"Upload the generated system diagnostic log to incident number I-2405-0012."

list_all_to_pdesk_visitors

Queries the Visitor Registration module using RSQL. This lets the agent search for expected arrivals, historical visits, or active guests currently signed into a specific branch.

"Show me the visitor log for the London office today. Have the auditors from KPMG arrived yet?"

create_a_to_pdesk_reservation

Books resources - such as meeting rooms, company cars, or loaner laptops - through the TOPdesk Reservations API.

"Create a reservation for the main boardroom tomorrow at 10:00 AM for a 2-hour architecture review meeting. Assign the reservation to my user ID."

To view the complete schema definitions and the full list of available operations, visit the TOPdesk integration page.

Workflows in Action

When you combine these tools, Claude transforms from a chatbot into a fully capable ITSM orchestration agent. Here are two real-world examples of how this architecture handles complex workflows.

Workflow 1: IT Asset & Ticket Orchestration

When a user reports a broken laptop, the agent needs to verify the asset, log the incident, and initiate the replacement process.

"My laptop screen is cracked. My employee ID is E-90210. Log a ticket and see if there are any loaners available."

Execution Steps:

1. Claude calls list_all_to_pdesk_people (filtered by the employee ID) to get the user's TOPdesk UUID.
2. Claude calls list_all_to_pdesk_assets (filtered by the user's UUID) to identify the specific broken laptop.
3. Claude calls create_a_to_pdesk_incident to log the hardware failure, linking the user and the broken asset.
4. Claude calls list_all_to_pdesk_reservable_assets to search the inventory for available loaner laptops.
5. Claude calls create_a_to_pdesk_reservation to book a loaner laptop for the user.

Result: The user receives an immediate response confirming the ticket number, the verification of their broken hardware, and instructions on where to pick up their reserved loaner device.

sequenceDiagram
    participant User as User Prompt
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant TOPdesk as TOPdesk API

    User->>Claude: "My screen is cracked..."
    Claude->>Truto: call tool: list_all_to_pdesk_assets
    Truto->>TOPdesk: GET /api/assets?query=...
    TOPdesk-->>Truto: 200 OK (Asset data)
    Truto-->>Claude: JSON response
    Claude->>Truto: call tool: create_a_to_pdesk_incident
    Truto->>TOPdesk: POST /api/incidents
    TOPdesk-->>Truto: 201 Created (Incident logged)
    Truto-->>Claude: JSON response
    Claude->>Truto: call tool: create_a_to_pdesk_reservation
    Truto->>TOPdesk: POST /api/reservations
    TOPdesk-->>Truto: 201 Created (Loaner reserved)
    Truto-->>Claude: JSON response
    Claude-->>User: "Ticket logged. Pick up your loaner at IT desk."

Workflow 2: Facilities & Visitor Management

Facilities management involves coordinating external guests with internal resources. An agent can completely automate the front desk experience.

"The catering company just arrived for the all-hands meeting. Log them in and let me know which room the meeting is in."

Execution Steps:

1. Claude calls list_all_to_pdesk_visitors using RSQL to find the expected visitor record for the catering company.
2. Claude calls to_pdesk_visitors_bulk_update to change the visitor's arrivalStatus to "arrived".
3. Claude calls list_all_to_pdesk_reservations to check the day's reservations for the "all-hands meeting".
4. Claude extracts the reservedFacilities array from the response to identify the specific room location.

Result: The LLM updates the official security logs in TOPdesk to reflect that the vendor is on-site, and instantly replies to the user with the correct room number to direct the catering staff.

Strategic Wrap-up

Connecting an AI agent to TOPdesk requires more than just passing an API key. You must handle complex query syntaxes, respect strict archiving paradigms, and translate varying API versions into clean, semantic tools. Building this infrastructure in-house means your engineering team assumes the ongoing maintenance burden for every upstream schema change.

By leveraging Truto's managed MCP architecture, you shift that burden. Truto automatically generates the tool schemas from documentation, standardizes rate limit headers, and provides granular security controls out of the box. Your engineers can focus on building intelligent agent workflows, rather than debugging FIQL queries and tracking down missing archiving reason IDs.