HaloPSA MCP Server

Model Context Protocol server for HaloPSA API integration with asset, user, and site management.

Key Features

• 71 tools for managing HaloPSA assets, users, sites, clients, tickets, actions, agents, workflows, milestones, budgets, ticket links, bulk updates, outcomes, validation, and SLA holds
• Deduplication with confidence scoring to prevent duplicate billing entities
• OAuth2 Client Credentials authentication with automatic token refresh
• Rate limiting with exponential backoff (60 requests/minute)
• In-memory caching with configurable TTLs and cache prewarm on startup
• Inflight request dedup prevents concurrent duplicate API calls
• Token optimization via format_options (compact/standard/detailed modes)

v1.6.0 highlights

• M4 worker-leak fix — cleanup timer now calls .unref() so broken-pipe / parent-death exits are immediate instead of hanging up to 60s.
• M3 version-import fix — server advertises the real package version (1.6.0) instead of the stale 1.0.0 hardcode.
• M2 POST idempotency hardening — POST /Actions and POST /Tickets are now at-most-once (no retry on transient errors). Prevents duplicate journal entries and double billing on network failures.
• Tool-list diet — five wordiest tool descriptions trimmed (~4 KB savings per session init). Tool count remains 71.

Important: Billing Context

HaloPSA asset and user counts are commonly used for billing calculations in MSP environments.

• Only ACTIVE assets (status_id=1) count toward billing
• Only ACTIVE users (inactive=false) count toward billing
• Duplicates = Billing errors — use the deduplication tools before creating new records

Installation

npm install halopsa-mcp-server

Or from source:

