Gusto MCP connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'gustomcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Gusto MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'gustomcp_get_company',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "gustomcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Gusto MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="gustomcp_get_company",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• List time records, payrolls, payroll blockers — List time records for the company over a pay period
• Get token info, time sheet, payroll — Return information about the current API token, including granted scopes and accessible resources

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

gustomcp_get_company#Retrieve the company profile including legal name, entity type, EIN, and status.1 param▾

Retrieve the company profile including legal name, entity type, EIN, and status.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_compensation#Retrieve a single pay rate record by UUID, including rate, frequency, and FLSA status.2 params▾

Retrieve a single pay rate record by UUID, including rate, frequency, and FLSA status.

NameTypeRequiredDescription

compensation_uuidstringrequiredThe unique identifier (UUID) for the record

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_contractor#Retrieve full profile for a contractor by UUID, including name, email, and payment method.2 params▾

Retrieve full profile for a contractor by UUID, including name, email, and payment method.

NameTypeRequiredDescription

contractor_uuidstringrequiredThe unique identifier (UUID) for the contractor

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_contractor_payment#Retrieve details for a single contractor payment by UUID, including amount and payment method.2 params▾

Retrieve details for a single contractor payment by UUID, including amount and payment method.

NameTypeRequiredDescription

contractor_payment_uuidstringrequiredThe unique identifier (UUID) for the contractor payment

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_contractor_payment_group#Retrieve all individual contractor payments within a batched payment group by UUID.2 params▾

Retrieve all individual contractor payments within a batched payment group by UUID.

NameTypeRequiredDescription

contractor_payment_group_uuidstringrequiredThe unique identifier (UUID) for the contractor payment group

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_department#Retrieve details for a single department by UUID, including name and assigned employees.2 params▾

Retrieve details for a single department by UUID, including name and assigned employees.

NameTypeRequiredDescription

department_uuidstringrequiredThe unique identifier (UUID) for the department

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_employee#Retrieve full profile for an employee by UUID, including name, hire date, job, and location.3 params▾

Retrieve full profile for an employee by UUID, including name, hire date, job, and location.

NameTypeRequiredDescription

employee_uuidstringrequiredThe unique identifier (UUID) for the employee to retrieve

_contextstringoptionalThe original user question or request that prompted this tool call

includestringoptionalComma-separated fields to include: all_compensations, all_home_addresses, company_name, current_home_address, custom_fields, portal_invitations

gustomcp_get_employee_earnings_summary#Return per-employee earning breakdowns aggregated across all payrolls in a date range.3 params▾

Return per-employee earning breakdowns aggregated across all payrolls in a date range.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

end_datestringoptionalEnd of date range (YYYY-MM-DD). Defaults to today.

start_datestringoptionalStart of date range (YYYY-MM-DD). Defaults to Jan 1 of current year.

gustomcp_get_employee_home_address#Retrieve a single home address record by UUID, including street, city, state, and ZIP.2 params▾

Retrieve a single home address record by UUID, including street, city, state, and ZIP.

NameTypeRequiredDescription

home_address_uuidstringrequiredThe unique identifier (UUID) for the address

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_employee_rehire#Retrieve rehire details for an employee, including new start date and updated employment terms.2 params▾

Retrieve rehire details for an employee, including new start date and updated employment terms.

NameTypeRequiredDescription

employee_uuidstringrequiredThe unique identifier (UUID) for the employee

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_employee_work_address#Retrieve a single work location assignment by UUID, including address and effective dates.2 params▾

Retrieve a single work location assignment by UUID, including address and effective dates.

NameTypeRequiredDescription

work_address_uuidstringrequiredThe unique identifier (UUID) for the work location

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_job#Retrieve details for a job position by UUID, including title, department, and current pay rate.3 params▾

Retrieve details for a job position by UUID, including title, department, and current pay rate.

NameTypeRequiredDescription

job_uuidstringrequiredThe unique identifier (UUID) for the job

_contextstringoptionalThe original user question or request that prompted this tool call

includestringoptionalUse all_compensations to include all effective dated compensations instead of only the current compensation

gustomcp_get_location#Retrieve details for a company location by UUID, including address and filing information.2 params▾

Retrieve details for a company location by UUID, including address and filing information.

NameTypeRequiredDescription

location_uuidstringrequiredThe unique identifier (UUID) for the location

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_pay_schedule#Retrieve a pay schedule by UUID, including frequency and next scheduled pay dates.2 params▾

Retrieve a pay schedule by UUID, including frequency and next scheduled pay dates.

NameTypeRequiredDescription

pay_schedule_uuidstringrequiredThe unique identifier (UUID) for the pay schedule

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_payroll#Retrieve complete details for a payroll run by UUID, including earnings, taxes, and net pay.4 params▾

Retrieve complete details for a payroll run by UUID, including earnings, taxes, and net pay.

NameTypeRequiredDescription

payroll_uuidstringrequiredThe unique identifier (UUID) for the payroll

