--- title: "Connect TOPdesk to Claude: Automate Tickets, Assets & Visitor Logs" slug: connect-topdesk-to-claude-automate-tickets-assets-visitor-logs date: 2026-08-18 author: Roopendra Talekar categories: ["AI & Agents"] excerpt: "Learn how to connect TOPdesk to Claude using a managed MCP server. This guide covers the technical reality of the TOPdesk API, tool calling, and workflow automation." tldr: "Connect TOPdesk to Claude via Truto's managed MCP server to automate IT workflows, asset management, and visitor logs. This guide includes setup instructions, API configurations, and real-world tool-calling examples." canonical: https://truto.one/blog/connect-topdesk-to-claude-automate-tickets-assets-visitor-logs/ --- # 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](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). 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](https://truto.one/connect-topdesk-to-chatgpt-manage-incidents-assets-reservations/) or explore our broader architectural overview on [connecting TOPdesk to AI Agents](https://truto.one/connect-topdesk-to-ai-agents-orchestrate-tickets-assets-bookings/). 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](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/), 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](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/) for TOPdesk, connect it natively to Claude, and execute complex ITSM workflows using natural language. > Want to give your AI agents secure, authenticated access to TOPdesk and 100+ other SaaS APIs? Let's talk about managed MCP architecture. > > [Talk to us](https://cal.com/truto/partner-with-truto) ## 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==;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. ```bash curl -X POST https://api.truto.one/integrated-account//mcp \ -H "Authorization: Bearer " \ -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: ```json { "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): ```json { "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](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) 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](https://truto.one/integrations/detail/topdesk). ## 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. ```mermaid 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](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/), 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.