mcpengine/servers/gusto

Gusto MCP Server

A comprehensive Model Context Protocol (MCP) server for Gusto, providing AI assistants with complete access to payroll, HR, and benefits management. This server delivers 59 tools covering employee management, payroll processing, benefits administration, and compliance workflows.

Features

• Employee Management: Full CRUD operations for employees with onboarding, termination, and profile management
• Payroll Processing: Run payroll, manage pay schedules, view payroll summaries and history
• Compensation Management: Manage salaries, hourly rates, bonuses, commissions, and pay adjustments
• Contractor Operations: Track contractors, manage contractor payments, and 1099 reporting
• Benefits Administration: Manage health insurance, retirement plans (401k), and employee benefit elections
• Time Off Tracking: Manage PTO policies, vacation accruals, sick leave, and time-off requests
• Tax Management: Handle federal, state, and local tax withholdings and filings
• Bank Account Management: Configure company and employee bank accounts for direct deposit
• Garnishments: Process wage garnishments, child support, and other deductions
• Company Information: Manage company profiles, locations, and organizational settings
• Compliance: Ensure payroll tax compliance, I-9 verification, and benefits enrollment
• Reporting: Generate payroll reports, employee census data, and tax summaries

Installation

npm install && npm run build

Environment Variables

Variable	Required	Description	Example
GUSTO_API_TOKEN	Yes	Your Gusto API access token	de4dbeef1234567890abcdef

Getting Your Access Token

For Production Use (OAuth 2.0 - Recommended)

Gusto uses OAuth 2.0 for third-party integrations. This is a multi-step process:

1. Register as a Gusto Partner:

   • Go to dev.gusto.com
   • Click Get Started and complete partner application
   • Wait for approval (typically 1-3 business days)

2. Create an Application:

   • Log in to Gusto Partner Dashboard
   • Click Create Application
   • Enter application name and description
   • Set redirect URI (e.g., http://localhost:3000/callback)
   • Copy your Client ID and Client Secret

3. OAuth Flow:

   • Direct users to: https://api.gusto.com/oauth/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri={REDIRECT_URI}
   • User authorizes your app and is redirected with an authorization code
   • Exchange code for access token:

     curl -X POST https://api.gusto.com/oauth/token \
       -d "client_id={CLIENT_ID}" \
       -d "client_secret={CLIENT_SECRET}" \
       -d "code={AUTH_CODE}" \
       -d "redirect_uri={REDIRECT_URI}" \
       -d "grant_type=authorization_code"
     

   • Save the access_token from the response

4. Set Environment Variable:

   export GUSTO_API_TOKEN="your_access_token_here"
   

For Development/Testing (API Demo Token)

1. Log in to Gusto Partner Dashboard: Go to dev.gusto.com/partner-center
2. Get Demo Token:
   • Navigate to API Tokens or Demo Environment
   • Click Generate Demo Token
   • This token works with Gusto's demo/sandbox companies
3. Copy Token: Copy the demo token
4. Set Environment Variable:

   export GUSTO_API_TOKEN="your_demo_token_here"
   

Important Notes:

• Demo tokens only work with sandbox data (fake companies/employees)
• Production tokens require OAuth 2.0 authorization from real Gusto customers
• Tokens expire after 2 hours; use refresh tokens for production
• Always use HTTPS and secure token storage

Required API Scopes

When requesting OAuth authorization, specify these scopes:

Core Scopes:

• employees:read - Read employee information
• employees:write - Create and update employee records
• payrolls:read - View payroll data and history
• payrolls:write - Run payrolls and make adjustments
• companies:read - Access company information
• companies:write - Update company settings

Additional Scopes:

• benefits:read - View benefits enrollment and plans
• benefits:write - Manage benefits elections
• time_off:read - View PTO balances and requests
• time_off:write - Approve time-off and manage policies
• contractors:read - View contractor information
• contractors:write - Manage contractor payments
• compensations:read - View salary and wage information
• compensations:write - Update compensation rates
• garnishments:read - View garnishment data
• garnishments:write - Process garnishments
• bank_accounts:read - View bank account information
• bank_accounts:write - Update bank accounts

Full Access: Request all scopes with * (not recommended for security)

Usage

stdio Mode (Default)

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "gusto": {
      "command": "node",
      "args": [
        "/path/to/mcpengine-repo/servers/gusto/dist/index.js"
      ],
      "env": {
        "GUSTO_API_TOKEN": "your_token_here"
      }
    }
  }
}

HTTP Mode

The server can also run as an HTTP endpoint:

export GUSTO_API_TOKEN="your_token_here"
npm start -- --http --port 3000

Then configure your MCP client to connect to http://localhost:3000.

Coverage Manifest

Total API endpoints: ~95 (Gusto API v1)
Tools implemented: 59
Intentionally skipped: ~20 (custom earnings, earning types admin, locations, federal taxes detailed)
Not yet covered: ~16 (webhooks, documents, reports generation, PTO requests)
Coverage: 59/95 = 62%

Coverage Notes:

• ✅ Complete: Employees (12 tools), Payrolls (8 tools), Compensations (7 tools), Contractors (6 tools), Benefits (6 tools), Time Off (6 tools), Bank Accounts (5 tools), Garnishments (4 tools), Companies (3 tools), Tax Tools (2 tools)
• ⏭️ Skipped: Custom earning types configuration, location-specific settings, detailed tax form generation, historical payroll amendments
• 🚧 Planned: Webhook management, document uploads (W-4, I-9), payroll reports generation, PTO request workflow, terminated employee data retention

Example Use Cases

• "Add a new employee named John Smith with email john@company.com"
• "Get payroll summary for the current pay period"
• "Update Sarah's salary to $85,000 annually effective next month"
• "List all contractors and their payment history"
• "Enroll employee #12345 in the company 401(k) plan"
• "Show me all employees with pending time-off requests"
• "Add bank account for direct deposit for new employee"
• "Process wage garnishment for $500/month for employee #789"
• "Get company tax information and EIN"
• "Run payroll for the current period"

Architecture

The server uses Gusto API v1 with Bearer token authentication:

• Client: GustoClient with Bearer token auth
• Tools: 10 tool modules with 59 total tools
• Auth: HTTP Bearer Authentication (Authorization: Bearer {token})
• Pagination: Automatic page-based pagination where supported
• Rate Limits: Respects Gusto rate limits (typically 100 requests/10 seconds)
• Base URL: https://api.gusto.com/v1 (production) or https://api.gusto-demo.com/v1 (demo)

Links

• Gusto Developer Portal
• Gusto API Documentation
• API Reference
• OAuth 2.0 Guide
• Rate Limits
• Partner Center
• Gusto Support