ConnectWise API Orchestration Protocol (MCP) Server

This Model Context Protocol (MCP) server establishes a unified control plane for all interactions involving the ConnectWise Manage API. It significantly simplifies endpoint discovery, request execution, and lifecycle management for both application developers and autonomous AI agents.

Primary Functions

• Endpoint Mapping: Locate and investigate ConnectWise API resources using descriptive keywords or natural language queries.
• Streamlined Invocation: Execute API calls, benefiting from intelligent parameter scaffolding and automated failure remediation.
• High-Velocity Cache (Fast Memory): Persistent storage and instant recall of frequently utilized API invocation patterns, boosting workflow throughput.
• Unrestricted Access Layer: Capability to dispatch completely custom API requests, offering granular dominion over URIs, HTTP methods, and payload structures.

Distinctive Characteristics

• Persistence Layer for Discovery: Leverages a persistent SQLite repository, populated from the official ConnectWise API manifest JSON, ensuring swift and efficient resource lookups.
• Conversational Querying: Enables users to pinpoint necessary API endpoints using vernacular descriptions of the desired business outcome.
• Hierarchical Organization: API endpoints are logically segmented and navigable via functional domains.
• Exhaustive Metadata Access: Provides immediate access to rich documentation for every endpoint, encompassing required parameters, data schemas, and response profiles.
• Usage-Driven Optimization: System dynamically prioritizes and retains high-value API interactions based on historical usage telemetry.

Deployment and Configuration Guide

Prerequisites

• Python interpreter, version 3.10 or newer.
• Valid authentication credentials for the target ConnectWise Manage instance.
• The requisite ConnectWise API definition artifact (manage.json) – bundled within the source repository.

Installation Pathways

Option 1: Via GitHub NPM Distribution (Preferred)

Installation can be achieved directly via the Node Package Manager:

bash npm install -g jasondsmith72/CWM-API-Gateway-MCP

This streamlined approach handles dependency resolution automatically and simplifies the configuration linkage within environments like Claude Desktop.

Option 2: Manual Source Repository Setup

Windows Operating System

1. Acquire the Source Code: bash git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP

2. Install Local Package Dependencies: bash pip install -e .

macOS Environment

For the NPM installation method, execute:

bash npm install -g jasondsmith72/CWM-API-Gateway-MCP

For manual installation procedures:

1. Ensure Python 3.10+ is present: bash

Utilizing Homebrew

brew install python@3.10

Or employing pyenv

brew install pyenv pyenv install 3.10.0 pyenv global 3.10.0

1. Clone the Repository: bash git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP

2. Establish a Virtual Environment (Recommended Practice): bash python3 -m venv venv source venv/bin/activate

3. Install Dependencies: bash pip install -e .

Linux (Debian/Ubuntu Variants)

For the NPM distribution path:

bash sudo npm install -g jasondsmith72/CWM-API-Gateway-MCP

For a direct repository installation:

1. Install Python 3.10+ Dependencies: bash

For Ubuntu 22.04 and newer

sudo apt update sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip

For preceding Ubuntu/Debian versions

sudo add-apt-repository ppa:deadsnakes/ppa sudo apt update sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip

1. Obtain Repository Copy: bash git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP

2. Activate Virtual Environment: bash python3.10 -m venv venv source venv/bin/activate

3. Execute Installation Command: bash pip install -e .

Post-Installation Configuration

Following successful setup on any operating system, configure the following environment variables with your ConnectWise credentials:

CONNECTWISE_API_URL=https://na.myconnectwise.net/v4_6_release/apis/3.0 CONNECTWISE_COMPANY_ID=your_company_id CONNECTWISE_PUBLIC_KEY=your_public_key CONNECTWISE_PRIVATE_KEY=your_private_key CONNECTWISE_AUTH_PREFIX=yourprefix+ # Mandatory prefix for CW authentication username construction

These variables drive the authentication schema:

• CONNECTWISE_API_URL: The base URI for all service interactions (e.g., constructing url = f"{API_URL}{endpoint}" for /service/tickets).

