Connect HaloITSM to Claude: Automate Billing, Projects, and Quotes

If you need to connect HaloITSM to Claude to automate ticket triage, service delivery, or project billing, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool-calling capabilities and the HaloITSM REST API. You can either build, host, 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 HaloITSM to ChatGPT or explore our broader architectural overview on connecting HaloITSM to AI Agents.

Giving a Large Language Model (LLM) read and write access to an IT Service Management (ITSM) system is a massive engineering challenge. You have to handle OAuth token lifecycles, map complex relational data models to MCP tool definitions, and manage strict API rate limits. Every time an endpoint changes, you have to update your server code and redeploy. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for HaloITSM, connect it natively to Claude, and execute complex workflows using natural language.

The Engineering Reality of the HaloITSM 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 a dense platform like HaloITSM is painful.

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

Relational Entity ID Resolution HaloITSM is highly relational. You cannot simply instruct the API to assign a ticket to "The Infrastructure Team" with a "High" priority. The API requires the exact numeric team_id, priority_id, client_id, and sla_id. This means your agent cannot just make a single write request; it must first execute a series of read operations to map human-readable strings to internal identifiers. If your MCP server does not expose these lookup tables as discrete tools, Claude will hallucinate IDs and the API requests will fail.

Complex Attachment Encoding Handling attachments in ITSM systems is notoriously difficult. HaloITSM requires attachments to be submitted as Base64 encoded strings within specific JSON payloads, alongside file metadata. Prompting an LLM to generate or handle massive Base64 strings directly often blows up context windows and leads to malformed JSON. A managed MCP server abstracts this complexity, allowing the model to focus on the metadata while the proxy layer handles the raw payload transmission.

Transparent Rate Limit Handling HaloITSM enforces API rate limits to protect platform stability, especially when executing complex queries across large ticket volumes. A critical architectural detail of Truto's MCP implementation is that Truto does not retry, throttle, or apply backoff on rate limit errors. When the HaloITSM API returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the calling client.

However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This pass-through design is intentional: it prevents silent queue build-ups in the middleware and ensures the caller (your agent framework or Claude) retains full control over retry logic and exponential backoff strategies.

How to Generate a HaloITSM MCP Server with Truto

Truto dynamically generates MCP tools based on the active API documentation and configuration of your integrated HaloITSM account. It reads the available resource endpoints and their schemas, mapping them into a flat input namespace where query and body parameters are properly routed during execution.

You can generate your MCP server using either the Truto Dashboard or the REST API.

Method 1: Via the Truto UI

For quick prototyping and manual configuration, the Truto dashboard is the fastest route:

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected HaloITSM account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can optionally filter tools by method (e.g., read-only) or tag (e.g., only billing-related tools).
6. Copy the generated MCP server URL. This URL contains a cryptographic token that securely routes requests to your specific integrated account.

Method 2: Via the Truto API

For programmatic, multi-tenant deployments where you need to spin up MCP servers for your end-users dynamically, use the API.