git clone https://github.com/SuperGaco/halopsa-mcp-server.git
cd halopsa-mcp-server
npm install
npm run build

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | HALOPSA_CLIENT_ID | Yes | OAuth2 Client ID | | HALOPSA_CLIENT_SECRET | Yes | OAuth2 Client Secret | | HALOPSA_BASE_URL | Yes | Your HaloPSA instance URL (e.g., https://your-instance.halopsa.com) | | HALOPSA_TEST_CLIENT_ID | Smoke tests only | Integer ID of a non-billable throwaway client used to scope test resource creation/cleanup. Required by test:smoke / test:smoke:local. |

HaloPSA API Setup

1. In HaloPSA, navigate to Configuration > Integrations > API Applications
2. Create a new application with OAuth2 Client Credentials
3. Grant appropriate permissions:
   • read:assets and read:customers for read-only access
   • edit:assets and edit:customers for write operations
4. Note the Client ID and Client Secret

Claude Desktop Configuration

Add to your Claude Desktop config:

{
  "mcpServers": {
    "halopsa": {
      "command": "node",
      "args": ["path/to/halopsa-mcp-server/dist/index.js"],
      "env": {
        "HALOPSA_CLIENT_ID": "your_client_id",
        "HALOPSA_CLIENT_SECRET": "your_client_secret",
        "HALOPSA_BASE_URL": "https://your-instance.halopsa.com"
      }
    }
  }
}

After upgrading

MCP servers read their tool registry at session/connection startup, not at every call. After installing a new version of this package, restart your MCP host (Claude Desktop quit + relaunch, or /mcp reload + reconnect in Claude Code) so the new tool list is loaded. Otherwise newly-added tools (e.g., list_halopsa_agents, delete_halopsa_ticket) will not be visible to your session even though npm view confirms they were published.

Common Recipes

Assign a ticket to a specific agent

The MCP exposes agent_id on create/update tickets, but the integer ID isn't human-meaningful. Always discover it first:

1. Call `list_halopsa_agents` (cached 1h)
2. Find the agent by `name` or `email` in the result
3. Pass that agent's `id` as `agent_id` on `create_halopsa_ticket` / `update_halopsa_ticket`

Field-name note: agents use isdisabled (one word), NOT inactive — diverges from the clients/users convention.

Create a child task under a parent project ticket

1. Find the parent ticket's `id` (via list or get)
2. Call `create_halopsa_ticket` with: `parent_id` = parent's id, `tickettype_id` = the project-task type (id=20 "Project Task" on the WilnerTech tenant), `summary`, `client_id`, `site_id` (matching the parent)
3. Halo automatically: increments parent's `child_count`, denormalises `parent_ticket_type_name` on the child, makes it visible in the parent's "Tasks" tab

Override Halo's auto-computed estimate

If estimate is omitted on create/update, Halo auto-computes it as business hours between startdate and targetdate (5 weekdays × 8h convention). To set an explicit estimate (e.g., for fixed-price phases), pass estimate as a number — Halo will use your value instead of the auto-computed one.

Find the right priority ID

list_halopsa_ticket_priorities returns priorities with id = the integer priorityid (1-4) suitable for Faults.priority_id. The underlying GUID is exposed as sla_priority_id for completeness; do not pass the GUID as priority_id — Halo will silently ignore it.

Find the right closed status

Multi-tenant Halo deployments often have 3-4 "closed-like" statuses (Closed, Closed Order, Closed Item, Completed). For canonical ticket closure, use close_halopsa_ticket (it resolves name === "Closed" && type === 0 correctly) or pass status_id explicitly via update_halopsa_ticket if your tenant uses a custom closed name.

Tools Reference

Asset Tools (11)

| Tool | Description | |------|-------------| | list_halopsa_assets | List assets with filtering, caching (1min TTL) | | get_halopsa_asset | Get single asset with custom fields | | search_halopsa_assets_by_serial | Search by serial number (key_field) | | search_halopsa_assets_by_hostname | Search by hostname (key_field2) | | create_halopsa_asset | Create new asset | | update_halopsa_asset | Update existing asset | | delete_halopsa_asset | Delete asset | | list_halopsa_asset_custom_fields | Inspect custom fields for an asset | | get_halopsa_asset_field_schema | Analyze custom field definitions | | find_halopsa_asset_match | Deduplication with confidence scoring | | scan_halopsa_asset_duplicates | Scan for duplicate assets |

User Tools (7)

| Tool | Description | |------|-------------| | list_halopsa_users | List users with filtering, caching (1min TTL) | | get_halopsa_user | Get single user with custom fields | | search_halopsa_users_by_email | Search by email address | | create_halopsa_user | Create new user | | update_halopsa_user | Update existing user | | find_halopsa_user_match | Deduplication with confidence scoring | | scan_halopsa_user_duplicates | Scan for duplicate users |

Site Tools (4)

| Tool | Description | |------|-------------| | list_halopsa_sites | List sites with caching (5min TTL) | | get_halopsa_site | Get single site | | create_halopsa_site | Create new site | | find_halopsa_site_match | Deduplication with fuzzy matching |

Client Tools (3)

| Tool | Description | |------|-------------| | list_halopsa_clients | List clients with caching (5min TTL) | | get_halopsa_client | Get single client | | search_halopsa_clients | Search clients by name |

Reference Data Tools (4)

| Tool | Description | |------|-------------| | list_halopsa_asset_types | List asset types (1hr cache) | | list_halopsa_asset_statuses | List statuses with billing notes | | list_halopsa_contact_types | List contact types (1hr cache) | | list_halopsa_agents | List agents (technicians/staff) with 1hr cache. Use to discover agent_id for ticket assignment. Fields: id, name, email, isdisabled (note: agents use isdisabled, NOT inactive). |

Ticket Reference Data Tools (5)

| Tool | Description | |------|-------------| | list_halopsa_tickettypes | List ticket types (Incident, Service Request, Change, ...) — 1hr cache | | get_halopsa_tickettype | Get a single ticket type — 1hr cache | | list_halopsa_ticket_statuses | List ticket statuses; backs close_halopsa_ticket dynamic resolution | | list_halopsa_ticket_priorities | List ticket priorities — 1hr cache | | list_halopsa_ticket_categories | List ticket categories (used by category_1..category_4) |

Ticket Tools (8)

| Tool | Description | |------|-------------| | list_halopsa_tickets | List with extensive filtering (client/site/user/agent/team/type/status/category/search/date/open_only). Array filters (tickettype_id, agent, category_1..4) accept single int or int[]. Compact response excludes details_html and customfields[]. | | get_halopsa_ticket | Single ticket with full details (includedetails=true) | | search_halopsa_tickets | Free-text search wrapper on list | | create_halopsa_ticket | POST /Tickets with array body — required: summary, tickettype_id, client_id. Optional: parent_id, site_id, agent_id, dateoccurred, startdate, source, category_1..4. | | update_halopsa_ticket | Read-before-write merge (Halo POST is REPLACE not PATCH). Supports tickettype_id, parent_id, dateoccurred, startdate, source in addition to status/agent/site/summary/details. | | close_halopsa_ticket | Dynamic closed-status lookup (name === 'Closed' && type === 0); optional resolution_note posts a final action first | | delete_halopsa_ticket | Safety-first delete with four pre-flight refusals (financial / cascade / historical / authorship). Required: ticket_id, reason (min 5 chars). Bypass: confirm_destructive: true + substring 'OVERRIDE' in reason. Idempotent on 404. | | get_halopsa_tickets_batch | Parallel batch fetch (max 50 ids) |

Ticket Action Tools (2)

| Tool | Description | |------|-------------| | add_halopsa_ticket_action | POST /Actions with array body — note/outcome/email_reply/hiddenfromuser | | list_halopsa_ticket_actions | List journal entries; compact mode includes 200-char note_preview |

Ticket Custom Field Tools (2)

| Tool | Description | |------|-------------| | list_halopsa_ticket_custom_fields | Per-tickettype field definitions via /FieldInfo?type=1 | | get_halopsa_ticket_field_schema | Sampling-based fallback when /FieldInfo is unavailable |

Batch Operations Tools (5)

| Tool | Description | |------|-------------| | get_halopsa_assets_batch | Get multiple assets (max 50) | | get_halopsa_users_batch | Get multiple users (max 50) | | get_halopsa_sites_batch | Get multiple sites (max 50) | | get_halopsa_tickets_batch | Get multiple tickets (max 50) | | bulk_update_halopsa_tickets | Update up to 20 tickets in parallel via Promise.allSettled. Each element accepts the full update_halopsa_ticket field set (status_id, agent_id, milestone_id, etc.). Returns per-ticket {success\|error, result?, error?} so a single failure does not abort the batch. |

Ticket Link Tools (1)

| Tool | Description | |------|-------------| | list_halopsa_linked_tickets | Read-side discovery of all relationships on a ticket: parent_id, child_count, and linked_tickets[] array. Compact returns {linked_ticket_id, link_type?, summary?} per entry. Write-side ticket-to-ticket linking via /IntegrationData/Get/HaloLink is deferred to v1.4 pending endpoint param discovery. For now, use parent_id on create/update as the canonical "depends on / blocks" mechanism. |

Workflow Tools (6)

| Tool | Description | |------|-------------| | list_halopsa_workflows | List all workflow definitions (cached 1h). Returns id, name, active, notinuse per workflow. | | get_halopsa_workflow | Get a single workflow with full steps[] + stages[] + flow_chart_json. | | list_halopsa_workflow_steps | List workflow steps (124 total on a typical tenant). Optionally filter by workflow_id. | | create_halopsa_workflow | POST /Workflow with array body. Accepts name, note?, steps?, stages?. | | update_halopsa_workflow | Read-before-write merge. POST /Workflow [{id, ...merged}]. | | delete_halopsa_workflow | Safety-first: refuses unless notinuse === true AND no tickettype defaults to this workflow. Override with confirm_destructive: true + 'OVERRIDE' in reason. Idempotent on 404. | | Advance a ticket through its workflow | (No dedicated tool — workflows are advanced via update_halopsa_ticket(status_id=X). Each status maps to a workflow step.) |

Ticket Milestone Tools (4)

Milestones are nested under tickets — no top-level /Milestone endpoint exists. Each Project ticket has a milestones[] array (similar to customfields[]).

| Tool | Description | |------|-------------| | list_halopsa_ticket_milestones | Return ticket.milestones[] for a given ticket id. Cached 1min. | | set_halopsa_ticket_milestones | Replace the entire milestones[] array via read-before-write merge. Each input: {name (required), target_date (required ISO), start_date?, sequence?, billing_amount?, status_id?}. | | add_halopsa_ticket_milestone | Convenience: append one milestone to the existing array. | | remove_halopsa_ticket_milestone | Convenience: remove one milestone by id. | | Link a child ticket to a milestone | (Use update_halopsa_ticket(milestone_id=X) — exposed in v1.3 on the create/update schemas.) |

Budget Tools (5)

| Tool | Description | |------|-------------| | list_halopsa_budget_types | List all BudgetType records (Fixed Price, T&M, Retainer, etc.). Cached 1h. | | create_halopsa_budget_type | POST /BudgetType with array body. Accepts name, defaultrate?, chargerate?. | | delete_halopsa_budget_type | Safety-first: refuses by default (dependency check unavailable — Halo doesn't expose budgettype_id as a /Tickets filter). Override with confirm_destructive: true + 'OVERRIDE' in reason. | | get_halopsa_ticket_budget | Return ticket.budgets[] for a given ticket id (per-ticket budget records). Cached 1min. | | set_halopsa_ticket_budget | Replace the entire per-ticket budgets[] array. Each input: {budgettype_id (required int), hours?, days?, rate?}. |

Deduplication Algorithms

Asset Deduplication

| Match Type | Confidence | Action | |------------|------------|--------| | Exact serial number | 100% | Auto-update | | Hostname only (serial mismatch) | 85% | Manual review | | No match | 0% | Create new |

User Deduplication

| Match Type | Confidence | Action | |------------|------------|--------| | Exact email | 100% | Auto-update | | UPN match (Entra) | 95% | Auto-update | | Username only | 70% | Manual review | | No match | 0% | Create new |

Site Deduplication

| Match Type | Confidence | Action | |------------|------------|--------| | Exact name | 100% | Auto-update | | Fuzzy name + address | 95% | Auto-update | | Fuzzy name only | 85% | Manual review | | No match | 0% | Create new |

Token Optimization

All tools support format_options for reducing response size:

{
  "format_options": {
    "format": "compact",
    "fields": ["id", "name", "status_id"],
    "omit_empty": true
  }
}

Formats:

• compact: Minimal fields (id, name, status)
• standard: Default fields (no pretty-printing)
• detailed: All fields with pretty-printing

Rate Limiting

• Limit: 60 requests/minute per client_id
• Auto-throttling: 1 second minimum between requests
• Retry: Exponential backoff on 429 errors (1s, 2s, 4s)
• Token refresh: 5 minutes before expiration

Development

npm run build           # Build (tsc)
npm run dev             # Watch mode (tsc --watch)
npm run typecheck       # Type-check without emit
npm run lint            # ESLint
npm test                # Jest unit tests (similarity + formatter scrubber)
npm start               # Start server (uses external env)
npm run start:local     # Start server loading .env via Node --env-file
npm run test:smoke      # Run smoke tests against live API (CI/CD env injects creds)
npm run test:smoke:local # Run smoke tests loading .env via Node --env-file

For local development, copy .env.example to .env and fill in HALOPSA_CLIENT_ID, HALOPSA_CLIENT_SECRET, HALOPSA_BASE_URL, and HALOPSA_TEST_CLIENT_ID (the last is required by test:smoke:local only).

License

MIT