ConnectWise MCP: Complete Developer Guide to Model Context Protocol Integration

import axios from 'axios';
import * as crypto from 'crypto';

interface ConnectWiseMCPConfig {
  clientId: string;
  clientSecret: string;
  companyId: string;
  baseUrl: string;
  apiVersion: string;
}

interface TokenResponse {
  access_token: string;
  refresh_token: string;
  expires_in: number;
  token_type: string;
}

class ConnectWiseMCPAuth {
  private config: ConnectWiseMCPConfig;
  private accessToken: string | null = null;
  private refreshToken: string | null = null;
  private tokenExpiry: Date | null = null;

  constructor(config: ConnectWiseMCPConfig) {
    this.config = config;
  }

  /**
   * Authenticate using OAuth 2.0 Client Credentials flow
   * Implements secure token acquisition for ConnectWise MCP
   */
  async authenticate(): Promise {
    if (this.isTokenValid()) {
      return this.accessToken!;
    }

    try {
      const authUrl = `${this.config.baseUrl}/v${this.config.apiVersion}/oauth/token`;
      
      const response = await axios.post(
        authUrl,
        {
          grant_type: 'client_credentials',
          client_id: this.config.clientId,
          client_secret: this.config.clientSecret,
          scope: 'MCP.Read MCP.Write MCP.Execute'
        },
        {
          headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Accept': 'application/json'
          }
        }
      );

      this.accessToken = response.data.access_token;
      this.refreshToken = response.data.refresh_token;
      this.tokenExpiry = new Date(Date.now() + response.data.expires_in * 1000);

      console.log('ConnectWise MCP authentication successful');
      return this.accessToken;
    } catch (error: any) {
      console.error('ConnectWise MCP authentication failed:', error.message);
      throw new Error(`Authentication failed: ${error.response?.data?.message || error.message}`);
    }
  }

  /**
   * Check if current access token is still valid
   */
  private isTokenValid(): boolean {
    if (!this.accessToken || !this.tokenExpiry) {
      return false;
    }
    // Add 5-minute buffer to prevent edge case failures
    const bufferTime = 5 * 60 * 1000;
    return this.tokenExpiry.getTime() - bufferTime > Date.now();
  }

  /**
   * Refresh expired access token using refresh token
   */
  async refreshAccessToken(): Promise {
    if (!this.refreshToken) {
      return this.authenticate();
    }

    try {
      const refreshUrl = `${this.config.baseUrl}/v${this.config.apiVersion}/oauth/token`;
      
      const response = await axios.post(
        refreshUrl,
        {
          grant_type: 'refresh_token',
          refresh_token: this.refreshToken,
          client_id: this.config.clientId,
          client_secret: this.config.clientSecret
        }
      );

      this.accessToken = response.data.access_token;
      this.tokenExpiry = new Date(Date.now() + response.data.expires_in * 1000);

      return this.accessToken;
    } catch (error) {
      console.error('Token refresh failed, re-authenticating...');
      return this.authenticate();
    }
  }

  /**
   * Get current valid access token
   */
  async getAccessToken(): Promise {
    if (!this.isTokenValid()) {
      return this.refreshAccessToken();
    }
    return this.accessToken!;
  }
}

import axios, { AxiosInstance } from 'axios';

interface Ticket {
  id?: number;
  summary: string;
  company: { id: number; name?: string };
  board: { id: number; name?: string };
  status: { id: number; name?: string };
  priority: { id: number; name?: string };
  serviceType?: { id: number; name?: string };
  severity?: string;
  impact?: string;
  initialDescription?: string;
  contactName?: string;
  contactEmailAddress?: string;
  recordType?: string;
}

interface TicketSearchParams {
  conditions?: string;
  orderBy?: string;
  page?: number;
  pageSize?: number;
  fields?: string;
}

class ConnectWiseMCPTicketClient {
  private axiosInstance: AxiosInstance;
  private auth: ConnectWiseMCPAuth;

