claude-halopsa-mcp

PrecisionIT launcher for the HaloPSA MCP connector. Mirrors the Meraki connector pattern: the connector authenticates to Azure with the technician's own az login identity and pulls HaloPSA OAuth config from Azure Key Vault at runtime. No secrets ever land in the Claude config file.

The actual MCP server is the upstream package @adamhancock/halopsa-mcp; this repo is the Key Vault launcher that wraps it.

How it works

1. Claude Desktop / Claude Code spawns node mcp-keyvault-launch.js.

2. The launcher uses AzureCliCredential (the tech's az login session) to read four secrets from Key Vault — RW vault first, whole-set fallback to RO:

   | Vault secret | Env var injected | |-------------------|-------------------------| | HaloPsaUrl | HALOPSA_URL | | HaloPsaTenant | HALOPSA_TENANT | | HaloPsaClientId | HALOPSA_CLIENT_ID | | HaloPsaClientSecret | HALOPSA_CLIENT_SECRET |

3. With those in the environment, it spawns @adamhancock/halopsa-mcp over stdio. stdout is the MCP JSON-RPC channel; all launcher diagnostics go to stderr.

Vaults: PrecisionIT-MCP-RW (read-write techs) and PrecisionIT-MCP-RO (read-only techs). RW vs RO is an Entra entitlement, not a machine setting.

Prerequisites

• git

• Node.js 18+

• Azure CLI, signed in (az login) with an identity entitled to one of the vaults

• Claude Desktop and/or Claude Code

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/dspray/claude-halopsa-mcp/main/install/install.sh | bash

Windows (PowerShell)

powershell -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/dspray/claude-halopsa-mcp/main/install/install.ps1 -OutFile $env:TEMP\h.ps1; & $env:TEMP\h.ps1"

The installer resolves node's absolute path, clones this repo to ~/claude-halopsa-mcp, runs npm ci, and writes the halopsa entry into the Claude Desktop config (backing it up first) and Claude Code (via claude mcp add, if the CLI is present). It is idempotent.

After installing, fully quit and reopen Claude Desktop, then confirm the halopsa tools load and run a harmless read (e.g. "list a couple of Halo clients").

Manual config (if you skip the installer)

{
  "mcpServers": {
    "halopsa": {
      "command": "/absolute/path/to/node",
      "args": ["/Users/you/claude-halopsa-mcp/mcp-keyvault-launch.js"]
    }
  }
}

No env block — the launcher fetches everything at runtime.

Troubleshooting

• No tools after install: confirm a full quit + reopen (not just closing the window), and that the config was written to the app you're actually using.

• Credential error on stderr: az login session expired (az login again) or az isn't on the launcher's PATH.

• 401/403 from Halo on a working install: the OAuth token cache (~1 hour after a scope change). Disconnect and reconnect the connector to force a fresh token.

• Calls hang then time out: the MCP server wedged — fully quit and relaunch Claude Desktop.

Notes

• The connector authenticates as a shared PrecisionIT HaloPSA OAuth application; Halo action attribution reflects that app. Per-tech attribution here is at the Key Vault access layer (who pulled the secret), same as the Meraki connector.

• If you rename the Key Vault secrets, edit SECRET_MAP at the top of mcp-keyvault-launch.js to match.