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.

Name Type Required Description

_context string optional The 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.

Name Type Required Description

compensation_uuid string required The unique identifier (UUID) for the record

_context string optional The 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.

Name Type Required Description

contractor_uuid string required The unique identifier (UUID) for the contractor

_context string optional The 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.

Name Type Required Description

contractor_payment_uuid string required The unique identifier (UUID) for the contractor payment

_context string optional The 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.

Name Type Required Description

contractor_payment_group_uuid string required The unique identifier (UUID) for the contractor payment group

_context string optional The 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.

Name Type Required Description

department_uuid string required The unique identifier (UUID) for the department

_context string optional The 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.

Name Type Required Description

employee_uuid string required The unique identifier (UUID) for the employee to retrieve

_context string optional The original user question or request that prompted this tool call

include string optional Comma-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.

Name Type Required Description

_context string optional The original user question or request that prompted this tool call

end_date string optional End of date range (YYYY-MM-DD). Defaults to today.

start_date string optional Start 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.

Name Type Required Description

home_address_uuid string required The unique identifier (UUID) for the address

_context string optional The 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.

Name Type Required Description

employee_uuid string required The unique identifier (UUID) for the employee

_context string optional The 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.

Name Type Required Description

work_address_uuid string required The unique identifier (UUID) for the work location

_context string optional The 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.

Name Type Required Description

job_uuid string required The unique identifier (UUID) for the job

_context string optional The original user question or request that prompted this tool call

include string optional Use 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.

Name Type Required Description

location_uuid string required The unique identifier (UUID) for the location

_context string optional The 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.

Name Type Required Description

pay_schedule_uuid string required The unique identifier (UUID) for the pay schedule

_context string optional The 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.

Name Type Required Description

payroll_uuid string required The unique identifier (UUID) for the payroll

_context string optional The original user question or request that prompted this tool call

employee_compensations_page integer optional Page number for paginating employee compensations within the payroll. Defaults to 1.

employee_compensations_per integer optional Number 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.

Name Type Required Description

time_sheet_uuid string required The unique identifier (UUID) for the timesheet

_context string optional The 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.

Name Type Required Description

_context string optional The 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.

Name Type Required Description

_context string optional The original user question or request that prompted this tool call

end_date string optional Optional end of date range (YYYY-MM-DD)

page integer optional Page number for pagination

per integer optional Number of items per page

start_date string optional Optional 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.

Name Type Required Description

end_date string required End of date range (YYYY-MM-DD) for contractor payments

start_date string required Start of date range (YYYY-MM-DD) for contractor payments

_context string optional The original user question or request that prompted this tool call

contractor_uuid string optional Filter payments by contractor UUID

group_by_date boolean optional When true, groups results by check date

page integer optional Page number for pagination

per integer optional Number 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.

Name Type Required Description

_context string optional The original user question or request that prompted this tool call

include string optional Comma-separated fields to include: company_name, portal_invitations

onboarded boolean optional Filter by contractors who have completed onboarding

onboarded_active boolean optional Filter by contractors who are onboarded and currently active

page integer optional Page number for pagination

per integer optional Number of items per page

search_term string optional A string to search for in names

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

terminated boolean optional Filter by contractors who are no longer active

terminated_today boolean optional Filter 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.

Name Type Required Description

_context string optional The original user question or request that prompted this tool call

page integer optional Page number for pagination (default 1)

per integer optional Number 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.

Name Type Required Description

_context string optional The 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.

Name Type Required Description

_context string optional The 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.

Name Type Required Description

employee_uuid string required The unique identifier (UUID) for the employee

_context string optional The original user question or request that prompted this tool call

page integer optional Page number for pagination

per integer optional Number 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.

Name Type Required Description

employee_uuid string required The unique identifier (UUID) for the employee

_context string optional The 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.

Name Type Required Description

employee_uuid string required The unique identifier (UUID) for the employee

_context string optional The 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.

Name Type Required Description

employee_uuid string required The unique identifier (UUID) for the employee

_context string optional The original user question or request that prompted this tool call

include string optional Use all_compensations to include all effective dated compensations for each job

page integer optional Page number for pagination

per integer optional Number 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.

Name Type Required Description

employee_uuid string required The unique identifier (UUID) for the employee

_context string optional The 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.

Name Type Required Description

employee_uuid string required The unique identifier (UUID) for the employee

_context string optional The 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.

Name Type Required Description

_context string optional The original user question or request that prompted this tool call

include string optional Comma-separated fields to include: all_compensations, all_home_addresses, company_name, current_home_address, custom_fields, portal_invitations

location_uuid string optional Filter by employees assigned to a specific location UUID

onboarded boolean optional Filter by employees who have completed onboarding

onboarded_active boolean optional Filter by employees who are onboarded and currently active

page integer optional Page number for pagination

payroll_uuid string optional Filter by employees included in a specific payroll UUID

per integer optional Number of items per page

search_term string optional A string to search for in names

sort_by string optional Sort field and optional direction, e.g. name:asc. Supported fields: created_at, name, onboarding_status

terminated boolean optional Filter by employees who are no longer active with the company

terminated_today boolean optional Filter by employees whose last day was today

uuids string optional Comma-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.

Name Type Required Description

job_uuid string required The unique identifier (UUID) for the job

_context string optional The original user question or request that prompted this tool call

include string optional Use all_compensations to include all effective dated compensations instead of only the current compensation

page integer optional Page number for pagination

per integer optional Number 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.

Name Type Required Description

_context string optional The original user question or request that prompted this tool call

page integer optional Page number for pagination

per integer optional Number 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.

Name Type Required Description

_context string optional The original user question or request that prompted this tool call

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

payroll_types string optional Comma-separated payroll types to include: regular, transition

start_date string optional Filter 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.

Name Type Required Description

_context string optional The 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.

Name Type Required Description

_context string optional The original user question or request that prompted this tool call

page integer optional Page number for pagination

per integer optional Number 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.

Name Type Required Description

payroll_uuid string required The unique identifier (UUID) for the payroll to check blockers for

_context string optional The 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.

Name Type Required Description

_context string optional The original user question or request that prompted this tool call

date_filter_by string optional Specifies 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_date string optional Filters 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.

include string optional Comma-separated: taxes, totals, payroll_status_meta, risk_blockers, reversals

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

payroll_types string optional Comma-separated: regular,off_cycle,external

per integer optional Number of objects per page. For majority of endpoints will default to 25.

processing_statuses string optional Comma-separated: processed,unprocessed

sort_by string optional Sort field: pay_period or check_date

sort_order string optional Sort payrolls in ascending (asc) or descending (desc) chronological order. Defaults to asc.

start_date string optional Filters 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.

Name Type Required Description

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

_context string optional The original user question or request that prompted this tool call