ConnectWise Management Platform Interface Proxy MCP Server

This Model Context Protocol (MCP) instance supplies a thorough gateway for engaging with the ConnectWise Manage API suite. It streamlines the procedures of API identification, invocation, and administration for both software developers and sophisticated autonomous agents.

Primary Functionalities

• Service Endpoint Exploration: Query and survey ConnectWise API routes utilizing lexicon or descriptive prose.
• Streamlined Call Execution: Trigger API interactions with user-friendly parameter handling and intrinsic fault remediation.
• Accelerated Caching System: Persist and recall frequently executed API operations for optimized operational sequences.
• Unfiltered Endpoint Access: Transmit bespoke API invocations affording comprehensive dominion over URIs, HTTP verbs, and payload specifications.

Distinctive Attributes

• Metadata Repository for Discovery: Leverages an embedded SQLite datastore, populated from the official ConnectWise API specification JSON, ensuring rapid, efficient lookup of service pathways.
• Natural Language Querying: Locate pertinent service interfaces through conversational articulation of required functionality.
• Functional Categorization for Navigation: Browse endpoints organized logically by operational domains.
• In-Depth Specification Access: Retrieve exhaustive details on service pathways, encompassing required arguments, data schemas, and expected return structures.
• Usage-Based Adaptation: The system dynamically learns the value of specific API calls based on interaction frequency.

Deployment and Configuration

Preconditions

• Runtime environment: Python version 3.10 or newer.
• Valid authentication credentials for the ConnectWise Manage API.
• The ConnectWise API schema file (manage.json)—sourced within the project repository.

Installation Pathways

Method A: Utilizing the GitHub NPM Distribution (Recommended)

Install the package directly via the Node Package Manager:

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

This route automates dependency resolution and offers a smoother setup experience for interfaces like Claude Desktop.

Method B: Manual Source Installation

For Windows Systems

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

2. Install the package in editable mode: bash pip install -e .

For macOS Systems

Follow the NPM installation command:

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

For manual setup:

1. Ensure Python 3.10+ is present: bash

Using Homebrew

brew install python@3.10

Or using pyenv

brew install pyenv pyenv install 3.10.0 pyenv global 3.10.0

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

2. Establish a virtual isolated environment (Best Practice): bash python3 -m venv venv source venv/bin/activate

3. Install dependencies: bash pip install -e .

For Linux Distributions (Ubuntu/Debian)

For NPM installation:

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

For manual procedure:

1. Install Python 3.10+ dependencies: bash

For recent Ubuntu versions

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

For older systems, utilizing a PPA

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

1. Fetch the repository source: 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 package installation: bash pip install -e .

Subsequent Configuration Steps

Post-installation on any operating system, complete these checks:

1. (Optional) Initializing the API Metadata Store

While the repository ships with a pre-populated database, execute this command if you incorporate a revised ConnectWise API specification file:

bash

Windows

python build_database.py /path/to/your/manage.json

macOS/Linux

python3 build_database.py /path/to/your/manage.json

This initialization is necessary only once, or whenever the official ConnectWise API structure undergoes modification.

2. Establishing API Access Credentials

Define the following environment variables, substituting placeholders with your actual ConnectWise authorization details:

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 ConnectWise authentication schema

These inputs govern the authentication framework as follows:

• CONNECTWISE_API_URL: The base Uniform Resource Locator for all service interactions with your ConnectWise tenant

full_uri = f"{API_URL}{path}" # Example: https://na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets

• CONNECTWISE_COMPANY_ID: Supplied within the 'clientId' HTTP header for tenant identification

headers = {{'clientId': COMPANY_ID, ...}}

• CONNECTWISE_PUBLIC_KEY & CONNECTWISE_PRIVATE_KEY: Combined with AUTH_PREFIX to construct Basic Authorization credentials

user_principal = f"{AUTH_PREFIX}{PUBLIC_KEY}" # e.g., "api+user_pub_key" secret = PRIVATE_KEY auth_string = f"{user_principal}:{secret}" # Combined: "api+user_pub_key:user_priv_key"

• CONNECTWISE_AUTH_PREFIX: The mandatory prefix prepended to the public key in the authentication username field. ConnectWise requires this discriminator (e.g., "api+", "integration+") to validate the integration type.

The final HTTP headers transmitted with every request will resemble this structure:

'Authorization': 'Basic [Base64 Encoded Credentials]' 'clientId': 'your_company_id' 'Content-Type': 'application/json'

Configuration for AI Environment Integration (e.g., Claude Desktop)

Two primary pathways exist for integrating this proxy service:

Path 1: Via NPM Package Execution (Preferred)

Install using NPM as previously noted:

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

Then, modify the environment configuration file (claude_desktop_config.json):

{ "mcpServers": { "CW-Manage-Interface-Proxy-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+" } } } }

Path 2: Utilizing the Local Node.js Script Launcher (Alternative)

If the source code was cloned and dependencies installed locally, employ the bundled Node.js executable:

