halopsa-mcp

A Rust-based Model Context Protocol server for HaloPSA. Gives AI assistants authenticated access to HaloPSA tickets, actions, and workflows through a standards-compliant MCP interface.

The server relays OAuth 2.1 to HaloPSA's own authorization endpoint, meaning users authenticate directly with HaloPSA and all API calls carry their real permissions. The server never sees passwords or handles credentials directly.

Features

• OAuth 2.1 relay with full PKCE (S256) support on both legs
• 18 MCP tools covering tickets, actions, workflows, reference data, and semantic search
• Workflow-aware actions — surfaces only the transitions valid at the ticket's current step
• Semantic search with permission filtering per authenticated user
• Encrypted token storage — HaloPSA tokens stored with AES-256-GCM in SQLite
• Hosted and on-premise HaloPSA instances supported
• Two MCP transports: SSE (classic) and Streamable HTTP (POST)
• Pluggable embedding providers: local fastembed, OpenAI-compatible API, or Ollama

Architecture

Cargo workspace with four crates:

The embedder runs as a separate service. It indexes tickets using a service account (Client Credentials flow) so the embedding corpus is complete. At query time, each result is verified against the requesting user's token before being returned, so users only see tickets they have access to.

Semantic search uses pgvector with an HNSW cosine-similarity index. The Docker Compose file pins pgvector/pgvector:pg16, which bundles Postgres 16 and the extension — no extra setup required.

Quick Start (Docker)

Copy .env.example to .env and fill in the required values (see Configuration below), then:

docker compose up -d

The server starts on port 8080. The embedder starts alongside it and begins indexing tickets in the background.

To use SSE transport with Claude Desktop or another MCP client, point it at:

http://your-host:8080/sse

For Streamable HTTP transport:

http://your-host:8080/mcp

Configuration

Copy .env.example to .env. Required variables:

Server defaults:

Semantic search (optional):

For OpenAI-compatible providers, also set HMCP_EMBED_API_KEY and optionally HMCP_EMBED_API_URL. For Ollama, set HMCP_EMBED_OLLAMA_URL.

See .env.example for all options with comments.

MCP Tools

Tickets

Actions

Workflow

Reference Data

User

Semantic Search (optional, requires HMCP_SEMANTIC_SEARCH=true)

Semantic Search

When semantic search is enabled, the embedder sidecar maintains a vector index of all tickets. Each ticket is chunked into a summary/metadata block and a details block, with per-action chunks added for ticket history. The embedder uses a service account with broad read access to keep the index complete.

At query time, semantic_search retrieves candidate chunks by vector similarity, then verifies each matching ticket against the requesting user's own HaloPSA token. Results that the user cannot access are filtered out before the response is returned. This means the index is shared but access is enforced per-user.

Supported providers:

• local (default) — fastembed running in-process, no external API needed. Default model: BAAI/bge-base-en-v1.5.
• openai — Any OpenAI-compatible embeddings API. Set HMCP_EMBED_API_KEY and optionally override HMCP_EMBED_API_URL for self-hosted models.
• ollama — Local Ollama instance. Set HMCP_EMBED_OLLAMA_URL.

OAuth Flow

The server implements a two-legged OAuth 2.1 relay:

1. The MCP client initiates authorization. The server redirects to HaloPSA's /auth/authorize with PKCE.
2. The user authenticates directly with HaloPSA. HaloPSA issues a code to the server's callback.
3. The server exchanges the code for HaloPSA tokens, encrypts them with AES-256-GCM, and stores them mapped to a new MCP access token.
4. Subsequent tool calls use the stored HaloPSA token. The MCP client only ever sees the MCP access token.

The server supports both hosted HaloPSA (where a tenant identifier is required) and on-premise instances (where HMCP_HALO_TENANT is left empty).

Building from Source

Requires Rust 1.82 or later.

git clone https://github.com/bees-roadhouse/halopsa-mcp
cd halopsa-mcp
cargo build --release

Binaries are written to target/release/hmcp-server and target/release/hmcp-embedder.

The release profile enables LTO, binary stripping, and size optimization (opt-level = "z").

To build Docker images directly:

# Server image
docker build --target server -t halopsa-mcp-server .

# Embedder image
docker build --target embedder -t halopsa-mcp-embedder .

Status

Early development. The scaffolding for Phase 1 is in place (ticket, action, workflow, and semantic tools stubbed; OAuth relay and SSE/Streamable HTTP transports wired up) but the server has not yet been run end-to-end against a live HaloPSA instance. Planned for later phases: assets, clients, contracts, and invoices.

License

MIT