Three fixes discovered during initial deployment against
interakt.halopsa.com:
- halo-client: include scope=all in the client_credentials token
request. Without it Halo issues a token with no read scopes — every
/api/* call fails authorization despite a successful exchange.
Manifested as the original "permissions issue".
- tools: add pageinate=true to every list_* call. Halo ignores
page_size unless pagination is explicitly enabled, so requesting
page_size=5 was returning the server-side default of 50.
- tools: project list_clients to a summary shape (id, name, top-level,
status, customer_relationship names). Full Halo client records are
~18 KB each; a 5-row page was 89 KB, exceeding tool-result budgets.
Pass full=true for the original payload; get_client still returns
full detail.
Also: switch list_clients filter from inactive=false to the canonical
includeinactive=false, and ship start.sh (the wrapper documented in
CLAUDE.md Step 4) so downstream setups don't have to author it.
Verified end-to-end against the live instance: GET /Client with
pageinate=true&page_size=3 now returns exactly 3 records and
record_count=122 (total active clients).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
TypeScript MCP server exposing 18 tools for querying a Halo PSA
instance via OAuth 2.0 Client Credentials:
- Tickets / actions (list, get, time entries)
- Clients / sites (list, get)
- Contracts (list, get — recurring service agreements)
- Invoices — both one-off (list, get) and recurring (list, get)
- Projects (list, get)
- Assets / configuration items (list, get)
- Agents, reports (list)
- revenue_breakdown — composite tool that cross-references contracts,
recurring invoices, and one-off invoices to separate recurring
(MRR) from non-recurring revenue per client
Build artefacts verified: npm install clean (0 vulnerabilities, 107
pkgs), npm run build produces dist/*.js with no TS errors, server
boots and announces 'Halo PSA MCP server running on stdio'.
Shipping with Dockerfile (multi-stage, alpine), .env.example,
README.md (user-facing), and CLAUDE.md (deployment briefing for
downstream Claude Code setup on customer machines).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