{ "mcpServers": { "CW-Manage-Interface-Proxy-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+" } } } }

Path 3: Direct Invocation of the Python Core Script

If relying purely on the Python execution environment:

{ "mcpServers": { "CW-Manage-Interface-Proxy-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), adjust the interpreter command and path structure accordingly:

{ "mcpServers": { "CW-Manage-Interface-Proxy-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 launch the service directly from the terminal for verification purposes:

bash

If installed via NPM

cwm-api-gateway-mcp

If executing the Node.js wrapper (post-clone)

node bin/server.js

Or via direct Python invocation

Windows

python api_gateway_server.py

macOS/Linux

python3 api_gateway_server.py

Available Operational Modules

The Interface Proxy MCP furnishes several distinct modules for interacting with the ConnectWise REST architecture:

Service Endpoint Probing Modules

Module Name	Purpose
search_api_endpoints	Locates service interfaces based on supplied keyword parameters
natural_language_api_search	Derives relevant endpoints using semantic descriptions of intent
list_api_categories	Enumerates all recognized functional groupings within the API
get_category_endpoints	Retrieves all service paths contained within a nominated category
get_api_endpoint_details	Fetches granular specification data for a targeted service path

Service Execution Modules

Module Name	Purpose
execute_api_call	Triggers a service interaction using URI, HTTP verb, parameters, and payload
send_raw_api_request	Submits an unfiltered request formatted as "VERB /path [JSON Body]"

Accelerated Caching Modules

Module Name	Purpose
save_to_fast_memory	Explicitly archives a service operation configuration into the cache
list_fast_memory	Displays the complete catalog of stored operational definitions
delete_from_fast_memory	Removes a singular stored operation definition from the cache
clear_fast_memory	Empties the entire contents of the accelerated cache storage

Illustrative Use Cases

Querying Endpoints Related to Service Records

python search_api_endpoints("service requests")

Semantic Search Execution

python natural_language_api_search("retrieve all pending support incidents tagged as critical")

Executing a Data Retrieval (GET) Operation

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

Creating a New Service Dispatch Record

python execute_api_call( "/service/tickets", "POST", None, # No query parameters needed { "summary": "Critical server outage detected", "board": {"id": 5}, "company": {"id": 101}, "status": {"id": 2}, "priority": {"id": 5} } )

Utilizing the Unfiltered Submission Mechanism

python send_raw_api_request("GET /system/members?pageSize=100")

Inspecting Cached Operations

python list_fast_memory()

Archiving a Useful Retrieval Pattern

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

Deep Dive into the Accelerated Caching System

The Fast Memory feature facilitates the recording and instant recall of frequently employed API operations, thereby optimizing workflow efficiency across several dimensions:

Core Advantages

• Operational Velocity: Achieve rapid execution of complex service calls without requiring recall of precise path segments or intricate parameters.
• Fidelity Enhancement: Reusing validated, successful request signatures minimizes the probability of parameter-related errors.
• Self-Tuning Mechanism: The proxy actively identifies and prioritizes the most leveraged API invocations.
• Configuration Inheritance: Query parameters and full request bodies are retained for effortless reuse.

Operational Flow

1. Automatic Persistence: Upon successful completion of an API transmission, the user is prompted to commit the request signature to Fast Memory.
2. Intelligent Recall: Subsequent attempts to invoke the identical service pathway prompt the system to first check the cache.
3. Default Parameterization: If explicit parameters are omitted during a new call, the system defaults to using the stored configuration from Fast Memory.
4. Usage Metric Tracking: The system maintains a count of how often each stored signature is accessed, influencing display priority.

Cache Management Capabilities

• Catalog View: list_fast_memory()
• Targeted Search: list_fast_memory("search criteria")
• Item Removal: delete_from_fast_memory(unique_identifier)
• Full Purge: clear_fast_memory()

Fast Memory Technical Schema

The persistence layer for Fast Memory is an SQLite instance (fast_memory_api.db), storing the following components:

• Request paths and HTTP verbs.
• Parameters and request bodies serialized as JSON objects.
• Utilization statistics and time markers.
• Human-readable operational descriptions.

The underlying database structure includes these fields: - id: Primary key identifier for the cached entry. - description: User-supplied narrative explaining the purpose of the operation. - path: The exact API endpoint fragment. - method: HTTP verb (e.g., GET, POST, PATCH). - params: Query string parameters, stored as JSON. - data: The request payload, stored as JSON. - timestamp: Record of the last time the entry was invoked. - usage_count: Integer tally of invocations.

Debugging and Diagnostics

Frequent Error Resolution

Initialization Failure (Database Missing)

Error: Metadata store missing at [location] Action Required: Execute the build_database.py utility to construct the necessary data store.

Remedy: Invoke the build_database.py script, pointing it to your ConnectWise API specification document: bash python build_database.py /path/to/your/manage.json

Authorization Rejection (HTTP 401)

HTTP error 401: Credentials Invalidated

Remedy: Conduct a thorough verification of all environment variables related to ConnectWise access: - Confirm accuracy of CONNECTWISE_COMPANY_ID, CONNECTWISE_PUBLIC_KEY, and CONNECTWISE_PRIVATE_KEY. - Verify that the associated API key possesses sufficient rights within the ConnectWise administrative portal. - Ensure CONNECTWISE_AUTH_PREFIX is configured precisely as mandated by your integration profile.

Latency Issues (Timeouts)

Request execution exceeded specified timeout threshold. ConnectWise API responsiveness degraded.

Remedy: - Validate network connectivity stability. - The remote ConnectWise API instance might be under elevated transactional load. - For substantial data extractions, employ more granular filtering mechanisms within your query parameters.

Log and Data Store Locations

• Primary Log File: api_gateway/api_gateway.log
• Data Repository Locations:
  • API Metadata: api_gateway/connectwise_api.db
  • Fast Memory Cache: api_gateway/fast_memory_api.db

Verifying Metadata Store Integrity

Confirm successful construction and accessibility of the API metadata repository: bash python test_database.py

This test command outputs summary statistics regarding the database content, confirming proper query functionality.

Advanced Operational Tuning

Performance Enhancement Strategies for API Requests

To maximize throughput when interacting with ConnectWise endpoints:

1. Employ Hyper-Specific Filtering: Reduce result sets by using precise conditional logic. python execute_api_call("/service/tickets", "GET", { "conditions": "status/name='In Progress' AND dateCreated > [2024-05-01T00:00:00Z]" })

2. Projection for Field Minimization: Limit the returned payload to only the necessary attributes. python execute_api_call("/service/tickets", "GET", { "conditions": "status/name='New'", "fields": "id,title,ownerName,urgency" })

3. Manage Large Datasets via Paging: Utilize page and pageSize controls for segmented retrieval. python execute_api_call("/service/tickets", "GET", { "conditions": "status/name='New'", "page": 2, "pageSize": 100 })

Licensing Stipulations

This software implementation is classified as proprietary and confidential documentation. Any unauthorized duplication, dissemination, or utilization is strictly forbidden.

Acknowledgements

• Developed within the framework architecture of Model Context Protocol (MCP)
• Data exchange powered by the ConnectWise Manage API WIKIPEDIA: XMLHttpRequest (XHR) constitutes an Application Programming Interface realized as a JavaScript entity. Its methods are designed to dispatch HTTP requests from a client browser environment to a designated web server. These capabilities allow browser-hosted applications to initiate server communications subsequent to initial page rendering, and subsequently consume returned data. XMLHttpRequest serves as a foundational element of Ajax programming methodologies. Preceding the emergence of Ajax, page navigation relied primarily on standard hyperlink traversal and form submissions, actions that characteristically involved replacing the entirety of the visible page content.

== Chronology == The conceptual foundation underpinning XMLHttpRequest was first formulated in the year 2000 by the engineering team developing Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). Nonetheless, the initial syntactic implementation did not utilize the standardized XMLHttpRequest identifier. Instead, developers relied on instantiating objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 was released (2006), all dominant browsers had incorporated native support for the XMLHttpRequest identifier. The XMLHttpRequest identifier has since solidified its position as the default, standard mechanism across all major browser engines, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Formal Standardization === The World Wide Web Consortium (W3C) published its initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C advanced this to the Level 2 specification Working Draft. Level 2 introduced enhancements for monitoring data transfer progress events, enabling secure cross-site communication, and managing binary data streams. Towards the close of 2011, the Level 2 specifications were formally subsumed back into the primary standard document. As of late 2012, the WHATWG consortium assumed stewardship over development, maintaining a dynamic document governed by Web IDL specifications.

== Operational Procedure == Generally, initiating a data transmission using XMLHttpRequest necessitates adherence to several programmatic milestones.

1. Object Instantiation: Create an XMLHttpRequest entity by invoking its constructor method:
2. Configuration: Invoke the "open" method to define the transmission type (e.g., GET, POST), pinpoint the target resource Uniform Resource Identifier (URI), and select either synchronous or asynchronous processing mode:
3. Asynchronous Listener Setup: For non-blocking operations, establish an event handler function designed to respond when the request's internal state undergoes modification:
4. Transmission Initiation: Commence the process by calling the "send" method, optionally supplying payload data:
5. State Monitoring: The designated event handler processes state transitions. If the server returns content, it typically populates the "responseText" property. Once the object completes processing the response cycle, its state transitions to 4, signifying the 'completed' status. Beyond these core steps, XMLHttpRequest provides extensive controls over request methodology and response parsing. Custom header fields can be appended to direct server handling instructions, and data streams can be uploaded via the "send" argument. The returned payload can be systematically deserialized from JSON into native JavaScript objects or processed incrementally as chunks arrive rather than awaiting full buffering. Furthermore, the transmission can be halted prematurely or configured to time out if completion is not achieved within a specified duration.

== Inter-Domain Transactions ==

During the early evolution of the World Wide Web, the capability to breach dom