_contextstringoptionalThe original user question or request that prompted this tool call

employee_compensations_pageintegeroptionalPage number for paginating employee compensations within the payroll. Defaults to 1.

employee_compensations_perintegeroptionalNumber of employee compensations per page. Defaults to 100 (max).

gustomcp_get_time_sheet#Retrieve time entries for a timesheet by UUID, including daily hours, overtime, and notes.2 params▾

Retrieve time entries for a timesheet by UUID, including daily hours, overtime, and notes.

NameTypeRequiredDescription

time_sheet_uuidstringrequiredThe unique identifier (UUID) for the timesheet

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_get_token_info#Return information about the current API token, including granted scopes and accessible resources.1 param▾

Return information about the current API token, including granted scopes and accessible resources.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_list_contractor_payment_groups#List batched contractor payment runs, showing payment group UUIDs and check dates.5 params▾

List batched contractor payment runs, showing payment group UUIDs and check dates.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

end_datestringoptionalOptional end of date range (YYYY-MM-DD)

pageintegeroptionalPage number for pagination

perintegeroptionalNumber of items per page

start_datestringoptionalOptional start of date range (YYYY-MM-DD)

gustomcp_list_contractor_payments#List payments made to contractors within a date range. Requires start_date and end_date.7 params▾

List payments made to contractors within a date range. Requires start_date and end_date.

NameTypeRequiredDescription

end_datestringrequiredEnd of date range (YYYY-MM-DD) for contractor payments

start_datestringrequiredStart of date range (YYYY-MM-DD) for contractor payments

_contextstringoptionalThe original user question or request that prompted this tool call

contractor_uuidstringoptionalFilter payments by contractor UUID

group_by_datebooleanoptionalWhen true, groups results by check date

pageintegeroptionalPage number for pagination

perintegeroptionalNumber of items per page

gustomcp_list_contractors#List all independent contractors for the company with pagination and search support.10 params▾

List all independent contractors for the company with pagination and search support.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

includestringoptionalComma-separated fields to include: company_name, portal_invitations

onboardedbooleanoptionalFilter by contractors who have completed onboarding

onboarded_activebooleanoptionalFilter by contractors who are onboarded and currently active

pageintegeroptionalPage number for pagination

perintegeroptionalNumber of items per page

search_termstringoptionalA string to search for in names

sort_bystringoptionalSort field and optional direction, e.g. name:asc. Supported fields: created_at, name, onboarding_status, type

terminatedbooleanoptionalFilter by contractors who are no longer active

terminated_todaybooleanoptionalFilter by contractors whose last day was today

gustomcp_list_custom_fields_schema#Retrieve definitions of all custom fields configured for the company, including types and options.3 params▾

Retrieve definitions of all custom fields configured for the company, including types and options.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

pageintegeroptionalPage number for pagination (default 1)

perintegeroptionalNumber of items per page (default 25, max 500)

gustomcp_list_departments#List all departments in the company, including names, UUIDs, and assigned employees.1 param▾

List all departments in the company, including names, UUIDs, and assigned employees.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_list_earning_types#List all earning type categories for the company, such as regular pay, overtime, and bonuses.1 param▾

List all earning type categories for the company, such as regular pay, overtime, and bonuses.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_list_employee_custom_fields#Retrieve all custom field values set for a specific employee.4 params▾

Retrieve all custom field values set for a specific employee.

NameTypeRequiredDescription

employee_uuidstringrequiredThe unique identifier (UUID) for the employee

_contextstringoptionalThe original user question or request that prompted this tool call

pageintegeroptionalPage number for pagination

perintegeroptionalNumber of items per page

gustomcp_list_employee_employment_history#Retrieve the work history timeline for an employee, including all roles and status changes.2 params▾

Retrieve the work history timeline for an employee, including all roles and status changes.

NameTypeRequiredDescription

employee_uuidstringrequiredThe unique identifier (UUID) for the employee

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_list_employee_home_addresses#List all home addresses on file for an employee, including current and historical entries.2 params▾

List all home addresses on file for an employee, including current and historical entries.

NameTypeRequiredDescription

employee_uuidstringrequiredThe unique identifier (UUID) for the employee

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_list_employee_jobs#List all job positions held by an employee, including title, location, and rate information.5 params▾

List all job positions held by an employee, including title, location, and rate information.

NameTypeRequiredDescription

employee_uuidstringrequiredThe unique identifier (UUID) for the employee

_contextstringoptionalThe original user question or request that prompted this tool call

includestringoptionalUse all_compensations to include all effective dated compensations for each job

pageintegeroptionalPage number for pagination

perintegeroptionalNumber of items per page

gustomcp_list_employee_terminations#Retrieve separation records for an employee, including departure dates and final pay details.2 params▾

Retrieve separation records for an employee, including departure dates and final pay details.

NameTypeRequiredDescription

employee_uuidstringrequiredThe unique identifier (UUID) for the employee

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_list_employee_work_addresses#List all work locations assigned to an employee, with effective dates.2 params▾