• CONNECTWISE_COMPANY_ID: Populates the mandatory 'clientId' header used for tenant identification.

• CONNECTWISE_PUBLIC_KEY & CONNECTWISE_PRIVATE_KEY: Combined with the prefix to form the Basic Auth payload.

username_stem = f"{AUTH_PREFIX}{PUBLIC_KEY}" password_stem = PRIVATE_KEY credentials_string = f"{username_stem}:{password_stem}"

• CONNECTWISE_AUTH_PREFIX: The required initial string segment prepended to the public key when formulating the authentication username.

The final HTTP header package transmitted with each API transaction includes:

'Authorization': 'Basic [base64 encoded credentials]' 'clientId': 'your_company_id' 'Content-Type': 'application/json'

Integration with Claude Desktop

Integration methods cater to different deployment scenarios:

Method 1: NPM Package Integration (Recommended)

After installing globally via NPM:

Configure claude_desktop_config.json as follows:

{ "mcpServers": { "CW-Manage-API-Orchestrator-MCP": { "command": "npx", "args": [ "-y", "@jasondsmith72/CWM-API-Gateway-MCP" ], "env": { "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0", "CONNECTWISE_COMPANY_ID": "your_company_id", "CONNECTWISE_PUBLIC_KEY": "your_public_key", "CONNECTWISE_PRIVATE_KEY": "your_private_key", "CONNECTWISE_AUTH_PREFIX": "yourprefix+" } } } }

Method 2: Node.js Script Execution (Alternative)

If the repository was cloned and dependencies installed:

{ "mcpServers": { "CW-Manage-API-Orchestrator-MCP": { "command": "node", "args": ["C:/path/to/CWM-API-Gateway-MCP/bin/server.js"], "env": { "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0", "CONNECTWISE_COMPANY_ID": "your_company_id", "CONNECTWISE_PUBLIC_KEY": "your_public_key", "CONNECTWISE_PRIVATE_KEY": "your_private_key", "CONNECTWISE_AUTH_PREFIX": "yourprefix+" } } } }

Method 3: Direct Python Script Invocation

For execution via the primary Python runtime:

{ "mcpServers": { "CW-Manage-API-Orchestrator-MCP": { "command": "python", "args": ["C:/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"], "env": { "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0", "CONNECTWISE_COMPANY_ID": "your_company_id", "CONNECTWISE_PUBLIC_KEY": "your_public_key", "CONNECTWISE_PRIVATE_KEY": "your_private_key", "CONNECTWISE_AUTH_PREFIX": "yourprefix+" } } } }

For Unix-like systems (macOS/Linux):

{ "mcpServers": { "CW-Manage-API-Orchestrator-MCP": { "command": "python3", "args": ["/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"], "env": { "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0", "CONNECTWISE_COMPANY_ID": "your_company_id", "CONNECTWISE_PUBLIC_KEY": "your_public_key", "CONNECTWISE_PRIVATE_KEY": "your_private_key", "CONNECTWISE_AUTH_PREFIX": "yourprefix+" } } } }

To initiate the server for immediate functional testing:

bash

If installed via NPM

cwm-api-gateway-mcp

If executing the Node wrapper

node bin/server.js

If invoking the Python core script

Windows

python api_gateway_server.py

macOS/Linux

python3 api_gateway_server.py

Integrated Function Set

The API Orchestrator MCP exposes the following functional toolsets for interacting with ConnectWise:

API Topology Retrieval Tools

Tool Name	Purpose
query_api_endpoints	Search for API resources based on descriptive criteria (keywords)
semantic_endpoint_locator	Pinpoint endpoints using narrative descriptions of required functionality
enumerate_api_domains	Retrieve a list of all high-level functional API categories
fetch_domain_resources	List all available endpoints nested within a specified functional domain
resolve_resource_metadata	Obtain granular specifications for an individual API endpoint (params, schema)

API Invocation Utilities

