halopsa-mcp
Health Warn
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
MCP server for HaloPSA — tickets, clients, assets, contracts, and reporting tools for AI assistants
HaloPSA MCP Server
A Model Context Protocol (MCP) server for interacting with HaloPSA, featuring a decision tree architecture for efficient tool loading.
One-Click Deployment
[!IMPORTANT]
Before you click: this server depends on@wyre-technology/node-halopsa,
which is hosted on the GitHub Packages npm registry. GitHub Packages has no
anonymous access — even though the package is public, everynpm installneeds a
token. The cloud builder runsnpm installfor you, so you must give it one, or
the build fails withnpm error 401 Unauthorized ... npm.pkg.github.com.
- Create a GitHub Personal Access Token with the
read:packagesscope
(classic token).
Any GitHub account works — you do not need to be a member of thewyre-technologyorg to read its public packages.- Add it as a build variable when prompted by the deploy flow:
- Cloudflare Workers → set a build variable named
NODE_AUTH_TOKENto your PAT
(Workers → Settings → Build → Variables and Secrets).- DigitalOcean App Platform → set an encrypted env var named
GITHUB_TOKEN
with scope Build Time to your PAT (the.do/app.yamlalready declares it).
[!NOTE]
The DigitalOcean target builds the full Docker image and runs the complete MCP
server over HTTP — this is the recommended path for operators. The Cloudflare
Workers target is currently a thin entrypoint (the/mcproute returns 501 until
the Workers transport adapter lands) and is best suited to gateway-style
deployments; for a full self-hosted server prefer DigitalOcean or the prebuilt
container image (ghcr.io/wyre-ai/halopsa-mcp).
Architecture
This MCP server uses a hierarchical tool loading approach instead of exposing all tools upfront:
- Navigation Phase: Initially exposes only a navigation tool (
halopsa_navigate) - Domain Selection: User selects a domain (tickets, clients, assets, agents, invoices, categories, statuses, items, contracts)
- Domain Tools: Server exposes domain-specific tools after selection
- 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
Interactive Ticket Card (MCP Apps)
halopsa_tickets_get renders as an interactive card in MCP Apps hosts
(Claude Desktop/web) with an in-card "Add note" round-trip viahalopsa_tickets_add_action; plain-JSON behavior is unchanged in other hosts.
The card is neutral by default and brandable via window.__BRAND__ injection
or MCP_BRAND_* env vars (MCP_BRAND_NAME, MCP_BRAND_LOGO_URL,MCP_BRAND_PRIMARY_COLOR, MCP_BRAND_ACCENT_COLOR, MCP_BRAND_BG,MCP_BRAND_TEXT) — no rebuild needed.
Installation
This package is published to the GitHub Packages npm registry, which requires a
token even for public packages. Authenticate once, then install:
# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token) # or a PAT with read:packages
npm install @wyre-ai/halopsa-mcp
The repo's .npmrc already points the @wyre-technology scope at GitHub Packages and
reads the token from NODE_AUTH_TOKEN, so no further config is needed.
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 @wyre-ai/halopsa-mcp
Claude Desktop Configuration
Add to your Claude Desktop claude_desktop_config.json:
{
"mcpServers": {
"halopsa": {
"command": "npx",
"args": ["@wyre-ai/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=xxx -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 (category_1only;category_2–category_4are rejected)halopsa_tickets_get- Get ticket detailshalopsa_tickets_create- Create a new ticket (optionalcategory_1–category_4)halopsa_tickets_update- Update an existing ticket (optionalcategory_1–category_4)halopsa_tickets_add_action- Add a note/action to a ticket. Supply time spent in minutes usingtime_minutes(preferred) or the deprecatedtimetakenalias. The server converts minutes to Halo decimal hours (15 minutes → 0.25 hours);time_minuteswins when both are supplied. Values must be finite and non-negative; zero is allowed.
Categories
Look up Halo ticket categories so triage can assign category_1–category_4 (the category name, matched to its level).
Tools:
halopsa_categories_list- List one page of ticket categories (limitdefaults to 50;page_nostarts at 1)halopsa_categories_get- Get a category by ID
Statuses
Look up Halo ticket statuses (id and name). Records are returned as Halo supplies them.
Tools:
halopsa_statuses_list- List one page of statuses (limitdefaults to 50;page_nostarts at 1)halopsa_statuses_get- Get a status by ID
Items
Read the Halo items catalog (products, services, bundles).
Tools:
halopsa_items_list- List one page of catalog items; filter bytype,category,supplier_id,inactive, orsearch(filters are sent to Halo as query parameters and are best-effort until checked against a tenant)halopsa_items_get- Get a catalog item by ID
Contracts
Read Halo client contracts. Records are returned as Halo supplies them.
Tools:
halopsa_contracts_list- List one page of contracts; filter byclient_id,site_id,status,type,inactive, orsearch(filters are sent to Halo as query parameters and are best-effort until checked against a tenant)halopsa_contracts_get- Get a contract by ID
Clients
Manage companies/clients in HaloPSA.
Tools:
halopsa_clients_list- List clientshalopsa_clients_get- Get client detailshalopsa_clients_create- Create a new clienthalopsa_clients_search- Search clients by name
Assets
Manage configuration items/assets.
Tools:
halopsa_assets_list- List assets with filtershalopsa_assets_get- Get asset detailshalopsa_assets_search- Search assetshalopsa_assets_list_types- List available asset types
Agents
View technicians and teams.
Tools:
halopsa_agents_list- List agents/technicianshalopsa_agents_get- Get agent detailshalopsa_teams_list- List teams
Invoices
View billing and invoices.
Tools:
halopsa_invoices_list- List invoices with filtershalopsa_invoices_get- Get invoice details
Navigation Tools
Always available:
halopsa_navigate- Select a domain to work withhalopsa_status- Show current state and credential statushalopsa_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 underlying @asachs01/node-halopsa client handles this automatically with request throttling.
License
Apache-2.0
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found