HaloPSA MCP Server

A Model Context Protocol (MCP) server for interacting with HaloPSA, featuring a decision tree architecture for efficient tool loading.

Architecture

This MCP server uses a hierarchical tool loading approach instead of exposing all tools upfront:

1. Navigation Phase: Initially exposes only a navigation tool (halopsa_navigate)
2. Domain Selection: User selects a domain (tickets, clients, assets, agents, invoices, workflows, and more)
3. Domain Tools: Server exposes domain-specific tools after selection
4. Lazy Loading: Domain handlers and the HaloPSA client are loaded on-demand

This architecture provides:

• Reduced cognitive load (fewer tools to choose from)
• Faster initial load times
• Better organization of related operations
• Clear navigation state

Installation

npm install @avantguardllc/halopsa-mcp

Configuration

Set the following environment variables:

| Variable | Required | Description | |----------|----------|-------------| | HALOPSA_CLIENT_ID | Yes | OAuth 2.0 Client ID | | HALOPSA_CLIENT_SECRET | Yes | OAuth 2.0 Client Secret | | HALOPSA_TENANT | One of | Tenant name (e.g., yourcompany) | | HALOPSA_BASE_URL | these | Explicit base URL (e.g., https://yourcompany.halopsa.com) |

Usage

Running Standalone

# Set credentials
export HALOPSA_CLIENT_ID="your-client-id"
export HALOPSA_CLIENT_SECRET="your-client-secret"
export HALOPSA_TENANT="yourcompany"

# Run the server
npx @avantguardllc/halopsa-mcp

Claude Desktop Configuration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "halopsa": {
      "command": "npx",
      "args": ["@avantguardllc/halopsa-mcp"],
      "env": {
        "HALOPSA_CLIENT_ID": "your-client-id",
        "HALOPSA_CLIENT_SECRET": "your-client-secret",
        "HALOPSA_TENANT": "yourcompany"
      }
    }
  }
}

Docker

docker build -t halopsa-mcp .
docker run -e HALOPSA_CLIENT_ID=xxx -e HALOPSA_CLIENT_SECRET=*** -e HALOPSA_TENANT=yourcompany halopsa-mcp

Available Domains

Tickets

Manage support tickets, create new tickets, update status, add actions/notes.

Tools:

• halopsa_tickets_list - List tickets with filters
• halopsa_tickets_get - Get ticket details
• halopsa_tickets_create - Create a new ticket
• halopsa_tickets_update - Update an existing ticket
• halopsa_tickets_add_action - Add a note/action to a ticket

Clients

Manage companies/clients in HaloPSA.

Tools:

• halopsa_clients_list - List clients
• halopsa_clients_get - Get client details
• halopsa_clients_create - Create a new client
• halopsa_clients_search - Search clients by name

Assets

Manage configuration items/assets.

Tools:

• halopsa_assets_list - List assets with filters
• halopsa_assets_get - Get asset details
• halopsa_assets_search - Search assets
• halopsa_assets_list_types - List available asset types

Agents

View technicians and teams.

Tools:

• halopsa_agents_list - List agents/technicians
• halopsa_agents_get - Get agent details
• halopsa_teams_list - List teams

Invoices

View billing and invoices.

Tools:

• halopsa_invoices_list - List invoices with filters
• halopsa_invoices_get - Get invoice details

Workflows

Manage HaloPSA automation workflows — ticket routing, approval chains, escalations, and SLA actions.

Tools:

• halopsa_workflows_list - List all workflows
• halopsa_workflows_get - Get a single workflow by ID
• halopsa_workflows_steps - Get all workflow steps
• halopsa_workflows_create - Create a new workflow
• halopsa_workflows_delete - Delete a workflow by ID

Ticket Types

Manage ticket type definitions used to categorize tickets.

Tools:

• halopsa_tickettypes_list - List all ticket types
• halopsa_tickettypes_get - Get a specific ticket type by ID
• halopsa_tickettypes_create - Create or update a ticket type
• halopsa_tickettypes_delete - Delete a ticket type by ID

Statuses

Manage ticket status definitions.

Tools:

• halopsa_statuses_list - List all statuses
• halopsa_statuses_get - Get a specific status by ID
• halopsa_statuses_create - Create or update a status
• halopsa_statuses_delete - Delete a status by ID

Outcomes

Manage ticket outcome/resolution definitions.

Tools:

• halopsa_outcomes_list - List all outcomes
• halopsa_outcomes_get - Get a specific outcome by ID
• halopsa_outcomes_create - Create or update an outcome
• halopsa_outcomes_delete - Delete an outcome by ID

Actions

Manage ticket action templates used for notes, updates, and replies.

Tools:

• halopsa_actions_list - List all action templates
• halopsa_actions_get - Get a specific action template by ID
• halopsa_actions_create - Create or update an action template
• halopsa_actions_delete - Delete an action template by ID

Custom Fields

Manage custom field definitions that extend entities like tickets, clients, and assets.

Tools:

• halopsa_customfields_list - List all custom field definitions
• halopsa_customfields_get - Get a specific custom field by ID
• halopsa_customfields_create - Create or update a custom field definition
• halopsa_customfields_delete - Delete a custom field definition by ID

Custom Tables

Manage custom table definitions for structured data linked to entities.

Tools:

• halopsa_customtables_list - List all custom tables
• halopsa_customtables_get - Get a specific custom table by ID
• halopsa_customtables_create - Create or update a custom table
• halopsa_customtables_delete - Delete a custom table by ID

Custom Tabs

Manage custom tab layouts on entity detail views.

Tools:

• halopsa_customtabs_list - List all custom tabs
• halopsa_customtabs_get - Get a specific custom tab by ID
• halopsa_customtabs_create - Create or update a custom tab
• halopsa_customtabs_delete - Delete a custom tab by ID

Custom Buttons

Manage custom button definitions on entity views.

Tools:

• halopsa_custombuttons_list - List all custom buttons
• halopsa_custombuttons_get - Get a specific custom button by ID
• halopsa_custombuttons_create - Create or update a custom button
• halopsa_custombuttons_delete - Delete a custom button by ID

Navigation Tools

Always available:

• halopsa_navigate - Select a domain to work with
• halopsa_status - Show current state and credential status
• halopsa_back - Return to main menu (when in a domain)

Example Workflow

User: Check my tickets
Claude: [calls halopsa_navigate with domain="tickets"]
       -> Navigated to tickets domain. Available tools: ...

User: List open tickets
Claude: [calls halopsa_tickets_list with open_only=true]
       -> [ticket list results]

User: Now show me clients
Claude: [calls halopsa_back]
       -> Navigated back to main menu.
       [calls halopsa_navigate with domain="clients"]
       -> Navigated to clients domain.

Rate Limiting

HaloPSA has a rate limit of 500 requests per 3-minute window. The client handles this with automatic request throttling.

License

Apache-2.0