Make an authenticated POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/<HALOITSM_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HaloITSM Billing & Project Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["billing", "projects", "crm"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API provisions the server, validates that the requested filters match at least one documented tool, and stores the hashed routing token in a distributed key-value store. The response will include your ready-to-use URL:

{
  "id": "mcp_abc123",
  "name": "HaloITSM Billing & Project Agent",
  "config": { "methods": ["read", "write"], "tags": ["billing", "projects", "crm"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/t_xyz987654321..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your Claude environment. Because Truto's MCP servers communicate over standard HTTP POST with JSON-RPC 2.0 messages, configuration is minimal.

Method 1: Via the Claude UI

If you are using the Claude Desktop application or an enterprise Claude workspace with connector support:

1. Open Claude and navigate to Settings.
2. Click on Integrations or Connectors (depending on your tier).
3. Select Add MCP Server or Add custom connector.
4. Give the connection a name (e.g., "HaloITSM via Truto").
5. Paste your Truto MCP URL into the endpoint field and click Add.

Claude will immediately send an initialize handshake to the URL, discover the available tools, and make them available in your chat interface.

Method 2: Via Manual Configuration File

For local development or custom agent deployments, you can connect to the Truto MCP URL using the standard Server-Sent Events (SSE) bridge provided by the MCP SDK. Edit your claude_desktop_config.json file (typically located in ~/Library/Application Support/Claude/ on macOS):

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

Restart Claude Desktop. The application will execute the bridge command, connect to the Truto endpoint, and pull the HaloITSM tool definitions.

Hero Tools for HaloITSM

Truto automatically generates tools for every documented resource and method on the HaloITSM integration. By feeding these schemas to Claude, the model knows exactly what data is required to execute a request.

Here are the most powerful tools available for orchestrating IT and billing operations.

list_all_halo_itsm_tickets

This tool retrieves a paginated list of tickets in HaloITSM. It is the primary discovery tool for your agent, allowing it to search for open incidents, service requests, or specific client issues. Truto injects limit and next_cursor parameters into the schema, instructing Claude to pass pagination cursors back unchanged to traverse large datasets.

"Find all open tickets assigned to the 'Network Operations' team that have breached their SLA. Give me a summary of the client names and ticket IDs."

get_single_halo_itsm_ticket_by_id

Once Claude identifies a relevant ticket, it uses this tool to pull the deep context. The response includes fields like client_name, sla_id, status_id, and lastactiondate. This provides the LLM with the context needed to draft a customer update or analyze the root cause of an incident.

"Pull the full details for ticket ID 45920. Who is the assigned agent, and what was the last update provided by the client?"

create_a_halo_itsm_ticket

This is the core write operation for service management. If an id is included, the ticket is updated; if omitted, a new ticket is generated. Because the input namespace is flat, Claude simply passes the required fields (like summary, details, client_id, and team_id), and Truto maps them to the correct JSON body format expected by HaloITSM.

"Create a new High priority ticket for client ID 104 regarding a VPN connectivity failure. Assign it to the Security team and set the status to Open."

create_a_halo_itsm_action

In HaloITSM, an "action" represents an update, note, or time entry logged against a ticket. This tool is essential for updating progress without altering the core ticket metadata. It requires a ticket_id and allows Claude to append internal notes or send responses to end-users.

"Add a private internal note to ticket 45920 stating that we have rebooted the core router and are monitoring packet loss. Do not email the client."

list_all_halo_itsm_projects

ITSM isn't just about break/fix; it involves long-term delivery. This tool returns a list of project objects (often stored as specialized tickets in HaloITSM). It includes summary data, priority, associated SLAs, and the client name, allowing your agent to report on project health.

"List all active onboarding projects for the client 'Acme Corp'. What is the current status of each project?"

list_all_halo_itsm_quotes

This tool retrieves quoting and billing records. It returns total revenue, line items, associated ticket IDs, and expiration dates. Giving Claude access to quotes allows it to answer commercial questions alongside technical ones, bridging the gap between service delivery and account management.

"Find all pending quotes that are set to expire this week. Calculate the total potential revenue and list the associated ticket IDs."

To view the complete schema definitions and the full list of available operations, refer to the HaloITSM integration page.

Workflows in Action

When Claude is equipped with these tools, it stops being a passive conversational bot and becomes an active participant in your IT operations.

Workflow 1: Automated Ticket Triage and Response

Persona: L1 Service Desk Automation

"A user from Wayne Enterprises emailed saying they are locked out of their primary accounting software. Check if they have an active ticket. If not, create one, assign it to the Identity team, and draft an initial response action asking for the specific error code."

Step-by-step Execution:

1. list_all_halo_itsm_clients: Claude searches for "Wayne Enterprises" to retrieve their numeric client_id.
2. list_all_halo_itsm_tickets: Claude queries for recent open tickets associated with that client_id to prevent duplicate logging.
3. list_all_halo_itsm_teams: Claude searches for the "Identity" team to retrieve their team_id.
4. create_a_halo_itsm_ticket: Finding no existing ticket, Claude creates a new one using the retrieved client_id and team_id, setting the summary to "Accounting Software Lockout".
5. create_a_halo_itsm_action: Claude adds an action to the new ticket, sending an email to the user asking for the specific error code to aid in troubleshooting.

Outcome: The ticket is correctly categorized, routed to the right team using exact database IDs, and the client receives an immediate, context-aware request for more information - entirely autonomously.

graph TD
    A[User Request] --> B[list_all_halo_itsm_clients]
    B --> C[list_all_halo_itsm_tickets]
    C --> D{Existing Ticket?}
    D -->|Yes| E[create_a_halo_itsm_action: Update]
    D -->|No| F[list_all_halo_itsm_teams]
    F --> G[create_a_halo_itsm_ticket]
    G --> H[create_a_halo_itsm_action: Email User]

Workflow 2: Project & Billing Scoping

Persona: Technical Account Manager

"Give me a health report for the 'Stark Industries Cloud Migration' project. Summarize the latest actions on the project ticket, and check if there are any unapproved quotes associated with this client."

Step-by-step Execution:

1. list_all_halo_itsm_clients: Claude identifies the client_id for "Stark Industries".
2. list_all_halo_itsm_projects: Claude searches for the specific project summary under that client to find the project_id.
3. list_all_halo_itsm_actions: Claude fetches recent actions associated with the project ticket to summarize the engineering progress.
4. list_all_halo_itsm_quotes: Claude queries the quotes endpoint filtering by the client_id and looks for statuses indicating "pending" or "unapproved".

Outcome: The Account Manager receives a comprehensive briefing combining technical project status with pending commercial blockers, allowing them to follow up with the client effectively.

Security and Access Control

Giving an AI agent access to your entire IT service desk and billing platform presents significant security risks. Truto provides strict controls at the MCP server level to limit the blast radius of any AI operation.

• Method Filtering (methods): You can restrict an MCP server to specific HTTP verbs. For example, setting methods: ["read"] ensures the agent can only execute get and list operations, making it impossible for Claude to accidentally delete a user or alter a project timeline.
• Tag Filtering (tags): Truto groups integration resources using descriptive tags. By configuring a server with tags: ["support"], you restrict the server to only expose tools related to tickets and knowledge bases, intentionally hiding billing, quotes, and contract endpoints.
• Extra Authentication (require_api_token_auth): By default, possessing the MCP URL is enough to interact with the server. For higher security deployments, setting require_api_token_auth: true adds a secondary middleware layer. The client must pass a valid Truto API token in the Authorization header, ensuring only authenticated internal systems can execute tools.
• Managed Expiration (expires_at): For temporary workflows or external contractor access, you can attach an ISO datetime to the server. Once the timestamp is reached, the server is automatically revoked and cleaned up via scheduled infrastructure alarms, ensuring no stale access points remain.

Ship Enterprise AI Workflows Faster

Building a custom integration layer between Claude and an enterprise platform like HaloITSM is a significant distraction from your core product. You have to maintain relational data mapping, normalize varying API error payloads, and build robust security guardrails from scratch.

Truto abstracts this entire layer. By deriving MCP tools directly from live integration schemas, Truto provides a maintenance-free bridge between your AI agents and your users' data.

Stop writing custom API wrappers and start building agentic workflows.