This MCP server provides access to Kaseya Autotask PSA data. It supports operations related to companies, tickets, projects, time entries, and more, based on the server description provided.
🛠️ Key Features
MCP server for Kaseya Autotask PSA
Access to companies, tickets, projects, and time entries
🚀 Use Cases
Search tickets
Integrate Autotask PSA workflows with an AI assistant
⚡ Developer Benefits
Tagged for common developer ecosystems: mcp, autotask, psa, kaseya
Repository indicates Apache 2.0 licensing
⚠️ Limitations
The available documentation excerpt is incomplete and only partially describes supported actions (e.g., “search tickets, create”).
Give your AI assistant direct access to Autotask. Search tickets, create time entries, look up companies, manage projects — all through natural language. No more copy-pasting between browser tabs and chat windows.
This is a Model Context Protocol (MCP) server that connects Claude (or any MCP-compatible AI) to your Autotask PSA environment. Your AI assistant gets 101 tools covering the operations MSP teams use daily: ticket triage, time logging, company lookups, project management, billing review, and more.
If you run an MSP on Autotask and you're tired of the context-switching tax, this is for you.
Note — no GitHub Packages token required. Unlike most WYRE MCP servers,
autotask-mcp does not depend on a private @wyre-ai/* package on
GitHub Packages. Its only WYRE dependency is the autotask-node SDK, declared
as a git dependency on the publicWYRE-AI/autotask-node repo, which
npm install resolves anonymously. The DigitalOcean one-click deploy therefore
works without any NODE_AUTH_TOKEN/GITHUB_TOKEN build variable.
See Installation for Docker and from-source methods.
Features
🔌 MCP Protocol Compliance: Full support for MCP resources and tools
🎴 Interactive Ticket Card (MCP Apps): autotask_get_ticket_details renders as an interactive card in MCP Apps hosts (Claude Desktop/web) with an in-card "Add note" round-trip; neutral theme by default, brandable via MCP_BRAND_* env vars. In every host, the text the assistant reads carries the full ticket: description, contact, linked configuration item, custom fields (UDFs), recent notes and the complete record as JSON
🛠️ Comprehensive API Coverage: 101 tools spanning companies, contacts, tickets, projects, billing items, time entries, notes, attachments, and more
🔍 Advanced Search: Powerful search capabilities with filters across all entities
The HTTP server refuses to start when CONDUIT_S2S_SECRET is empty or a known placeholder. Clients connect to http://127.0.0.1:8080/mcp using MCP Streamable HTTP transport and must send X-Gateway-S2S. See X-Gateway-S2S signing.
Gateway Mode (for MCP Gateway deployments):
When deploying behind an MCP Gateway that injects credentials via HTTP headers. This container has no static Autotask credentials:
X-Gateway-S2S: service-to-service proof (required on /mcp)
X-API-Key: Autotask username
X-API-Secret: Autotask secret
X-Integration-Code: Autotask integration code
X-Impersonation-Resource-Id: (optional) Autotask resource ID to act on behalf of
A /mcp request missing any of the three Autotask headers returns 401 and does not fall back to AUTOTASK_* in the environment. See Gateway Mode for details.
Option 3: From Source (Development)
bash
git clone https://github.com/WYRE-AI/autotask-mcp.git
cd autotask-mcp
npm ci && npm run build
Valid Autotask API credentials (API user email, secret, integration code)
MCP-compatible client (Claude Desktop, Claude Code, etc.)
Docker (for Option 2) or Node.js 18+ (for Option 3)
Configuration
Environment Variables
Create a .env file with your configuration:
bash
# Required Autotask API credentials (Local Mode)
AUTOTASK_USERNAME=your-api-user@example.com
AUTOTASK_SECRET=your-secret-key
AUTOTASK_INTEGRATION_CODE=your-integration-code
# Optional configuration# AUTOTASK_API_URL is auto-detected from AUTOTASK_USERNAME via Autotask's# unauthenticated zoneInformation endpoint on first connect. Only set this# explicitly to override auto-detection (e.g. for an on-prem proxy).# AUTOTASK_API_URL=https://webservices2.autotask.net/atservicesrest/
MCP_SERVER_NAME=autotask-mcp
# Authentication mode
AUTH_MODE=env# env (local), gateway (hosted)# Required to start HTTP. Empty and known placeholders are rejected.# Never commit a real value. stdio does not use this.
CONDUIT_S2S_SECRET=
# Local HTTP only. Exactly "1" skips X-Gateway-S2S and forces 127.0.0.1.# MCP_ALLOW_INSECURE_DEV=1# Transport (stdio for local/desktop, http for remote/Docker)
MCP_TRANSPORT=stdio # stdio, http
MCP_HTTP_PORT=8080 # HTTP transport port (only used when MCP_TRANSPORT=http)# Honored when CONDUIT_S2S_SECRET is set. Without a usable secret the bind is 127.0.0.1.
MCP_HTTP_HOST=0.0.0.0 # HTTP transport bind address# Logging
LOG_LEVEL=info # error, warn, info, debug
LOG_FORMAT=simple # simple, json# Search-result name enrichment# Max concurrent Autotask API calls used to resolve company/resource names on# search results. Kept low to stay under Autotask's per-integration# concurrent-thread limit (raising it risks HTTP 429 "thread threshold").
AUTOTASK_ENHANCE_CONCURRENCY=3
# Max Autotask REST calls in flight per tenant. Further calls queue instead of# tripping the concurrent-thread limit (HTTP 429 "thread threshold").
AUTOTASK_MAX_INFLIGHT=3
# Environment
NODE_ENV=production
Gateway Mode
When deployed behind an MCP Gateway (e.g., mcp.wyre.ai), the server operates in gateway mode where credentials are injected via HTTP headers on each request.
Every /mcp request must include a valid X-Gateway-S2S header and the three Autotask credential headers. A request missing any credential header returns 401. The server does not fall back to AUTOTASK_USERNAME, AUTOTASK_SECRET, or AUTOTASK_INTEGRATION_CODE in the process environment.
Expected Headers:
Header
Description
X-Gateway-S2S
Service-to-service proof. t=<unix seconds>,v1=<hex hmac-sha256>. Required on /mcp whenever CONDUIT_S2S_SECRET is set. See X-Gateway-S2S signing.
X-API-Key
Autotask API username (email)
X-API-Secret
Autotask API secret key
X-Integration-Code
Autotask integration code
X-API-URL
(Optional) Custom Autotask API URL
X-Impersonation-Resource-Id
(Optional) Autotask resource ID to act on behalf of. Forwarded to Autotask as its ImpersonationResourceId header, so actions are attributed to that resource instead of the API user, and recorded in the entity's read-only impersonatorCreatorResourceID field. Must be a positive integer; anything else is ignored with a warning. The impersonated resource must itself have permission for the action, and the API user's security level must permit impersonation.
X-Gateway-S2S signing
MCP_TRANSPORT=http refuses to start unless CONDUIT_S2S_SECRET is a real secret. Empty values and known placeholders are rejected, including changeme, placeholder, your-s2s-secret, secret, password, test, and any value that is only an unresolved ${...} template. The process logs an error and exits non-zero. It never prints the secret.
MCP_ALLOW_INSECURE_DEV=1 is the local-only escape hatch. The process logs a warning, does not check X-Gateway-S2S, and listens on 127.0.0.1 only. A non-loopback MCP_HTTP_HOST (including 0.0.0.0, localhost, and ::1) is ignored in that mode and the override is logged.
Without a usable secret the bind address defaults to 127.0.0.1. A configured secret honors MCP_HTTP_HOST (default 0.0.0.0 when that variable is unset, which is what the container image sets). Publish the host port on loopback unless a proxy sits in front.
/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
With a usable secret, every /mcp request must include:
v1 is HMAC-SHA256, hex-encoded, of the ASCII string t=<unix seconds> (the same t= prefix that starts the header), keyed with CONDUIT_S2S_SECRET. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns HTTP 401. The secret is never written to logs or the response body.
bash
# t is the current unix time. v1 is HMAC-SHA256 of the literal "t=$t".
t=$(date +%s)
v1=$(printf't=%s'"$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "X-Gateway-S2S: t=${t},v1=${v1}" \
-H "X-API-Key: api-user@example.com" \
-H "X-API-Secret: the-api-secret" \
-H "X-Integration-Code: the-integration-code" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
In AUTH_MODE=env, /mcp still requires a valid X-Gateway-S2S header. Autotask credentials then come from AUTOTASK_*. In AUTH_MODE=gateway, the three X-API-* headers above are required as well and are the only credential source for that request.
# Start the MCP server (stdio transport, for piping to an MCP client)
node dist/entry.js
# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http node dist/index.js
# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_TRANSPORT=http node dist/index.js
Resources provide read-only access to Autotask data:
autotask://companies - List all companies
autotask://companies/{id} - Get specific company
autotask://contacts - List all contacts
autotask://contacts/{id} - Get specific contact
autotask://tickets - List all tickets
autotask://tickets/{id} - Get specific ticket
autotask://time-entries - List time entries
Tools
The server provides 101 tools for interacting with Autotask:
Company Operations
autotask_search_companies - Search companies with filters
autotask_create_company - Create new company
autotask_update_company - Update existing company
Contact Operations
autotask_search_contacts - Search contacts with filters
autotask_create_contact - Create new contact
Ticket Operations
autotask_search_tickets - Search tickets with filters
autotask_get_ticket_details - Get a ticket by ID: description, status/priority/queue, company, contact, assignee, dates, linked configuration item, resolution, custom fields (UDFs), recent notes and the full record (fullDetails: true for untruncated text and all UDFs)
autotask_create_ticket - Create new ticket
Time Entry Operations
autotask_create_time_entry - Log time entry
autotask_search_time_entries - Search time entries with filters (resource, ticket, task, date range); each entry includes summaryNotes and internalNotes
Billing Items (Approve and Post Workflow)
autotask_search_billing_items - Search approved and posted billing items
autotask_get_billing_item - Get specific billing item by ID
autotask_search_billing_item_approval_levels - Search multi-level approval records for time entries
Project Operations
autotask_search_projects - Search projects with filters
// Search for companies
{
"name": "autotask_search_companies",
"arguments": {
"searchTerm": "Acme Corp",
"isActive": true,
"pageSize": 10
}
}
// Create a new ticket
{
"name": "autotask_create_ticket",
"arguments": {
"companyID": 12345,
"title": "Server maintenance request",
"description": "Need to perform monthly server maintenance",
"priority": 2,
"status": 1
}
}
ID-to-Name Mapping
The Autotask MCP server includes intelligent ID-to-name mapping that automatically resolves company and resource IDs to human-readable names, making API responses much more useful for AI assistants and human users.
Automatic Enhancement
All search and detail tools automatically include an _enhanced field with resolved names:
ID-to-name mapping is applied automatically to all search and detail tool results. No additional tools are needed — the _enhanced field is added transparently to every response that contains company or resource IDs.
Performance Features
Smart Caching: Names are cached for 30 minutes to reduce API calls
Bulk Operations: Efficient batch lookups for multiple IDs
Graceful Fallback: Returns "Unknown Company (123)" if lookup fails
The server supports the MCP Streamable HTTP transport for remote deployments (e.g., Docker, cloud hosting). Set MCP_TRANSPORT=http to enable it.
bash
# Start with HTTP transport (exits unless CONDUIT_S2S_SECRET is a real secret)
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http MCP_HTTP_PORT=8080 node dist/index.js
The HTTP transport exposes:
POST /mcp — MCP Streamable HTTP endpoint. Requires X-Gateway-S2S when CONDUIT_S2S_SECRET is set. See X-Gateway-S2S signing.
GET /health — Unauthenticated health check (returns {"status":"ok"}). Does not read credentials.
Clients must send requests to /mcp with Accept: application/json, text/event-stream headers per the MCP Streamable HTTP specification.
Docker Deployment
The Docker image uses HTTP transport by default (port 8080) with a built-in health check.
Using Pre-built Image from GitHub Container Registry
The Docker image defaults to HTTP transport on port 8080 — suitable for remote/server deployments where clients connect over the network.
bash
# Pull the latest image
docker pull ghcr.io/wyre-ai/autotask-mcp:latest
# Run container with HTTP transport (default). The image binds 0.0.0.0 inside# the container; publish on loopback and pass the S2S secret.
docker run -d \
--name autotask-mcp \
-p 127.0.0.1:8080:8080 \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-e AUTOTASK_USERNAME="your-api-user@example.com" \
-e AUTOTASK_SECRET="your-secret-key" \
-e AUTOTASK_INTEGRATION_CODE="your-integration-code" \
--restart unless-stopped \
ghcr.io/wyre-ai/autotask-mcp:latest
# Verify it's running (health does not require X-Gateway-S2S)
curl http://127.0.0.1:8080/health
Compose will not start when CONDUIT_S2S_SECRET is unset. The checked-in gateway service sets AUTH_MODE=gateway, publishes 127.0.0.1:8080:8080, and does not inject AUTOTASK_*:
bash
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up
# Clone repository
git clone https://github.com/WYRE-AI/autotask-mcp.git
cd autotask-mcp
# Create environment filecp .env.example .env# Edit .env with your credentials# Start with docker-compose
docker compose up -d
Production Deployment
bash
# Build production image locally
docker build -t autotask-mcp:latest .
# Run container
docker run -d \
--name autotask-mcp \
--env-file .env \
--restart unless-stopped \
autotask-mcp:latest
Development Mode
bash
# Start development environment with hot reload
docker compose --profile dev up autotask-mcp-dev
Development
Setup
bash
git clone https://github.com/WYRE-AI/autotask-mcp.git
cd autotask-mcp
npm install
Available Scripts
bash
npm run dev # Start development server with hot reload
npm run build # Build for production
npm run test# Run test suite
npm run test:watch # Run tests in watch mode
npm run test:coverage # Run tests with coverage
npm run lint # Run ESLint
npm run lint:fix # Fix ESLint issues
# Run all tests
npm test# Run with coverage
npm run test:coverage
# Run in watch mode
npm run test:watch
# Run specific test file
npm test -- tests/autotask-service.test.ts
Test Categories
Unit Tests: Service layer and utility functions
Integration Tests: MCP protocol compliance
API Tests: Autotask API integration (requires credentials)
Coverage Requirements
Minimum 80% coverage for all metrics
100% coverage for critical paths (authentication, data handling)
Configuration Reference
Environment Variables
Variable
Required
Default
Description
AUTOTASK_USERNAME
✅
-
Autotask API username (email)
AUTOTASK_SECRET
✅
-
Autotask API secret key
AUTOTASK_INTEGRATION_CODE
✅
-
Autotask integration code
AUTOTASK_API_URL
❌
Auto-detected
Autotask API endpoint URL
MCP_SERVER_NAME
❌
autotask-mcp
MCP server name
MCP_TRANSPORT
❌
stdio
Transport type (stdio or http)
MCP_HTTP_PORT
❌
8080
HTTP transport port
MCP_HTTP_HOST
❌
0.0.0.0 when a secret is set; 127.0.0.1 without one
HTTP bind address. A configured CONDUIT_S2S_SECRET honors this variable. MCP_ALLOW_INSECURE_DEV=1 forces 127.0.0.1.
CONDUIT_S2S_SECRET
Yes for HTTP
—
Service-to-service secret for X-Gateway-S2S. HTTP exits if this is empty or a known placeholder. Never commit a real value.
MCP_ALLOW_INSECURE_DEV
❌
unset
Set to exactly 1 for local HTTP without a usable secret. Logs a warning, skips X-Gateway-S2S, and listens on 127.0.0.1 only.
LOG_LEVEL
❌
info
Logging level
LOG_FORMAT
❌
simple
Log output format
AUTOTASK_ENHANCE_CONCURRENCY
❌
3
Max concurrent Autotask API calls used to resolve company/resource names on search results. Kept low to stay under Autotask's concurrent-thread limit.
AUTOTASK_MAX_INFLIGHT
❌
3
Max Autotask REST calls in flight per tenant. Further calls queue in the HTTP client instead of tripping the concurrent-thread limit.
NODE_ENV
❌
development
Node.js environment
Logging Levels
error: Only error messages
warn: Warnings and errors
info: General information, warnings, and errors
debug: Detailed debugging information
Log Formats
simple: Human-readable console output
json: Structured JSON output (recommended for production)
Rate Limits
Autotask enforces per-integration-code API thresholds on a rolling 1-hour window:
~20,000 req/hr (hard) — sustained HTTP 429 until the window rolls
LLM-driven workflows fan out easily — "status report on all open projects with notes" can issue hundreds of requests across a few minutes. The server tries to make this safer:
429 responses are surfaced as structured errors. Tool results carry error_type: "rate_limited" and a retry_after_seconds field parsed from Autotask's Retry-After header. The error message explicitly tells the LLM not to retry and to ask the user to scope the query — this prevents repeated retries from extending the cooldown.
Concurrent-thread 429s are queued, not cooled down for a minute. Autotask also returns HTTP 429 when an integration exceeds its thread threshold (the body mentions "thread threshold"). That is a burst problem, separate from the hourly quota. The HTTP client allows AUTOTASK_MAX_INFLIGHT calls in flight per tenant (default 3) and queues the rest. A thread-threshold 429 on an idempotent call (GET, DELETE, or POST /{Entity}/query) is retried with a short backoff and does not arm the 60s cooldown. Hourly-threshold 429s still arm it. Create/update calls are not retried automatically.
Fan-out tool descriptions include rate-limit tips. Tools that are commonly looped over (autotask_search_ticket_notes, autotask_search_project_notes, autotask_search_company_notes, autotask_search_time_entries, autotask_search_ticket_attachments, autotask_search_ticket_note_attachments) include a hint reminding the LLM to scope the parent record list before iterating.
Raising the limit
Per-integration thresholds can be increased in Autotask:
Autotask Admin → Resources/Users (HR) → Resources
Edit the dedicated API user → Workflow Rules → API Tracking Identifier
Adjust the threshold for the integration code your MCP server uses
This is the right answer when a single integration code is shared between Claude/Copilot/etc. and other tooling. For LLM-heavy workloads, dedicate a separate API user (and integration code) so a fan-out from one client doesn't starve others.
Patterns that help
Always scope by date range when searching notes, time entries, attachments. Even a 30-day window can drop call count by an order of magnitude.
Cache parent lookups. If you're iterating over 100 tickets, fetch the ticket list once and reuse it across follow-up queries; don't re-search per child.
Use autotask_get_field_info to discover picklist values once per session rather than refetching them per call.
If you're seeing threshold warnings from Autotask but the server seems fine, the LLM driver is probably issuing fan-out patterns. Tighten the prompt to scope before iterating.
Troubleshooting
Common Issues
Authentication Errors
code
Error: Missing required Autotask credentials
Solution: Ensure all required environment variables are set correctly.
Connection Timeouts
code
Error: Connection to Autotask API failed
Solutions:
Check network connectivity
Verify API endpoint URL
Confirm API user has proper permissions
Permission Denied
code
Error: User does not have permission to access this resource
Solution: Review Autotask API user permissions and security level settings.
Debug Mode
Enable debug logging for detailed troubleshooting:
bash
LOG_LEVEL=debug npm start
Health Checks
Test server connectivity:
bash
# Run test suite
npm run test# For HTTP transport, check the health endpoint
curl http://localhost:8080/health
# Returns: {"status":"ok"}# Test API connection with debug logging
LOG_LEVEL=debug npm start
Autotask API Rate Limits
Problem: 429 Too Many Requests or "thread limit exceeded" errors when Claude queries aggressively
Autotask enforces 3 concurrent threads per endpoint per API tracking identifier. When an LLM issues multiple tool calls simultaneously (e.g., searching tickets, companies, and contacts at once), requests can pile up and hit this limit.
Built-in mitigation: The HTTP client caps in-flight requests per tenant (AUTOTASK_MAX_INFLIGHT, default 3) and queues the rest, so a parallel burst waits for a free slot instead of tripping the thread threshold. You may notice slower responses under heavy load. A thread-threshold 429 on an idempotent call is retried briefly; the hourly request threshold still surfaces as a structured rate-limit error and a short tenant cooldown.
Critical for team/multi-user deployments: If multiple users or the MCP Gateway share the same API credentials, they compete for the same 3-thread budget. This can cause noticeable slowdowns and, in severe cases, queued requests that time out.
Solution — one API key per team: Create a dedicated Autotask API user per team or integration. Each user has an independent integrationCode with its own thread budget:
Set AUTOTASK_USERNAME, AUTOTASK_SECRET, and AUTOTASK_INTEGRATION_CODE per team
code
Support Team → AUTOTASK_INTEGRATION_CODE=SUPPORT_TEAM_CODE (3 threads)
Projects Team → AUTOTASK_INTEGRATION_CODE=PROJECTS_TEAM_CODE (3 threads, independent)
Additionally, Autotask limits 10,000 total requests per hour across all integrations hitting your tenant. If you hit this limit, all integrations will start receiving 429s — another reason to use targeted queries with appropriate filters.
MCP Client Issues
Problem: MCP server not appearing in Claude Desktop
Solutions:
Check configuration file syntax (valid JSON)
Verify file path in the configuration
Ensure environment variables are set correctly
Restart Claude Desktop completely
Problem: "Invalid JSON-RPC message: [dotenv@...] injecting env" / Server disconnected
Cause: The autotask-node library calls dotenv.config() at module load time. dotenv v17+ writes status messages via console.log to stdout, which corrupts the MCP stdio JSON-RPC channel.
Solution: Ensure you're using dist/entry.js (not dist/index.js) as the entry point. The entry wrapper redirects console.log to stderr before any libraries load.
Problem: Slow responses
Solutions:
Check network connectivity to Autotask API
Enable debug logging (LOG_LEVEL=debug) to identify bottlenecks
The server caches company/resource names for 30 minutes automatically
Security Best Practices
Store credentials in environment variables, not directly in config files
Limit Autotask API user permissions to the minimum required
Rotate API credentials regularly
For Docker deployments, use secrets management rather than plain environment variables
Contributing
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
Development Guidelines
Follow TypeScript best practices
Maintain test coverage above 80%
Use conventional commit messages
Update documentation for API changes
Add tests for new features
License
This project is licensed under the Apache License 2.0. See the LICENSE file for details.
Contributor License Agreement
By submitting a pull request, you agree to the terms of our Contributor License Agreement. This ensures that contributions can be properly licensed and that you have the right to submit the code.