Autotask MCP Server

Instructions

Implementation Reference

• src/services/autotask.service.ts:1366-1383 (handler)

  Core handler implementation: creates a note linked to the company (via accountId) using the Autotask notes.create API endpoint.
  async createCompanyNote(companyId: number, note: Partial<AutotaskCompanyNote>): Promise<number> { const client = await this.ensureClient(); try { this.logger.debug(`Creating company note for company ${companyId}:`, note); const noteData = { ...note, accountId: companyId }; const result = await client.notes.create(noteData as any); const noteId = (result.data as any)?.id; this.logger.info(`Company note created with ID: ${noteId}`); return noteId; } catch (error) { this.logger.error(`Failed to create company note for company ${companyId}:`, error); throw error; } }
• src/handlers/tool.handler.ts:658-683 (schema)

  Tool schema definition including input parameters validation (companyId required, description required, optional title/actionType). Part of the tools list returned by listTools().
  { name: 'create_company_note', description: 'Create a new note for a company', inputSchema: { type: 'object', properties: { companyId: { type: 'number', description: 'The company ID to add the note to' }, title: { type: 'string', description: 'Note title' }, description: { type: 'string', description: 'Note content' }, actionType: { type: 'number', description: 'Action type for the note' } }, required: ['companyId', 'description'] } },
• src/handlers/tool.handler.ts:1225-1232 (handler)

  MCP tool dispatcher in callTool(): maps tool arguments to service method call and formats response.
  case 'create_company_note': result = await this.autotaskService.createCompanyNote(args.companyId, { title: args.title, description: args.description, actionType: args.actionType }); message = `Successfully created company note with ID: ${result}`; break;