List all work locations assigned to an employee, with effective dates.

NameTypeRequiredDescription

employee_uuidstringrequiredThe unique identifier (UUID) for the employee

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_list_employees#List all employees for the company with pagination and filtering by status, onboarding, or name.13 params▾

List all employees for the company with pagination and filtering by status, onboarding, or name.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

includestringoptionalComma-separated fields to include: all_compensations, all_home_addresses, company_name, current_home_address, custom_fields, portal_invitations

location_uuidstringoptionalFilter by employees assigned to a specific location UUID

onboardedbooleanoptionalFilter by employees who have completed onboarding

onboarded_activebooleanoptionalFilter by employees who are onboarded and currently active

pageintegeroptionalPage number for pagination

payroll_uuidstringoptionalFilter by employees included in a specific payroll UUID

perintegeroptionalNumber of items per page

search_termstringoptionalA string to search for in names

sort_bystringoptionalSort field and optional direction, e.g. name:asc. Supported fields: created_at, name, onboarding_status

terminatedbooleanoptionalFilter by employees who are no longer active with the company

terminated_todaybooleanoptionalFilter by employees whose last day was today

uuidsstringoptionalComma-separated subset of employee UUIDs to fetch

gustomcp_list_job_compensations#List the pay rate history for a job position, showing all rate changes over time.5 params▾

List the pay rate history for a job position, showing all rate changes over time.

NameTypeRequiredDescription

job_uuidstringrequiredThe unique identifier (UUID) for the job

_contextstringoptionalThe original user question or request that prompted this tool call

includestringoptionalUse all_compensations to include all effective dated compensations instead of only the current compensation

pageintegeroptionalPage number for pagination

perintegeroptionalNumber of items per page

gustomcp_list_locations#List all physical office and work locations registered for the company.3 params▾

List all physical office and work locations registered for the company.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

pageintegeroptionalPage number for pagination

perintegeroptionalNumber of items per page

gustomcp_list_pay_periods#List all pay periods for the company, showing start and end dates and linked payroll runs.4 params▾

List all pay periods for the company, showing start and end dates and linked payroll runs.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

end_datestringoptionalFilter pay periods ending on or before this date (YYYY-MM-DD). Defaults to today. Cannot be more than 3 months in the future.

payroll_typesstringoptionalComma-separated payroll types to include: regular, transition

start_datestringoptionalFilter pay periods starting on or after this date (YYYY-MM-DD). Defaults to 6 months ago. Must be within 1 year of end_date.

gustomcp_list_pay_schedule_assignments#Show which employees are assigned to which pay schedules.1 param▾

Show which employees are assigned to which pay schedules.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_list_pay_schedules#List all pay schedules for the company, showing frequency and schedule UUID.3 params▾

List all pay schedules for the company, showing frequency and schedule UUID.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

pageintegeroptionalPage number for pagination

perintegeroptionalNumber of items per page

gustomcp_list_payroll_blockers#Identify issues preventing a payroll from being processed, such as missing setup or documents.2 params▾

Identify issues preventing a payroll from being processed, such as missing setup or documents.

NameTypeRequiredDescription

payroll_uuidstringrequiredThe unique identifier (UUID) for the payroll to check blockers for

_contextstringoptionalThe original user question or request that prompted this tool call

gustomcp_list_payrolls#List all payroll runs for the company with optional filtering by type, date, and status.11 params▾

List all payroll runs for the company with optional filtering by type, date, and status.

NameTypeRequiredDescription

_contextstringoptionalThe original user question or request that prompted this tool call

date_filter_bystringoptionalSpecifies which date field to use when filtering with start_date and end_date. Only applies to regular processed payrolls. Defaults to pay period if not provided. Valid value is check_date.

end_datestringoptionalFilters where the pay period ends on or before this date (YYYY-MM-DD). Cannot be more than 3 months in the future and must be within 1 year of start_date.

includestringoptionalComma-separated: taxes, totals, payroll_status_meta, risk_blockers, reversals

pageintegeroptionalThe page that is requested. When unspecified, will load all objects unless endpoint forces pagination.

payroll_typesstringoptionalComma-separated: regular,off_cycle,external

perintegeroptionalNumber of objects per page. For majority of endpoints will default to 25.

processing_statusesstringoptionalComma-separated: processed,unprocessed

sort_bystringoptionalSort field: pay_period or check_date

sort_orderstringoptionalSort payrolls in ascending (asc) or descending (desc) chronological order. Defaults to asc.

start_datestringoptionalFilters where the pay period starts on or after this date (YYYY-MM-DD). Must be within 1 year of end_date.

gustomcp_list_time_records#List time records for the company over a pay period. Requires pay_period with start and end dates.2 params▾

List time records for the company over a pay period. Requires pay_period with start and end dates.

NameTypeRequiredDescription

pay_periodobjectrequiredDate range to query. Pass as an object with start_date and end_date in YYYY-MM-DD format.

_contextstringoptionalThe original user question or request that prompted this tool call