Tool Name	Purpose
dispatch_api_operation	Execute an API interaction specifying URI path, HTTP verb, input parameters, and payload data
send_unmediated_payload	Transmit a raw request formatted as "METHOD /path [JSON payload]"

Rapid-Recall Cache Tools (Fast Memory)

Tool Name	Purpose
cache_invocation_pattern	Manually commit a successful API call structure to the High-Velocity Cache
display_cached_invocations	List all entries currently stored within the Rapid-Recall Cache
discard_cached_entry	Remove a specified invocation record from the cache
flush_rapid_recall_system	Erase the entire contents of the High-Velocity Cache

Operational Examples

Finding Endpoints Related to Service Tickets

python query_api_endpoints("service tickets")

Locating Resources via Natural Language

python semantic_endpoint_locator("retrieve all unresolved service requests flagged with critical severity")

Performing a Data Retrieval (GET)

python dispatch_api_operation( "/service/tickets", "GET", {"conditions": "status/name='New' AND priority/name='Critical'"} )

Creating a New Work Order Record

python dispatch_api_operation( "/service/tickets", "POST", None, # Query parameters omitted { "summary": "Urgent Network Outage", "board": {"id": 10}, "company": {"id": 55}, "status": {"id": 1}, "priority": {"id": 5} } )

Inspecting Cached Operations

python display_cached_invocations()

Persisting a Reusable Query Pattern

python cache_invocation_pattern( "/service/tickets", "GET", "Query for all critical open tickets", {"conditions": "status/name='Open' and priority/name='Critical'"} )

High-Velocity Cache (Fast Memory) Deep Dive

The Fast Memory feature is engineered to archive and instantly recall frequently executed API sequences, delivering substantial workflow optimization benefits:

Advantages

• Efficiency Gain: Bypasses the need to recall complex endpoint structures or verbose parameter sets.
• Fidelity Maintenance: Reusing proven, successful invocation payloads minimizes execution errors.
• Intelligent Caching: The system learns the operational utility of stored calls.
• Stateful Recall: Saved parameter sets and request bodies are preserved for subsequent reuse.

Operational Flow

1. Automatic Persistence Prompt: Upon successful execution of an API call, the system may prompt for archival into Fast Memory.
2. Preemptive Matching: Subsequent calls targeting the same resource check the cache first.
3. Default Parameter Application: If a user omits parameters for a known operation, the system defaults to cached values.
4. Usage Metric Tracking: The system increments a counter for each invocation retrieved from the cache, refining prioritization.

Cache Management Tools

• Review Contents: display_cached_invocations()
• Search Cache: display_cached_invocations("search term")
• Purge Item: discard_cached_entry(record_identifier)
• Total Wipe: flush_rapid_recall_system()

Technical Implementation

The cache persistence layer is managed via a dedicated SQLite schema (fast_memory_api.db) storing:

• Endpoint paths and HTTP verbs.
• Parameters and request bodies serialized as JSON.
• Performance metrics (usage count, last access timestamp).
• User-defined descriptive labels.

Schema Fields: id, description, path, method, params (JSON), data (JSON), timestamp, usage_count.

Troubleshooting Guide

Common Execution Failures

Missing Database Manifest

Error: API Discovery Index not located at [path] Action required: Execute the 'build_database.py' utility referencing your ConnectWise API schema file.

Remedy: Execute the database generation script: bash python build_database.py /path/to/your/manage.json

HTTP 401: Authentication Failure

HTTP error 401: Unauthorized

Remedy: Scrutinize the defined environment variables for credential validity: - Validate the integrity of CONNECTWISE_COMPANY_ID, CONNECTWISE_PUBLIC_KEY, and CONNECTWISE_PRIVATE_KEY. - Confirm that the associated API key possesses requisite permissions within the ConnectWise portal. - Verify that CONNECTWISE_AUTH_PREFIX aligns with ConnectWise's expected format.

Request Timeout Issues

Request exceeded time limit. ConnectWise API latency suspected.

Remedy: - Check network connectivity status. - The ConnectWise service layer might be under elevated load. - For voluminous data retrievals, incorporate more granular filtering criteria into the query parameters.

Diagnostic Artifacts

Log File Locations

• Primary Activity Log: api_gateway/api_gateway.log
• Data Stores:
• API Definition Index: api_gateway/connectwise_api.db
• Rapid-Recall Cache: api_gateway/fast_memory_api.db

Database Integrity Check

Confirm the API index is sound and queryable: bash python test_database.py

This command outputs summary statistics, verifying connectivity to the discovery database.

Performance Tuning and Advanced Query Construction

To maximize throughput when interacting with the ConnectWise API:

1. Apply Focused Filtering: Restrict results using precise condition syntax. python dispatch_api_operation("/service/tickets", "GET", { "conditions": "status/name='New' AND dateCreatedUTC > '[2024-01-01T00:00:00Z]'" })

2. Specify Field Projection: Request only essential data attributes. python dispatch_api_operation("/service/tickets", "GET", { "conditions": "status/name='New'", "fields": "id,ticketNumber,summary,urgency" })

3. Implement Result Paging: Manage large result sets using pagination parameters. python dispatch_api_operation("/service/tickets", "GET", { "conditions": "status/name='New'", "page": 2, "pageSize": 100 })

Licensing Status

This solution is proprietary and subject to strict confidentiality agreements. Unauthorized duplication, distribution, or operational use is strictly forbidden.

Credits

• Developed utilizing the Model Context Protocol (MCP) architecture.
• Integration layer for the ConnectWise Manage API. WIKIPEDIA: Business process management tools encompass the entire suite of systems, applications, governance structures, analytical solutions, operational methodologies, etc., utilized by enterprises to effectively navigate shifting commercial landscapes, maintain competitive advantage, and elevate overall organizational efficacy.

== General Classification == Business tools can be segmented according to the organizational function they serve. This includes tools dedicated to forecasting, procedural governance, record retention, human capital management, strategic deliberation, compliance monitoring, among others. A functional taxonomy commonly recognizes:

Utilities for initial data capture and verification across any operational unit. Software designed for the oversight and refinement of core business workflows. Systems dedicated to synthesizing data for executive insight and decision support. Modern management instrumentation has undergone explosive technological advancement over the last decade, presenting a challenge in selecting the optimal suite for a given operational context. This complexity is driven by relentless pressure for cost reduction and revenue expansion, the imperative to deeply understand client requirements, and the drive to deliver products precisely matching those needs and delivery expectations. In this environment, leadership must adopt a strategic stance toward business tool selection, rather than simply adopting the newest offering. Often, managers implement tools without necessary organizational adaptation, resulting in systemic instability. Therefore, business tools mandate careful selection, followed by rigorous tailoring to meet specific organizational mandates.

== Prominent Tools (2013 Benchmark) == In a 2013 assessment by Bain & Company, global adoption patterns for business tools were mapped, reflecting regional demands shaped by economic cycles. Key categories frequently cited included:

Strategic roadmapping and planning Client relationship management platforms Staff sentiment measurement programs Comparative performance analysis (Benchmarking) Performance measurement frameworks (Balanced Scorecard) Identification of core organizational competencies Operational subcontracting strategies Organizational transformation programs Inbound/Outbound logistics oversight Articulating organizational purpose (Mission/Vision statements) Client base segmentation analysis Comprehensive quality control methodologies

== Enterprise Software Ecosystems == Software suites or discrete applications deployed by business personnel to execute various commercial functions are termed 'business software.' These applications are purposed to amplify productivity, quantify performance metrics, and execute diverse organizational tasks with precision. The evolution progressed from basic Management Information Systems (MIS) to comprehensive Enterprise Resource Planning (ERP) systems, subsequently integrating Customer Relationship Management (CRM), culminating in the contemporary domain of cloud-based enterprise orchestration. While a measurable correlation exists between IT investment and organizational results, two factors are paramount for realizing value: execution quality of the implementation and the rigor applied to tool selection and customization.