• src/handlers/tool.handler.ts:37-1055 (registration)

  Registers the create_company_note tool by including it in the listTools() array returned to MCP server.
  async listTools(): Promise<McpTool[]> { this.logger.debug('Listing available Autotask tools'); const tools: McpTool[] = [ // Connection testing { name: 'test_connection', description: 'Test the connection to Autotask API', inputSchema: { type: 'object', properties: {}, required: [] } }, // Company tools { name: 'search_companies', description: 'Search for companies in Autotask with optional filters', inputSchema: { type: 'object', properties: { searchTerm: { type: 'string', description: 'Search term for company name' }, isActive: { type: 'boolean', description: 'Filter by active status' }, pageSize: { type: 'number', description: 'Number of results to return (default: 50, max: 200)', minimum: 1, maximum: 200 } }, required: [] } }, { name: 'create_company', description: 'Create a new company in Autotask', inputSchema: { type: 'object', properties: { companyName: { type: 'string', description: 'Company name' }, companyType: { type: 'number', description: 'Company type ID' }, phone: { type: 'string', description: 'Company phone number' }, address1: { type: 'string', description: 'Company address line 1' }, city: { type: 'string', description: 'Company city' }, state: { type: 'string', description: 'Company state/province' }, postalCode: { type: 'string', description: 'Company postal/ZIP code' }, ownerResourceID: { type: 'number', description: 'Owner resource ID' }, isActive: { type: 'boolean', description: 'Whether the company is active' } }, required: ['companyName', 'companyType'] } }, { name: 'update_company', description: 'Update an existing company in Autotask', inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Company ID to update' }, companyName: { type: 'string', description: 'Company name' }, phone: { type: 'string', description: 'Company phone number' }, address1: { type: 'string', description: 'Company address line 1' }, city: { type: 'string', description: 'Company city' }, state: { type: 'string', description: 'Company state/province' }, postalCode: { type: 'string', description: 'Company postal/ZIP code' }, isActive: { type: 'boolean', description: 'Whether the company is active' } }, required: ['id'] } }, // Contact tools { name: 'search_contacts', description: 'Search for contacts in Autotask with optional filters', inputSchema: { type: 'object', properties: { searchTerm: { type: 'string', description: 'Search term for contact name or email' }, companyID: { type: 'number', description: 'Filter by company ID' }, isActive: { type: 'number', description: 'Filter by active status (1=active, 0=inactive)' }, pageSize: { type: 'number', description: 'Number of results to return (default: 50, max: 200)', minimum: 1, maximum: 200 } }, required: [] } }, { name: 'create_contact', description: 'Create a new contact in Autotask', inputSchema: { type: 'object', properties: { companyID: { type: 'number', description: 'Company ID for the contact' }, firstName: { type: 'string', description: 'Contact first name' }, lastName: { type: 'string', description: 'Contact last name' }, emailAddress: { type: 'string', description: 'Contact email address' }, phone: { type: 'string', description: 'Contact phone number' }, title: { type: 'string', description: 'Contact job title' } }, required: ['companyID', 'firstName', 'lastName'] } }, // Ticket tools { name: 'search_tickets', description: 'Search for tickets in Autotask with optional filters. BY DEFAULT retrieves ALL matching tickets via pagination for complete accuracy. Only specify pageSize to limit results. Perfect for reports and analytics.', inputSchema: { type: 'object', properties: { searchTerm: { type: 'string', description: 'Search term for ticket title or description' }, companyID: { type: 'number', description: 'Filter by company ID' }, status: { type: 'number', description: 'Filter by ticket status ID (omit for all open tickets: status < 5)' }, assignedResourceID: { type: 'number', description: 'Filter by assigned resource ID. Use null (or omit) to search for unassigned tickets.' }, unassigned: { type: 'boolean', description: 'Set to true to find tickets that are not assigned to any resource (where assignedResourceID is null)' }, pageSize: { type: 'number', description: 'OPTIONAL: Limit number of results. If omitted, retrieves ALL matching tickets for complete accuracy.', minimum: 1, maximum: 500 } }, required: [] } }, { name: 'get_ticket_details', description: 'Get detailed information for a specific ticket by ID. Use this for full ticket data when needed.', inputSchema: { type: 'object', properties: { ticketID: { type: 'number', description: 'Ticket ID to retrieve' }, fullDetails: { type: 'boolean', description: 'Whether to return full ticket details (default: false for optimized data)', default: false } }, required: ['ticketID'] } }, { name: 'create_ticket', description: 'Create a new ticket in Autotask', inputSchema: { type: 'object', properties: { companyID: { type: 'number', description: 'Company ID for the ticket' }, title: { type: 'string', description: 'Ticket title' }, description: { type: 'string', description: 'Ticket description' }, status: { type: 'number', description: 'Ticket status ID' }, priority: { type: 'number', description: 'Ticket priority ID' }, assignedResourceID: { type: 'number', description: 'Assigned resource ID' }, contactID: { type: 'number', description: 'Contact ID for the ticket' } }, required: ['companyID', 'title', 'description'] } }, // Time entry tools { name: 'create_time_entry', description: 'Create a time entry in Autotask', inputSchema: { type: 'object', properties: { ticketID: { type: 'number', description: 'Ticket ID for the time entry' }, taskID: { type: 'number', description: 'Task ID for the time entry (optional, for project work)' }, resourceID: { type: 'number', description: 'Resource ID (user) logging the time' }, dateWorked: { type: 'string', description: 'Date worked (YYYY-MM-DD format)' }, startDateTime: { type: 'string', description: 'Start date/time (ISO format)' }, endDateTime: { type: 'string', description: 'End date/time (ISO format)' }, hoursWorked: { type: 'number', description: 'Number of hours worked' }, summaryNotes: { type: 'string', description: 'Summary notes for the time entry' }, internalNotes: { type: 'string', description: 'Internal notes for the time entry' } }, required: ['resourceID', 'dateWorked', 'hoursWorked', 'summaryNotes'] } }, // Project tools { name: 'search_projects', description: 'Search for projects in Autotask with optional filters. Returns optimized project data to prevent large responses.', inputSchema: { type: 'object', properties: { searchTerm: { type: 'string', description: 'Search term for project name' }, companyID: { type: 'number', description: 'Filter by company ID' }, status: { type: 'number', description: 'Filter by project status' }, projectManagerResourceID: { type: 'number', description: 'Filter by project manager resource ID' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 100)', minimum: 1, maximum: 100 } }, required: [] } }, { name: 'create_project', description: 'Create a new project in Autotask', inputSchema: { type: 'object', properties: { companyID: { type: 'number', description: 'Company ID for the project' }, projectName: { type: 'string', description: 'Project name' }, description: { type: 'string', description: 'Project description' }, status: { type: 'number', description: 'Project status (1=New, 2=In Progress, 5=Complete)' }, startDate: { type: 'string', description: 'Project start date (YYYY-MM-DD)' }, endDate: { type: 'string', description: 'Project end date (YYYY-MM-DD)' }, projectManagerResourceID: { type: 'number', description: 'Project manager resource ID' }, estimatedHours: { type: 'number', description: 'Estimated hours for the project' } }, required: ['companyID', 'projectName', 'status'] } }, // Resource tools { name: 'search_resources', description: 'Search for resources (users) in Autotask with optional filters', inputSchema: { type: 'object', properties: { searchTerm: { type: 'string', description: 'Search term for resource name or email' }, isActive: { type: 'boolean', description: 'Filter by active status' }, resourceType: { type: 'number', description: 'Filter by resource type (1=Employee, 2=Contractor, 3=Temporary)' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 500)', minimum: 1, maximum: 500 } }, required: [] } }, // ===================================================== // NEW TOOLS - Phase 1: High-Priority Entity Support // ===================================================== // Ticket Notes tools { name: 'get_ticket_note', description: 'Get a specific ticket note by ticket ID and note ID', inputSchema: { type: 'object', properties: { ticketId: { type: 'number', description: 'The ticket ID' }, noteId: { type: 'number', description: 'The note ID to retrieve' } }, required: ['ticketId', 'noteId'] } }, { name: 'search_ticket_notes', description: 'Search for notes on a specific ticket', inputSchema: { type: 'object', properties: { ticketId: { type: 'number', description: 'The ticket ID to search notes for' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 100)', minimum: 1, maximum: 100 } }, required: ['ticketId'] } }, { name: 'create_ticket_note', description: 'Create a new note for a ticket', inputSchema: { type: 'object', properties: { ticketId: { type: 'number', description: 'The ticket ID to add the note to' }, title: { type: 'string', description: 'Note title' }, description: { type: 'string', description: 'Note content' }, noteType: { type: 'number', description: 'Note type (1=General, 2=Appointment, 3=Task, 4=Ticket, 5=Project, 6=Opportunity)' }, publish: { type: 'number', description: 'Publish level (1=Internal Only, 2=All Autotask Users, 3=Everyone)' } }, required: ['ticketId', 'description'] } }, // Project Notes tools { name: 'get_project_note', description: 'Get a specific project note by project ID and note ID', inputSchema: { type: 'object', properties: { projectId: { type: 'number', description: 'The project ID' }, noteId: { type: 'number', description: 'The note ID to retrieve' } }, required: ['projectId', 'noteId'] } }, { name: 'search_project_notes', description: 'Search for notes on a specific project', inputSchema: { type: 'object', properties: { projectId: { type: 'number', description: 'The project ID to search notes for' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 100)', minimum: 1, maximum: 100 } }, required: ['projectId'] } }, { name: 'create_project_note', description: 'Create a new note for a project', inputSchema: { type: 'object', properties: { projectId: { type: 'number', description: 'The project ID to add the note to' }, title: { type: 'string', description: 'Note title' }, description: { type: 'string', description: 'Note content' }, noteType: { type: 'number', description: 'Note type (1=General, 2=Appointment, 3=Task, 4=Ticket, 5=Project, 6=Opportunity)' } }, required: ['projectId', 'description'] } }, // Company Notes tools { name: 'get_company_note', description: 'Get a specific company note by company ID and note ID', inputSchema: { type: 'object', properties: { companyId: { type: 'number', description: 'The company ID' }, noteId: { type: 'number', description: 'The note ID to retrieve' } }, required: ['companyId', 'noteId'] } }, { name: 'search_company_notes', description: 'Search for notes on a specific company', inputSchema: { type: 'object', properties: { companyId: { type: 'number', description: 'The company ID to search notes for' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 100)', minimum: 1, maximum: 100 } }, required: ['companyId'] } }, { name: 'create_company_note', description: 'Create a new note for a company', inputSchema: { type: 'object', properties: { companyId: { type: 'number', description: 'The company ID to add the note to' }, title: { type: 'string', description: 'Note title' }, description: { type: 'string', description: 'Note content' }, actionType: { type: 'number', description: 'Action type for the note' } }, required: ['companyId', 'description'] } }, // Ticket Attachments tools { name: 'get_ticket_attachment', description: 'Get a specific ticket attachment by ticket ID and attachment ID', inputSchema: { type: 'object', properties: { ticketId: { type: 'number', description: 'The ticket ID' }, attachmentId: { type: 'number', description: 'The attachment ID to retrieve' }, includeData: { type: 'boolean', description: 'Whether to include base64 encoded file data (default: false)', default: false } }, required: ['ticketId', 'attachmentId'] } }, { name: 'search_ticket_attachments', description: 'Search for attachments on a specific ticket', inputSchema: { type: 'object', properties: { ticketId: { type: 'number', description: 'The ticket ID to search attachments for' }, pageSize: { type: 'number', description: 'Number of results to return (default: 10, max: 50)', minimum: 1, maximum: 50 } }, required: ['ticketId'] } }, // Expense Reports tools { name: 'get_expense_report', description: 'Get a specific expense report by ID', inputSchema: { type: 'object', properties: { reportId: { type: 'number', description: 'The expense report ID to retrieve' } }, required: ['reportId'] } }, { name: 'search_expense_reports', description: 'Search for expense reports with optional filters', inputSchema: { type: 'object', properties: { submitterId: { type: 'number', description: 'Filter by submitter resource ID' }, status: { type: 'number', description: 'Filter by status (1=New, 2=Submitted, 3=Approved, 4=Paid, 5=Rejected, 6=InReview)' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 100)', minimum: 1, maximum: 100 } }, required: [] } }, { name: 'create_expense_report', description: 'Create a new expense report', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Expense report name' }, description: { type: 'string', description: 'Expense report description' }, submitterId: { type: 'number', description: 'The resource ID of the submitter' }, weekEndingDate: { type: 'string', description: 'Week ending date (YYYY-MM-DD format)' } }, required: ['submitterId'] } }, // Quotes tools { name: 'get_quote', description: 'Get a specific quote by ID', inputSchema: { type: 'object', properties: { quoteId: { type: 'number', description: 'The quote ID to retrieve' } }, required: ['quoteId'] } }, { name: 'search_quotes', description: 'Search for quotes with optional filters', inputSchema: { type: 'object', properties: { companyId: { type: 'number', description: 'Filter by company ID' }, contactId: { type: 'number', description: 'Filter by contact ID' }, opportunityId: { type: 'number', description: 'Filter by opportunity ID' }, searchTerm: { type: 'string', description: 'Search term for quote name or description' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 100)', minimum: 1, maximum: 100 } }, required: [] } }, { name: 'create_quote', description: 'Create a new quote', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Quote name' }, description: { type: 'string', description: 'Quote description' }, companyId: { type: 'number', description: 'Company ID for the quote' }, contactId: { type: 'number', description: 'Contact ID for the quote' }, opportunityId: { type: 'number', description: 'Associated opportunity ID' }, effectiveDate: { type: 'string', description: 'Effective date (YYYY-MM-DD format)' }, expirationDate: { type: 'string', description: 'Expiration date (YYYY-MM-DD format)' } }, required: ['companyId'] } }, // Configuration Item tools { name: 'search_configuration_items', description: 'Search for configuration items in Autotask with optional filters', inputSchema: { type: 'object', properties: { searchTerm: { type: 'string', description: 'Search term for configuration item name' }, companyID: { type: 'number', description: 'Filter by company ID' }, isActive: { type: 'boolean', description: 'Filter by active status' }, productID: { type: 'number', description: 'Filter by product ID' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 500)', minimum: 1, maximum: 500 } }, required: [] } }, // Contract tools { name: 'search_contracts', description: 'Search for contracts in Autotask with optional filters', inputSchema: { type: 'object', properties: { searchTerm: { type: 'string', description: 'Search term for contract name' }, companyID: { type: 'number', description: 'Filter by company ID' }, status: { type: 'number', description: 'Filter by contract status (1=In Effect, 3=Terminated)' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 500)', minimum: 1, maximum: 500 } }, required: [] } }, // Invoice tools { name: 'search_invoices', description: 'Search for invoices in Autotask with optional filters', inputSchema: { type: 'object', properties: { companyID: { type: 'number', description: 'Filter by company ID' }, invoiceNumber: { type: 'string', description: 'Filter by invoice number' }, isVoided: { type: 'boolean', description: 'Filter by voided status' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 500)', minimum: 1, maximum: 500 } }, required: [] } }, // Task tools { name: 'search_tasks', description: 'Search for tasks in Autotask with optional filters. Returns optimized task data to prevent large responses.', inputSchema: { type: 'object', properties: { searchTerm: { type: 'string', description: 'Search term for task title' }, projectID: { type: 'number', description: 'Filter by project ID' }, status: { type: 'number', description: 'Filter by task status (1=New, 2=In Progress, 5=Complete)' }, assignedResourceID: { type: 'number', description: 'Filter by assigned resource ID' }, pageSize: { type: 'number', description: 'Number of results to return (default: 25, max: 100)', minimum: 1, maximum: 100 } }, required: [] } }, { name: 'create_task', description: 'Create a new task in Autotask', inputSchema: { type: 'object', properties: { projectID: { type: 'number', description: 'Project ID for the task' }, title: { type: 'string', description: 'Task title' }, description: { type: 'string', description: 'Task description' }, status: { type: 'number', description: 'Task status (1=New, 2=In Progress, 5=Complete)' }, assignedResourceID: { type: 'number', description: 'Assigned resource ID' }, estimatedHours: { type: 'number', description: 'Estimated hours for the task' }, startDateTime: { type: 'string', description: 'Task start date/time (ISO format)' }, endDateTime: { type: 'string', description: 'Task end date/time (ISO format)' } }, required: ['projectID', 'title', 'status'] } } ]; this.logger.debug(`Listed ${tools.length} available tools`); return tools; }