HaloPSA MCP Server

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

Key Features

• 31 tools for managing HaloPSA assets, users, sites, clients, and reference data
• 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)

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 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"
      }
    }
  }
}

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 (3)

| 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) |

Batch Operations Tools (3)

| 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) |

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
npm run dev          # Watch mode
npm start            # Start server
npm run test:smoke   # Run smoke tests (requires live API credentials)

License

MIT