HaloPSA API Gateway Server

A Model Context Protocol (MCP) server that provides seamless integration with the HaloPSA API. Built for Claude Desktop to interact with HaloPSA — search tickets, manage clients, execute API calls, and more.

Features

• 🔐 OAuth2 Authentication — Client credentials flow with automatic token refresh
• 🎫 Smart Ticket Tools — Search, create, update tickets and add actions with dedicated tools
• 👥 Client & User Management — Search clients, users, agents, sites
• 📦 Asset Management — Search and manage assets
• 📋 Project & Contract Tools — Search projects, contracts, invoices
• 🔧 Generic API Access — Execute any HaloPSA API call with execute_api_call
• 💾 Fast Memory — Save frequently used queries for instant reuse
• 📚 Built-in Endpoint Reference — No database or swagger file needed — all 29 endpoints documented inline

Architecture

Unlike traditional approaches that require downloading a swagger.json and building a database, this server has the complete HaloPSA API endpoint catalog built right in. This means:

• No database build step — works immediately after install
• No swagger file needed — endpoint reference is always available
• Pure Python — no Node.js wrapper layer
• Smart tools for common operations + generic tools for anything else

Installation

Prerequisites

• Python 3.10+
• pip package manager

Quick Setup

1. Clone the repo:

   git clone https://github.com/jasondsmith72/HALO-PSA-API-Gateway-MCP.git
   cd HALO-PSA-API-Gateway-MCP
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure Claude Desktop — Add to your claude_desktop_config.json:

   {
     "mcpServers": {
       "halo-psa-api": {
         "command": "python",
         "args": ["C:/path/to/HALO-PSA-API-Gateway-MCP/halo_api_gateway_server.py"],
         "env": {
           "HALO_BASE_URL": "https://yourtenant.halopsa.com",
           "HALO_CLIENT_ID": "your-client-id",
           "HALO_CLIENT_SECRET": "your-client-secret",
           "HALO_TENANT": "yourtenant",
           "HALO_SCOPE": "all"
         }
       }
     }
   }
   

4. Restart Claude Desktop and the MCP server will be available.

Environment Variables

Variable	Required	Description
HALO_BASE_URL	Yes	Your HaloPSA instance URL (e.g. https://yourtenant.halopsa.com)
HALO_CLIENT_ID	Yes	OAuth2 Client ID from HaloPSA API application
HALO_CLIENT_SECRET	Yes	OAuth2 Client Secret
HALO_TENANT	No*	Tenant name (required for cloud-hosted instances)
HALO_AUTH_URL	No	Override auth token URL (defaults to {BASE_URL}/auth/token)
HALO_SCOPE	No	API scope (defaults to all)

Getting API Credentials

1. Login to HaloPSA → Configuration → Integrations → HaloPSA API
2. Click View Applications → New
3. Set Authentication Method to Client ID and Secret (Services)
4. Set Login Type to Agent and select an agent account
5. Under Permissions, set to all (or configure specific permissions)
6. Save and note your Client ID and Client Secret

Available Tools (22 total)

Smart Tools (High-Level)

Tool	Description
search_tickets	Search tickets with filters (client, agent, status, etc.)
get_ticket	Get a single ticket by ID
create_ticket	Create a new ticket
update_ticket	Update an existing ticket
add_action_to_ticket	Add a note/action to a ticket
search_clients	Search clients/customers
get_client	Get a single client by ID
search_users	Search end-users/contacts
search_assets	Search IT assets
search_agents	Search agents/technicians
search_projects	Search projects
search_contracts	Search contracts
search_invoices	Search invoices

Generic Tools (Power User)

Tool	Description
execute_api_call	Execute any HaloPSA API call with full control
send_raw_api_request	Send raw API request string (e.g. GET /Tickets?open_only=true)

Reference Tools

Tool	Description
list_endpoints	Browse available API endpoints by category
get_endpoint_details	Get detailed info about any endpoint

Fast Memory Tools

Tool	Description
save_to_fast_memory	Save a query for quick reuse
list_fast_memory	List saved queries
delete_from_fast_memory	Delete a saved query
clear_fast_memory	Clear all saved queries

Usage Examples

In Claude Desktop, you can ask:

• "Show me all open tickets for client ID 42"
• "Create a ticket for MicroTech USA about a VPN issue"
• "Search for all assets belonging to client 15"
• "What agents do we have?"
• "Add a note to ticket 1234 saying the issue has been resolved"
• "List all HaloPSA API endpoints"
• "Show me details about the Tickets endpoint"
• "Execute GET /Tickets with open_only=true and count=5"

Project Structure

HALO-PSA-API-Gateway-MCP/
├── halo_api_gateway_server.py    # Main entry point
├── requirements.txt               # Python dependencies
├── README.md                      # This file
└── api_gateway/
    ├── __init__.py
    ├── server.py                  # MCP server implementation
    ├── endpoints.py               # Built-in API endpoint reference (29 endpoints)
    └── fast_memory_db.py          # Fast Memory storage

License

UNLICENSED — Private use

Author

Jason Smith — MicroTech USA