HaloPSA — Claude Code MCP server: what it does, how to install
HaloPSA is a Claude Code MCP server that links assistants to the HaloPSA REST API. Automates tickets, customer records, and billing inside agent chat.
Apache-2.0 ★ 5 updated 2026-11-16
claude mcp add --env HALOPSA_CLIENT_ID=<HALOPSA_CLIENT_ID> --env HALOPSA_CLIENT_SECRET=<HALOPSA_CLIENT_SECRET> --env HALOPSA_TENANT=<HALOPSA_TENANT> --env HALOPSA_BASE_URL=<HALOPSA_BASE_URL> --env MCP_TRANSPORT=<MCP_TRANSPORT> --transport stdio halopsa -- docker run -i --rm -e HALOPSA_CLIENT_ID -e HALOPSA_CLIENT_SECRET -e HALOPSA_TENANT -e HALOPSA_BASE_URL -e MCP_TRANSPORT ghcr.io/wyre-ai/halopsa-mcp:v1.8.4What HaloPSA does
The server links your coding assistant to HaloPSA services covering support tickets, customer accounts, hardware assets, and invoices. It relies on a decision tree model instead of registering every tool upfront: assistants invoke halopsa_navigate first to choose a target domain, which loads only the relevant tools on demand.
Ticket management covers issue creation, list filters, and adding activity notes with duration logged via time_minutes. Running the prebuilt Docker container requires OAuth 2.0 credentials (HALOPSA_CLIENT_ID and HALOPSA_CLIENT_SECRET) plus your instance identifier in HALOPSA_TENANT or HALOPSA_BASE_URL. If installed through npm directly, builds will fail without a GitHub Personal Access Token scoped to read:packages.
What it helps with
- create and update service desk tickets inside HaloPSA
- log billable work duration on tickets using
time_minutes - search company profiles and inspect linked IT assets
- pull invoice details and inspect technician team assignments
Example prompts for the agent
- Run halopsa_navigate to switch context to the tickets domain
- Search HaloPSA clients for Acme Corp and show active assets
- Log 45 minutes of troubleshooting on ticket 5012 with an action note
How to install HaloPSA
Platform CLI
claude mcp add --env HALOPSA_CLIENT_ID=<HALOPSA_CLIENT_ID> --env HALOPSA_CLIENT_SECRET=<HALOPSA_CLIENT_SECRET> --env HALOPSA_TENANT=<HALOPSA_TENANT> --env HALOPSA_BASE_URL=<HALOPSA_BASE_URL> --env MCP_TRANSPORT=<MCP_TRANSPORT> --transport stdio halopsa -- docker run -i --rm -e HALOPSA_CLIENT_ID -e HALOPSA_CLIENT_SECRET -e HALOPSA_TENANT -e HALOPSA_BASE_URL -e MCP_TRANSPORT ghcr.io/wyre-ai/halopsa-mcp:v1.8.4Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
codex mcp add halopsa --env HALOPSA_CLIENT_ID=<HALOPSA_CLIENT_ID> --env HALOPSA_CLIENT_SECRET=<HALOPSA_CLIENT_SECRET> --env HALOPSA_TENANT=<HALOPSA_TENANT> --env HALOPSA_BASE_URL=<HALOPSA_BASE_URL> --env MCP_TRANSPORT=<MCP_TRANSPORT> -- docker run -i --rm -e HALOPSA_CLIENT_ID -e HALOPSA_CLIENT_SECRET -e HALOPSA_TENANT -e HALOPSA_BASE_URL -e MCP_TRANSPORT ghcr.io/wyre-ai/halopsa-mcp:v1.8.4Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"halopsa": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HALOPSA_CLIENT_ID",
"-e",
"HALOPSA_CLIENT_SECRET",
"-e",
"HALOPSA_TENANT",
"-e",
"HALOPSA_BASE_URL",
"-e",
"MCP_TRANSPORT",
"ghcr.io/wyre-ai/halopsa-mcp:v1.8.4"
],
"env": {
"HALOPSA_CLIENT_ID": "<HALOPSA_CLIENT_ID>",
"HALOPSA_CLIENT_SECRET": "<HALOPSA_CLIENT_SECRET>",
"HALOPSA_TENANT": "<HALOPSA_TENANT>",
"HALOPSA_BASE_URL": "<HALOPSA_BASE_URL>",
"MCP_TRANSPORT": "<MCP_TRANSPORT>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"halopsa": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HALOPSA_CLIENT_ID",
"-e",
"HALOPSA_CLIENT_SECRET",
"-e",
"HALOPSA_TENANT",
"-e",
"HALOPSA_BASE_URL",
"-e",
"MCP_TRANSPORT",
"ghcr.io/wyre-ai/halopsa-mcp:v1.8.4"
],
"env": {
"HALOPSA_CLIENT_ID": "<HALOPSA_CLIENT_ID>",
"HALOPSA_CLIENT_SECRET": "<HALOPSA_CLIENT_SECRET>",
"HALOPSA_TENANT": "<HALOPSA_TENANT>",
"HALOPSA_BASE_URL": "<HALOPSA_BASE_URL>",
"MCP_TRANSPORT": "<MCP_TRANSPORT>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
gemini mcp add -e HALOPSA_CLIENT_ID=<HALOPSA_CLIENT_ID> -e HALOPSA_CLIENT_SECRET=<HALOPSA_CLIENT_SECRET> -e HALOPSA_TENANT=<HALOPSA_TENANT> -e HALOPSA_BASE_URL=<HALOPSA_BASE_URL> -e MCP_TRANSPORT=<MCP_TRANSPORT> halopsa docker run -i --rm -e HALOPSA_CLIENT_ID -e HALOPSA_CLIENT_SECRET -e HALOPSA_TENANT -e HALOPSA_BASE_URL -e MCP_TRANSPORT ghcr.io/wyre-ai/halopsa-mcp:v1.8.4Replace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about HaloPSA
How to install HaloPSA in Claude Code?
Run this command: `claude mcp add --env HALOPSA_CLIENT_ID=<HALOPSA_CLIENT_ID> --env HALOPSA_CLIENT_SECRET=<HALOPSA_CLIENT_SECRET> --env HALOPSA_TENANT=<HALOPSA_TENANT> --env HALOPSA_BASE_URL=<HALOPSA_BASE_URL> --env MCP_TRANSPORT=<MCP_TRANSPORT> --transport stdio halopsa -- docker run -i --rm -e HALOPSA_CLIENT_ID -e HALOPSA_CLIENT_SECRET -e HALOPSA_TENANT -e HALOPSA_BASE_URL -e MCP_TRANSPORT ghcr.io/wyre-ai/halopsa-mcp:v1.8.4`.
What does HaloPSA do?
It exposes HaloPSA service desk operations to an AI assistant, covering ticketing, clients, hardware items, and invoices. Tools load on demand after domain selection via halopsa_navigate.
What is required to run HaloPSA?
You need OAuth 2.0 credentials (HALOPSA_CLIENT_ID, HALOPSA_CLIENT_SECRET), a tenant identifier (HALOPSA_TENANT or HALOPSA_BASE_URL), and Docker. Direct npm installs also demand a GitHub PAT with read:packages scope.