AI Assistant for ServiceFusion: Query Jobs by Chat, Not Clicks
The Situation
A field service operator running on ServiceFusion wanted dispatchers and office staff to stop clicking through menus every time they needed to check a customer's job history, pull open estimates, or see which technician was assigned to a job. The team was already using Claude for other tasks. The obvious next step: let Claude talk directly to ServiceFusion.
The Problem
ServiceFusion exposes a REST API, but AI assistants cannot call it directly. The Model Context Protocol (MCP) is the emerging standard for giving AI clients structured access to external tools, and no MCP server existed for ServiceFusion. Building one correctly meant solving three problems at once:
OAuth2 token lifecycle. ServiceFusion uses short-lived access tokens that expire and must be refreshed transparently, so the AI never hits an auth failure mid-conversation.
Multi-tenancy. A single server instance had to isolate credentials and API calls for multiple companies, each with their own ServiceFusion account.
Self-service onboarding. The operator did not want to configure every new tenant manually.
The Solution
I built a multi-tenant MCP server in Node.js and TypeScript that sits between AI clients (Claude, Cursor, ChatGPT) and ServiceFusion. It exposes 13 structured tools covering the core entities dispatchers actually use: customers, jobs, estimates, technicians, and equipment.
The server handles two independent OAuth2 layers. One authenticates incoming AI clients to the MCP server. The second manages the server's own ServiceFusion tokens, including automatic refresh with a concurrency lock so simultaneous requests never trigger duplicate refreshes.
All sensitive credentials (client IDs, secrets, tokens) are encrypted at rest with AES-256-GCM in Supabase PostgreSQL. New tenants self-register via REST API, confirm via OTP, and supply their ServiceFusion credentials to activate. No manual operator work per signup.
A lightweight admin panel lets the operator view usage per tenant, adjust rate limits, and activate or deactivate accounts.
Tech Stack: Node.js 20, TypeScript, @ modelcontextprotocol/sdk, Express, Supabase (PostgreSQL), AES-256-GCM encryption, Zod, Winston, Docker, nginx, Let's Encrypt
The Results
13 MCP tools live across customers, jobs, estimates, technicians, and equipment
Zero manual setup per tenant. Self-service OTP registration and activation flow
Transparent OAuth2. Expired tokens refresh automatically with race-condition protection
Per-tenant rate limits (free, pro, enterprise tiers) enforced at the request layer
Full usage tracking (tool name, endpoint, status code, response time) logged per tenant for billing and analytics
Deployed to production on Hetzner VPS behind nginx with SSL, coexisting with a sibling MCP server on the same host
How It Works
1. Tenant POSTs to /api/register with company name and email, receives a 6-digit OTP
2. Tenant confirms via /api/confirm, then activates by supplying ServiceFusion OAuth credentials
3. Credentials are encrypted with AES-256-GCM and stored in Supabase
4. AI client (Claude, Cursor) calls /mcp with a bearer token; middleware identifies the tenant and checks rate limit
5. On tool invocation, the server checks token validity and refreshes automatically if expired
6. Structured response flows back to the AI client, and the call is logged for usage analytics
A field service operator running on ServiceFusion wanted dispatchers and office staff to stop clicking through menus every time they needed to check a customer's job history, pull open estimates, or see which technician was assigned to a job. The team was already using Claude for other tasks. The obvious next step: let Claude talk directly to ServiceFusion.
The Problem
ServiceFusion exposes a REST API, but AI assistants cannot call it directly. The Model Context Protocol (MCP) is the emerging standard for giving AI clients structured access to external tools, and no MCP server existed for ServiceFusion. Building one correctly meant solving three problems at once:
OAuth2 token lifecycle. ServiceFusion uses short-lived access tokens that expire and must be refreshed transparently, so the AI never hits an auth failure mid-conversation.
Multi-tenancy. A single server instance had to isolate credentials and API calls for multiple companies, each with their own ServiceFusion account.
Self-service onboarding. The operator did not want to configure every new tenant manually.
The Solution
I built a multi-tenant MCP server in Node.js and TypeScript that sits between AI clients (Claude, Cursor, ChatGPT) and ServiceFusion. It exposes 13 structured tools covering the core entities dispatchers actually use: customers, jobs, estimates, technicians, and equipment.
The server handles two independent OAuth2 layers. One authenticates incoming AI clients to the MCP server. The second manages the server's own ServiceFusion tokens, including automatic refresh with a concurrency lock so simultaneous requests never trigger duplicate refreshes.
All sensitive credentials (client IDs, secrets, tokens) are encrypted at rest with AES-256-GCM in Supabase PostgreSQL. New tenants self-register via REST API, confirm via OTP, and supply their ServiceFusion credentials to activate. No manual operator work per signup.
A lightweight admin panel lets the operator view usage per tenant, adjust rate limits, and activate or deactivate accounts.
Tech Stack: Node.js 20, TypeScript, @ modelcontextprotocol/sdk, Express, Supabase (PostgreSQL), AES-256-GCM encryption, Zod, Winston, Docker, nginx, Let's Encrypt
The Results
13 MCP tools live across customers, jobs, estimates, technicians, and equipment
Zero manual setup per tenant. Self-service OTP registration and activation flow
Transparent OAuth2. Expired tokens refresh automatically with race-condition protection
Per-tenant rate limits (free, pro, enterprise tiers) enforced at the request layer
Full usage tracking (tool name, endpoint, status code, response time) logged per tenant for billing and analytics
Deployed to production on Hetzner VPS behind nginx with SSL, coexisting with a sibling MCP server on the same host
How It Works
1. Tenant POSTs to /api/register with company name and email, receives a 6-digit OTP
2. Tenant confirms via /api/confirm, then activates by supplying ServiceFusion OAuth credentials
3. Credentials are encrypted with AES-256-GCM and stored in Supabase
4. AI client (Claude, Cursor) calls /mcp with a bearer token; middleware identifies the tenant and checks rate limit
5. On tool invocation, the server checks token validity and refreshes automatically if expired
6. Structured response flows back to the AI client, and the call is logged for usage analytics
Харьков 
Свободен для работы