  constructor(auth: ConnectWiseMCPAuth, config: ConnectWiseMCPConfig) {
    this.auth = auth;
    this.axiosInstance = axios.create({
      baseURL: `${config.baseUrl}/v${config.apiVersion}/company/${config.companyId}`,
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    // Add request interceptor for authentication
    this.axiosInstance.interceptors.request.use(async (config) => {
      const token = await this.auth.getAccessToken();
      config.headers.Authorization = `Bearer ${token}`;
      return config;
    });
  }

  /**
   * Create a new service ticket in ConnectWise
   * Implements MCP protocol for ticket creation
   */
  async createTicket(ticketData: Ticket): Promise {
    try {
      const response = await this.axiosInstance.post(
        '/service/tickets',
        ticketData
      );
      
      console.log(`ConnectWise MCP: Ticket created with ID ${response.data.id}`);
      return response.data;
    } catch (error: any) {
      console.error('ConnectWise MCP ticket creation failed:', error.message);
      throw new Error(`Ticket creation failed: ${error.response?.data?.message || error.message}`);
    }
  }

  /**
   * Retrieve ticket by ID with full context
   */
  async getTicket(ticketId: number, fields?: string[]): Promise {
    try {
      const params = fields ? { fields: fields.join(',') } : {};
      const response = await this.axiosInstance.get(
        `/service/tickets/${ticketId}`,
        { params }
      );
      
      return response.data;
    } catch (error: any) {
      if (error.response?.status === 404) {
        throw new Error(`Ticket ${ticketId} not found in ConnectWise`);
      }
      throw new Error(`Failed to retrieve ticket: ${error.message}`);
    }
  }

  /**
   * Search tickets using ConnectWise conditions syntax
   * Enables AI models to query tickets based on context
   */
  async searchTickets(params: TicketSearchParams): Promise {
    try {
      const response = await this.axiosInstance.get(
        '/service/tickets',
        { 
          params: {
            conditions: params.conditions || '',
            orderBy: params.orderBy || 'id desc',
            page: params.page || 1,
            pageSize: params.pageSize || 25,
            fields: params.fields || 'id,summary,status,priority,company,contactName'
          }
        }
      );
      
      console.log(`ConnectWise MCP: Retrieved ${response.data.length} tickets`);
      return response.data;
    } catch (error: any) {
      console.error('ConnectWise MCP ticket search failed:', error.message);
      throw new Error(`Ticket search failed: ${error.response?.data?.message || error.message}`);
    }
  }

  /**
   * Update existing ticket with new information
   * Supports partial updates through patch operations
   */
  async updateTicket(ticketId: number, updates: Partial): Promise {
    try {
      const response = await this.axiosInstance.patch(
        `/service/tickets/${ticketId}`,
        updates
      );
      
      console.log(`ConnectWise MCP: Ticket ${ticketId} updated successfully`);
      return response.data;
    } catch (error: any) {
      console.error('ConnectWise MCP ticket update failed:', error.message);
      throw new Error(`Ticket update failed: ${error.response?.data?.message || error.message}`);
    }
  }

  /**
   * Add a note to a ticket for context tracking
   */
  async addTicketNote(ticketId: number, noteText: string, internalFlag: boolean = false): Promise {
    try {
      await this.axiosInstance.post(
        `/service/tickets/${ticketId}/notes`,
        {
          text: noteText,
          internalAnalysisFlag: internalFlag,
          externalFlag: !internalFlag
        }
      );
      
      console.log(`ConnectWise MCP: Note added to ticket ${ticketId}`);
    } catch (error: any) {
      console.error('ConnectWise MCP note creation failed:', error.message);
      throw new Error(`Failed to add note: ${error.message}`);
    }
  }
}

interface Company {
id: number;
name: string;
identifier: string;
status: { id: number; name: string };
types?: Array<{ id: number; name: string }>;
addressLine1?: string;
city?: string;
state?: string;
zip?: string;
phoneNumber?: string;
website?: string;
territory?: { id: number; name: string };
accountNumber?: string;
}
interface Contact {
id: number;
firstName: string;
lastName: string;
company: { id: number; name: string };
type?: { id: number; name: string };
relationship?: { id: number; name: string };
communicationItems?: Array<{
type: string;
value: string;
defaultFlag: boolean;
}>;
title?: string;
department?: string;
}
class ConnectWiseMCPClientManager {
private axiosInstance: AxiosInstance;
private auth: ConnectWiseMCPAuth;
private contextCache: Map = new Map();
constructor(auth: ConnectWiseMCPAuth, config: ConnectWiseMCPConfig) {
this.auth = auth;
this.axiosInstance = axios.create({
baseURL: ${config.baseUrl}/v${config.apiVersion}/company/${config.companyId},
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
});
this.axiosInstance.interceptors.request.use(async (config) => {
  const token = await this.auth.getAccessToken();
  config.headers.Authorization = `Bearer ${token}`;
  return config;
});
}
/**

Retrieve company information with caching for performance
Implements context caching for ConnectWise MCP
*/
async getCompany(companyId: number, useCache: boolean = true): Promise {
const cacheKey = company_${companyId};

if (useCache && this.contextCache.has(cacheKey)) {
  const cached = this.contextCache.get(cacheKey);
  if (Date.now() - cached.timestamp < 300000) { // 5-minute cache
    console.log(`ConnectWise MCP: Using cached company data for ${companyId}`);
    return cached.data;
  }
}

try {
  const response = await this.axiosInstance.get(
    `/company/companies/${companyId}`
  );
  
  this.contextCache.set(cacheKey, {
    data: response.data,
    timestamp: Date.now()
  });
  
  return response.data;
} catch (error: any) {
  console.error('ConnectWise MCP company retrieval failed:', error.message);
  throw new Error(`Failed to retrieve company: ${error.message}`);
}
}
/**

Search companies by name or identifier
Enables AI models to resolve company references
*/
async searchCompanies(searchTerm: string): Promise {
try {
const conditions = name contains "${searchTerm}" OR identifier contains "${searchTerm}";
const response = await this.axiosInstance.get(
'/company/companies',
{
params: {
conditions,
pageSize: 10,
orderBy: 'name'
}
}
);
console.log(ConnectWise MCP: Found ${response.data.length} matching companies);
return response.data;
} catch (error: any) {
console.error('ConnectWise MCP company search failed:', error.message);
throw new Error(Company search failed: ${error.message});
}
}

/**

Get all contacts for a specific company
Maintains relationship context for AI interactions
*/
async getCompanyContacts(companyId: number): Promise {
try {
const response = await this.axiosInstance.get(
/company/contacts,
{
params: {
conditions: company/id = ${companyId},
pageSize: 100,
orderBy: 'lastName,firstName'
}
}
);
return response.data;
} catch (error: any) {
console.error('ConnectWise MCP contact retrieval failed:', error.message);
throw new Error(Failed to retrieve contacts: ${error.message});
}
}

/**

Get comprehensive company context including tickets and contacts
Provides full context for AI decision-making
*/
async getCompanyContext(companyId: number): Promise<{
company: Company;
contacts: Contact[];
recentTickets: Ticket[];
}> {
try {
const [company, contacts] = await Promise.all([
this.getCompany(companyId),
this.getCompanyContacts(companyId)
]);
// Fetch recent tickets for this company
const ticketClient = new ConnectWiseMCPTicketClient(this.auth, this.config);
const recentTickets = await ticketClient.searchTickets({
conditions: company/id = ${companyId},
orderBy: 'dateEntered desc',
pageSize: 10
});
console.log(ConnectWise MCP: Retrieved full context for company ${companyId});
return {
company,
contacts,
recentTickets
};
} catch (error: any) {
console.error('ConnectWise MCP context retrieval failed:', error.message);
throw new Error(Failed to retrieve company context: ${error.message});
}
}

/**

Clear context cache (useful for testing or forced refresh)
*/
clearCache(pattern?: string): void {
if (pattern) {
for (const key of this.contextCache.keys()) {
if (key.includes(pattern)) {
this.contextCache.delete(key);
}
}
} else {
this.contextCache.clear();
}
console.log('ConnectWise MCP: Context cache cleared');
}
}

import express, { Request, Response } from 'express';


import crypto from 'crypto';
interface WebhookPayload {
ID: number;
Action: 'added' | 'updated' | 'deleted';
Entity: string;
Type: string;
MemberId: number;
CompanyId: string;
FromUrl: string;
}
interface AIProcessingResult {
action: string;
confidence: number;
suggestedResponse?: string;
nextSteps?: string[];
}
class ConnectWiseMCPWebhookHandler {
private app: express.Application;
private webhookSecret: string;
private mcpClient: ConnectWiseMCPTicketClient;
private aiProcessor: AITicketProcessor;
constructor(
webhookSecret: string,
mcpClient: ConnectWiseMCPTicketClient,
aiProcessor: AITicketProcessor
) {
this.app = express();
this.webhookSecret = webhookSecret;
this.mcpClient = mcpClient;
this.aiProcessor = aiProcessor;
this.setupMiddleware();
this.setupRoutes();
}
private setupMiddleware(): void {
this.app.use(express.json());
// Webhook signature verification middleware
this.app.use('/webhooks/connectwise', (req: Request, res: Response, next) => {
  const signature = req.headers['x-connectwise-signature'] as string;
  
  if (!signature) {
    return res.status(401).json({ error: 'Missing signature' });
  }

  const payload = JSON.stringify(req.body);
  const expectedSignature = crypto
    .createHmac('sha256', this.webhookSecret)
    .update(payload)
    .digest('hex');

  if (signature !== expectedSignature) {
    console.error('ConnectWise MCP: Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }

  next();
});
}
private setupRoutes(): void {
/**
* Handle incoming ConnectWise webhooks
* Processes events and triggers AI-powered automation
*/
this.app.post('/webhooks/connectwise', async (req: Request, res: Response) => {
const payload: WebhookPayload = req.body;
  // Immediately acknowledge webhook receipt
  res.status(200).json({ received: true });

  try {
    console.log(`ConnectWise MCP: Processing ${payload.Action} event for ${payload.Entity}`);
    
    // Process webhook asynchronously
    await this.processWebhook(payload);
  } catch (error: any) {
    console.error('ConnectWise MCP webhook processing error:', error.message);
    // Log error but don't fail webhook acknowledgment
  }
});

/**
 * Health check endpoint
 */
this.app.get('/health', (req: Request, res: Response) => {
  res.status(200).json({ 
    status: 'healthy',
    service: 'connectwise-mcp-webhook-handler',
    timestamp: new Date().toISOString()
  });
});
}
/**

Process webhook payload and trigger appropriate actions
*/
private async processWebhook(payload: WebhookPayload): Promise {
switch (payload.Entity) {
case 'Ticket':
await this.handleTicketEvent(payload);
break;
case 'TimeEntry':
await this.handleTimeEntryEvent(payload);
break;
case 'Company':
await this.handleCompanyEvent(payload);
break;
default:
console.log(ConnectWise MCP: Unhandled entity type ${payload.Entity});
}
}

/**

Handle ticket-related events with AI processing
*/
private async handleTicketEvent(payload: WebhookPayload): Promise {
if (payload.Action === 'added') {
// New ticket created - analyze and suggest actions
const ticket = await this.mcpClient.getTicket(payload.ID);
console.log(ConnectWise MCP: Analyzing new ticket ${ticket.id});
const aiResult: AIProcessingResult = await this.aiProcessor.analyzeTicket(ticket);
if (aiResult.confidence > 0.8) {
// High confidence - auto-assign or auto-respond
if (aiResult.suggestedResponse) {
await this.mcpClient.addTicketNote(
ticket.id!,
AI Analysis (${aiResult.confidence.toFixed(2)} confidence):\n${aiResult.suggestedResponse},
true // Internal note
);
}
// Update ticket based on AI recommendations
if (aiResult.nextSteps && aiResult.nextSteps.length > 0) {
const updates: Partial = {};
 // AI can suggest priority changes, assignments, etc.
 if (aiResult.action === 'escalate') {
   updates.priority = { id: 1, name: 'Critical' };
 }
 
 if (Object.keys(updates).length > 0) {
   await this.mcpClient.updateTicket(ticket.id!, updates);
 }
}
}
} else if (payload.Action === 'updated') {
// Ticket updated - check if AI attention needed
console.log(ConnectWise MCP: Ticket ${payload.ID} updated);
}
}

/**

Handle time entry events
*/
private async handleTimeEntryEvent(payload: WebhookPayload): Promise {
console.log(ConnectWise MCP: Time entry ${payload.Action} - ID ${payload.ID});
// Implement time entry analysis logic
}

/**

Handle company events
*/
private async handleCompanyEvent(payload: WebhookPayload): Promise {
console.log(ConnectWise MCP: Company ${payload.Action} - ID ${payload.ID});
// Implement company change analysis logic
}

/**

Start the webhook server
*/
start(port: number = 3000): void {
this.app.listen(port, () => {
console.log(ConnectWise MCP webhook handler listening on port ${port});
});
}
}

/**

Mock AI processor interface (would integrate with actual AI service)
*/
class AITicketProcessor {
async analyzeTicket(ticket: Ticket): Promise {
// In production, this would call an AI model API
// For demonstration, return mock analysis
return {
action: 'analyze',
confidence: 0.85,
suggestedResponse: 'This ticket appears to be a password reset request. Standard resolution time: 15 minutes.',
nextSteps: ['Verify user identity', 'Reset password', 'Send confirmation email']
};
}
}