GuidesAPI ReferenceChangelog
Log In
Guides
Start typing to search…

MCP


Server Documentation

Gusto MCP Server Documentation

About

The Gusto MCP server allows you to access your data housed within Gusto using natural language within a variety of AI platforms, such as Claude, Cursor, and Gemini.

Important Security & Usage Guidelines

Please adhere to the following critical guidelines:

Use the Gusto MCP Server in Isolation

To prevent potential data leakage and ensure the integrity of your session, use the Gusto MCP server in an isolated environment. Do not connect other MCP servers to the same client session that is connected to Gusto. Mixing servers can lead to unpredictable behavior, including the potential for your Gusto data to be inadvertently sent to another service.

Connect with Trusted Clients Only

Please connect to the Gusto MCP server only through trusted, well-established MCP clients such as Claude, Gemini and Cursor. Using unverified or untrusted clients could expose your sensitive data to security vulnerabilities.

Require Manual Confirmation for All Tool Use

LLMs can sometimes misinterpret prompts. To prevent unintended data access, it is critical that you don't enable any automatic tool execution features in your client. You should always be prompted to confirm any tool call before it is executed. This gives you final control and helps ensure the model is only accessing the data you explicitly approve.

Review All Tool Calls Before Approval

Before approving any tool call, carefully review what data the LLM is requesting. The AI may inadvertently request sensitive payroll or employee information that could then be exposed to other services. Be especially cautious of AI features that perform external web searches or use additional tools, as your company's sensitive data retrieved from Gusto could potentially be sent to external search engines or third-party services. Always verify that the tool calls are appropriate and necessary for your query before allowing them to execute.

Verify All Outputs for Accuracy

Treat all LLM-generated responses as a starting point, not a final source of truth. Always verify the accuracy of both the tool calls the model suggests and the final responses it generates. Because LLMs can occasionally misinterpret data or "hallucinate" information, it's critical that any data presented to you is correct before acting on it.

Opt-Out of Model Training

Your prompts and the resulting responses may contain sensitive information. To protect this data, you must configure your LLM client to opt out of sharing data for model training purposes. Most major providers offer this privacy setting, which may be labeled as "Chat history & training" or similar. Failure to do so could result in your sensitive company data being stored and used by the third-party LLM provider.

Capabilities

Our MCP server provides an OAuth2 based connection process and allows you to select the categories of data to which your chosen LLM will have access, directly shaping its capabilities.

Available Data Categories

When connecting, you can grant access to:

  • Company Information: Basic company details, locations, and settings
  • Employee Data: Employee profiles, job titles, departments, compensation
  • Contractor Data: Contractor information and payment details
  • Payroll Data: Payroll runs, pay schedules, tax information, and deductions
  • Time Tracking: Time-off balances, sick leave, vacation accruals

Getting Started

Prerequisites

  • Claude: Claude Pro or Max subscription
  • Cursor: Cursor Pro, Pro+, Ultra, Teams or Enterprise
  • Gemini: Gemini CLI installed

Setup for Claude

  1. Click your avatar in the bottom left corner of the Claude interface
  2. Click "Settings"
  3. Navigate to "Connectors" in the left nav
  4. Click "Add custom connector"
  5. Input "Gusto" as the Name
  6. Input the Remote MCP server URL: https://mcp.api.gusto.com/anthropic
  7. Click "Add"
  8. Click "Connect"
  9. Select the desired data types for which you'd like to provide access and, if applicable, the company you'd like to connect
  10. Click "Authorize"
  11. Open up a new chat
  12. Confirm the Gusto MCP server is active via the "Search and tools" button, which is found to the right of the "+” button within the chat input
  13. You're now ready to input your first query!

Setup for Cursor

  1. Within the Cursor IDE, go to "Cursor" (in the menu bar) → "Cursor Settings"
  2. Click "Tools & Integrations"
  3. Under "MCP Tools," click "New MCP Server"
  4. Input the following into the automatically generated mcp.json file:
{
  "mcpServers": {
    "gusto-mcp": {
      "url": "https://mcp.api.gusto.com/"
    }
  }
}
  1. Save the updated file
  2. Click "Needs login" under "gusto-mcp"
  3. Click "Open"
  4. Log in to your Gusto account
  5. If there are multiple companies, select the relevant company
  6. Click "Authorize"
  7. Click "Open Cursor"
  8. Within the "AI Pane," open up a New Chat
  9. Begin using the server with prompts like: "Limit this chat to MCP: 'gusto-mcp'"

Setup for Gemini CLI

Prerequisites: Gemini CLI must be installed (installation instructions)

  1. Add the following to your Gemini settings.json file (located in the .gemini folder):
{
  "mcpServers": {
    "gusto": {
      "httpUrl": "https://mcp.api.gusto.com"
    }
  }
}
  1. Start the tool using gemini
  2. Authenticate using one of the methods provided
  3. Input /mcp auth gusto
  4. Log in to your Gusto account
  5. If there are multiple companies, select the relevant company
  6. Click "Authorize"
  7. Confirm the MCP server is connected by inputting /mcp list
  8. Begin testing!

Example Use Cases

Here are practical examples of how to use the Gusto MCP server:

Example 1: Basic Company Information

Prompt: "What is the company name and where is it located?"

Expected Tools Called:

  • list_gusto_companies

Expected Output: Company name and full address (e.g., "MCP Test Company, located at 200 E Santa Clara St, Suite 200, San Jose, CA 95113")

Use Case: Quickly retrieve company details for reports or verification purposes. Note that list_gusto_companies returns an array with one company since users can only authenticate to a single company.

Example 2: Employee Department Analysis

Prompt: "How many employees are in each department?"

Expected Tools Called:

  • list_company_employees
  • list_company_departments

Expected Output: Breakdown by department (e.g., "Engineering: 6 employees, Sales: 3 employees, Marketing: 2 employees, plus 2 unassigned employees")

Use Case: Understand workforce distribution across departments for planning and resource allocation.

Example 3: Recent Payroll Cost Analysis

Prompt: "What was the total gross payroll cost for the most recent payrolls?"

Expected Tools Called:

  • list_company_payrolls

Expected Output: Total gross payroll amount (e.g., "$82,527.69 across three recent payroll runs in September-October 2025")

Use Case: Track payroll expenses for budgeting and financial reporting.

Example 4: New Hire Tracking

Prompt: "Which employees were hired since November 1, 2025?"

Expected Tools Called:

  • list_company_employees

Expected Output: List of recently hired employees with hire dates (e.g., "Maya Angelou (November 7, 2025) and John Lewis (November 14, 2025)")

Use Case: Track recent hires for onboarding workflows and headcount reporting.

Example 5: Compensation Review

Prompt: "Who are the highest and lowest paid employees?"

Expected Tools Called:

  • list_company_employees

Expected Output: Employees with highest and lowest compensation (e.g., "Highest: Taylor Swift and Regina Spektor ($110,000/year each). Lowest: Isaiah Berlin and Immanuel Kant ($22/hour each)")

Use Case: Review compensation distribution for equity analysis and budget planning.

Example 6: Contractor Management

Prompt: "How many contractors do we have and who are they?"

Expected Tools Called:

  • list_company_contractors

Expected Output: Count and names of contractors (e.g., "2 contractors: Ella Fitzgerald and Louis Armstrong")

Use Case: Manage contractor relationships and track non-employee workforce.

API Reference

Authentication

The Gusto MCP server uses OAuth 2.0 for secure authentication:

  • Authorization Endpoint: https://mcp.api.gusto.com/oauth/authorize
  • Token Endpoint: https://mcp.api.gusto.com/oauth/token
  • Supported Grant Types: authorization_code, refresh_token
  • PKCE: Required for enhanced security

Available Tools

The Gusto MCP server provides 37 tools organized into the following categories:

Company & Organization

  • list_gusto_companies - Get company information for the authenticated account (returns array with one company)
  • list_company_locations - List all company locations
  • list_company_departments - List all departments
  • get_department - Get details for a specific department
  • get_location - Get details for a specific location

Employees

  • list_company_employees - List all employees with filtering options
  • get_gusto_employee - Get detailed information about a specific employee
  • list_employee_jobs - List all jobs for an employee
  • get_job - Get details for a specific job
  • list_job_compensations - Get compensation history for a job
  • get_compensation - Get details for a specific compensation record
  • list_employee_employment_history - List employment history for an employee
  • list_employee_terminations - List termination records for an employee
  • get_employee_rehire - Get rehire details for an employee
  • list_employee_custom_fields - List custom field values for an employee
  • list_employee_home_addresses - List home addresses for an employee
  • get_employee_home_address - Get details for a specific home address
  • list_employee_work_addresses - List work addresses for an employee
  • get_employee_work_address - Get details for a specific work address

Contractors

  • list_company_contractors - List all contractors
  • get_contractor - Get detailed information about a specific contractor
  • list_company_contractor_payments - List payment history for contractors
  • get_contractor_payment - Get details for a specific contractor payment
  • list_company_contractor_payment_groups - List contractor payment groups
  • get_contractor_payment_group - Get all payments in a payment group

Payroll

  • list_company_payrolls - List all payroll runs with filtering (filters by pay period dates, not check dates)
  • get_payroll - Get detailed information about a specific payroll
  • list_company_pay_schedules - List all pay schedules for a company
  • get_pay_schedule - Get details for a specific pay schedule
  • list_company_pay_periods - List pay periods for a company
  • list_company_pay_schedule_assignments - List employee-to-pay-schedule assignments
  • list_company_earning_types - List earning types configured for a company

Time Tracking

  • list_company_time_sheets - List all timesheets for a company
  • get_time_sheet - Get details and time entries for a timesheet

Utility

  • get_token_info - Get OAuth scope and token information
  • list_company_custom_fields_schema - Get custom field schema for a company

Tool Parameters

All list tools support pagination and filtering:

  • page (integer): Page number for pagination (default: 1)
  • per (integer): Results per page (default: 25, max: 100)
  • include (string): Comma-separated list of fields to include in response

Response Format

All tools return JSON responses following the MCP protocol specification. Successful responses include:

  • jsonrpc: "2.0"
  • id: Request identifier
  • result: Tool execution results

Error responses include:

  • jsonrpc: "2.0"
  • id: Request identifier
  • error: Object containing code, message, and data fields

Rate Limits

The Gusto MCP server enforces rate limits to ensure fair usage. At the time of writing, the current rate limit is 200 requests over a 60 second rolling window.

If you exceed rate limits, you'll receive a 429 error with a Retry-After header indicating when you can retry.

Token Efficiency

To minimize token usage and improve performance:

  • Use pagination parameters (page, per) to limit result sets
  • Use the include parameter to request only needed fields
  • Filter results using available query parameters (e.g., hired_after, department_id)
  • Cache frequently accessed data when possible

Troubleshooting Guide

Connection Issues

Problem: "Unauthorized" error

Solution:

For Cursor:

  1. Go to "Cursor Settings" → "Tools & Integrations"
  2. Under "MCP Tools," find "gusto-mcp"
  3. Click "Log out" next to the server
  4. Click "Needs login" to log back in and reauthorize

For Claude:

  1. Go to Settings → Connectors
  2. Find the Gusto connector
  3. Click the ellipsis (...) and select "Disconnect"
  4. Click "Connect" to reconnect and reauthorize
  5. If you click "Configure" and no tools show up, follow the disconnect and reconnect steps above

Problem: "Failed to connect to Gusto MCP server"

Solution:

  1. Verify you're using the correct URL: https://mcp.api.gusto.com
  2. Check your internet connection
  3. Try disconnecting and reconnecting the server
  4. Clear your browser cache and cookies
  5. If using Cursor, toggle the server off and back on

Problem: "Authentication failed" or "Invalid credentials"

Solution:

  1. Ensure you're logged into the correct Gusto account
  2. Clear cookies and try authenticating again
  3. Verify you have admin access to the company you're trying to connect
  4. Check if your Gusto session has expired - log in again
  5. For demo environments, ensure you're not logged in as a super user

Problem: "No companies available" after authentication

Solution:

  1. Verify your Gusto account has at least one company
  2. Ensure you have admin access to at least one company
  3. Try logging out of Gusto completely and reconnecting
  4. Contact Gusto support if you believe you should have access

Tool Execution Issues

Problem: Tools are not appearing or not being called

Solution:

  1. Confirm the MCP server is active in your client's tool list
  2. Check that you've granted the appropriate data permissions during OAuth
  3. Try opening a new chat/conversation
  4. Verify your subscription level supports MCP (Pro/Max for Claude, Pro+ for Cursor)
  5. Review your prompt - be specific about what data you need

Problem: "Permission denied" or "Insufficient scope" errors

Solution:

  1. Disconnect and reconnect the server
  2. During reconnection, ensure you select all necessary data categories
  3. Verify the company you connected has the relevant data (e.g., payroll data exists)
  4. Check if your Gusto user role has access to the requested data type

Problem: Tool returns empty results or "No data found"

Solution:

  1. Verify the data exists in your Gusto account (log in directly to check)
  2. Check date ranges - you may be querying outside available data
  3. Review filter parameters - they may be too restrictive
  4. Try broadening your query or removing filters
  5. For payroll data, ensure payrolls have been processed

Response Quality Issues

Problem: LLM provides incorrect or incomplete answers

Solution:

  1. Always verify tool calls before execution - the LLM may have selected wrong tools
  2. Review the raw tool response data to confirm accuracy
  3. Rephrase your prompt to be more specific
  4. Break complex queries into smaller, sequential questions
  5. Explicitly mention which company or date range you're interested in
  6. Ask the LLM to show you which tools it plans to call before executing

Problem: LLM hallucinates data not in the response

Solution:

  1. Ask the LLM to cite which tool response contains the information
  2. Request raw data/JSON responses to verify
  3. Explicitly instruct: "Only use data from tool responses, do not make assumptions"
  4. Break down your question into multiple specific queries
  5. Always verify critical information directly in Gusto

Problem: Response times are slow

Solution:

  1. Reduce the scope of your query (limit date ranges, employee counts, etc.)
  2. Use pagination to request smaller result sets
  3. Ask about specific entities rather than broad "all employees" queries
  4. Check Gusto API status (status.gusto.com)
  5. Try your query during off-peak hours

Error Messages

Error: "Rate limit exceeded"

Message: "You have exceeded the rate limit. Please try again later."

Solution:

  • Wait for the time period specified in the error message
  • Reduce the frequency of your requests
  • Batch multiple questions into a single conversation
  • Use pagination instead of requesting large datasets at once

Error: "Tool not found"

Message: "The requested tool does not exist"

Solution:

  • Verify you're using a supported tool name (see API Reference)
  • Ensure you've granted permissions for that data category
  • Try disconnecting and reconnecting the server
  • The tool may have been renamed - check the latest documentation

Error: "Invalid parameters"

Message: "One or more parameters are invalid"

Solution:

  • Review the tool's parameter requirements in API Reference
  • Check date formats (ISO 8601: YYYY-MM-DD)
  • Verify numeric parameters are valid
  • Ensure required parameters are provided
  • Remove any unsupported parameters

Error: "Session expired"

Message: "Your authentication session has expired"

Solution:

  • Disconnect and reconnect the MCP server
  • Log in to Gusto again
  • Clear your browser cache and cookies
  • Re-authenticate through the OAuth flow

Best Practices for Reliable Results

  1. Start Simple: Begin with basic queries before attempting complex analysis
  2. Verify Data: Always check that the tool responses contain the data you expect
  3. Be Specific: Include company names, date ranges, and specific identifiers in prompts
  4. Sequential Queries: For complex questions, break them into steps
  5. Manual Confirmation: Never enable automatic tool execution
  6. Isolated Sessions: Use Gusto MCP alone, don't mix with other MCP servers
  7. Regular Reconnection: If you experience issues, try disconnecting and reconnecting
  8. Check Permissions: Ensure you've granted all necessary OAuth scopes

Getting Additional Help

If you continue to experience issues:

  1. Documentation: Review this documentation and the MCP specification
  2. Status Page: Check https://status.gusto.com for service interruptions
  3. Support Contact: Email [email protected] with:
    • Detailed description of the issue
    • Steps to reproduce
    • Error messages (if any)
    • Timestamp of the issue
    • MCP client and version you're using
  4. Privacy Policy: https://gusto.com/legal/privacy
  5. Terms of Service: https://gusto.com/legal/terms/gusto-mcp

Data Privacy & Security

What Data is Collected

When you use the Gusto MCP server, we collect:

  • Tool call logs: Tool name, parameters (sanitized), timestamp, request ID
  • Authentication data: OAuth tokens, refresh tokens, company ID
  • Usage metadata: Request counts, error rates, response times

What Data is NOT Collected

We do NOT log:

  • Full conversation history
  • Personally identifiable information (PII) beyond what's necessary for authentication

Data Retention

  • Tool call logs: Retained for 90 days for debugging and compliance
  • OAuth tokens: Stored securely, refreshed automatically, revoked on disconnect
  • Usage metrics: Aggregated and anonymized after 30 days

Your Rights

You have the right to:

  • Submit a request to exercise your privacy rights
  • Export your tool usage logs
  • Revoke access at any time by disconnecting the MCP server
  • Review OAuth permissions and modify scope selections

For data privacy requests, contact: [email protected]

Technical Details

Protocol Version

  • MCP Protocol: 2025-06-18
  • Transport: Streamable HTTP (POST requests)
  • Authentication: OAuth 2.0 with PKCE

Server Information

Service Level Agreement (SLA)

  • Uptime: 99.9% monthly uptime target
  • Support Response: Within 1 business day for critical issues
  • Performance: 95th percentile response time < 2 seconds

Note: AI platforms referenced for illustrative purposes only; Gusto MCP is not affiliated with or endorsed by any AI platforms.

This documentation is current as of November 2025. For the latest updates, visithttps://docs.gusto.com/app-integrations/docs/mcp

Demo & Testing Guide

Gusto MCP Server - Demo & Testing Guide

This guide is for testing the Gusto MCP server using demo companies. Use this before connecting your production company data.

Prerequisites

  • Demo Gusto company with sample data
  • Claude: Claude Pro or Max subscription
  • Cursor: Cursor Pro, Pro+, Ultra, Teams or Enterprise
  • Gemini: Gemini CLI installed

Demo Environment Setup

Claude

  1. Within the Claude interface, click your avatar in the bottom left corner
  2. Click "Settings"
  3. Click "Connectors" in the left nav
  4. Click "Add custom connector"
  5. Input "Gusto" as the "Name"
  6. Input the following as the Remote MCP server URL: https://mcp.api.gusto-demo.com
  7. Click "Add"
  8. Click the ellipses (...)
  9. Click "Disconnect"
  10. Confirm the disconnection by clicking "Disconnect" within the modal
  11. Click "Connect"
    • Note: If you have an active super user session in demo, you'll first need to log out or clear your cookies
  12. Log in using the test account credentials (see Test Account Credentials section above)
  13. You'll see "MCP Test Company" displayed (this is the only company for the test account)
  14. Click "Authorize"
  15. Open up a new chat
  16. Confirm the Gusto MCP server is active via the settings dropdown, which is found to the left of the "Research" button
  17. Begin testing!

Cursor

  1. Within the Cursor IDE, go to "Cursor" (in the menu bar) → "Cursor Settings"
  2. Click "Tools & Integrations"
  3. Under "MCP Tools," click "New MCP Server"
  4. Input the following into the automatically generated mcp.json file:
{
  "mcpServers": {
    "gusto-mcp-demo": {
      "url": "https://mcp.api.gusto-demo.com/"
    }
  }
}
  1. Save the updated file
  2. Click "Needs login" under "gusto-mcp-demo"
    • If under "gusto-mcp-demo" it says "Loading tools," toggle the switch off and back on
  3. Click "Open"
    • Note: If you have an active super user session in demo, either clear your cookies or open the link manually in an Incognito window
  4. Log in using the test account credentials
  5. You'll see "MCP Test Company" displayed (this is the only company for the test account)
  6. Click "Authorize"
  7. Click "Open Cursor"
    • If prompted to "Allow 'cursor-retrieval' extension to open this URI?" click "Open"
  8. Within the "AI Pane," open up a New Chat
  9. Within the new chat, use the following introductory prompt and begin testing:
    • Limit this chat to MCP: 'gusto-mcp-demo'

Gemini CLI

Prerequisites: Gemini CLI must be installed (installation instructions)

  1. Add the following to your Gemini settings.json file, which can be found within the .gemini folder:
{
  "mcpServers": {
    "gusto-demo": {
      "httpUrl": "https://mcp.api.gusto-demo.com"
    }
  }
}
  1. Start the tool using gemini
  2. Authenticate using one of the methods provided
  3. Input /mcp auth gusto-demo
    • Note: If you have an active super user session in demo, you'll first need to log out or clear your cookies
  4. Log in using the test account credentials (see Test Account Credentials section above)
  5. You'll see "MCP Test Company" displayed (this is the only company for the test account)
  6. Click "Authorize"
  7. Confirm the MCP server is connected and ready by inputting /mcp list
  8. Begin testing!

Sample Data

When you log in with the test account credentials, you'll have access to a company with the following, or similar, sample data:

Company Details

  • Display Name: MCP Test Company
  • Location: 200 E Santa Clara St, Suite 200, San Jose, CA 95113
  • Departments: Engineering (6 employees), Sales (3 employees), Marketing (2 employees)
  • Total Employees: 13 (11 assigned to departments, 2 unassigned)
  • Total Contractors: 2
  • Pay Schedule: Every other Friday (bi-weekly)

Sample Employees

Engineering Department:

  • Taylor Swift - CTO, $110,000/year
  • Regina Spektor - CEO, $110,000/year
  • Friedrich Nietzsche - Engineer, $80,000/year
  • Arthur Schopenhauer - Engineer, $88,000/year
  • Alexander Hamilton - Marketing Director, $78,000/year
  • Immanuel Kant - Client Support Manager, $22/hour

Sales Department:

  • Patricia Churchland - Account Director, $78,000/year
  • Isaiah Berlin - Client Support Manager, $22/hour
  • Ammie Purdy - Office Administrator, $37/hour

Marketing Department:

  • Soren Kierkegaard - Client Support Director, $70,000/year
  • Hannah Arendt - Account Manager, $61,000/year

Unassigned:

  • Maya Angelou - Chief Editor, $85,000/year (hired November 7, 2025)
  • John Lewis - Advocate, $85,000/year (hired November 14, 2025)

Contractors:

  • Ella Fitzgerald - Hourly ($18/hour)
  • Louis Armstrong - Fixed

Sample Payrolls

Three payrolls have been processed for September-October 2025:

  1. September 26, 2025

    • Pay Period: September 6 - September 19, 2025
    • Gross Pay: $27,509.23
    • Employer Taxes: $3,031.69
    • Net Pay: $18,275.02

  2. October 10, 2025

    • Pay Period: September 20 - October 3, 2025
    • Gross Pay: $27,509.23
    • Employer Taxes: $2,936.00
    • Net Pay: $18,275.03

  3. October 24, 2025

    • Pay Period: October 4 - October 17, 2025
    • Gross Pay: $27,509.23
    • Employer Taxes: $2,425.44
    • Net Pay: $18,275.05

Test Scenarios

Use these test scenarios to validate MCP functionality:

Test 1: Basic Information Retrieval

Prompt: "What is the company name and where is it located?" Expected Result: "MCP Test Company, located at 200 E Santa Clara St, Suite 200, San Jose, CA 95113"

Test 2: Department Analysis

Prompt: "How many employees are in each department?" Expected Result: "Engineering: 6 employees, Sales: 3 employees, Marketing: 2 employees"

Test 3: Payroll Cost Analysis

Prompt: "What was the total gross payroll for all payrolls in September-October 2025?" Expected Result: "$82,527.69 (three payrolls of $27,509.23 each, with check dates September 26, October 10, and October 24, 2025)"

Test 4: New Hire Tracking

Prompt: "Which employees were hired since November 1, 2025?" Expected Result: "Maya Angelou (November 7, 2025) and John Lewis (November 14, 2025)"

Test 5: Compensation Analysis

Prompt: "Who are the highest and lowest paid employees?" Expected Result: "Highest: Taylor Swift and Regina Spektor ($110,000/year each). Lowest: Isaiah Berlin and Immanuel Kant ($22/hour each)"

Test 6: Contractor Information

Prompt: "How many contractors do we have and who are they?" Expected Result: "2 contractors: Ella Fitzgerald and Louis Armstrong"

Test 7: Employee Details

Prompt: "What is Patricia Churchland's job title and annual salary?" Expected Result: "Account Director, $78,000/year"

Test 8: Payroll Trend Analysis

Prompt: "How has the gross payroll changed across the three most recent payrolls?" Expected Result: "It has remained consistent at $27,509.23 for all three payrolls"

Test 9: Tax Analysis

Prompt: "What is the trend in employer tax payments across the three most recent payrolls?" Expected Result: "Decreasing: $3,031.69 (September 26) → $2,936.00 (October 10) → $2,425.44 (October 24)"

Test 10: Department Distribution

Prompt: "Which employees in Marketing have salaries over $60,000?" Expected Result: "Soren Kierkegaard ($70,000/year) and Hannah Arendt ($61,000/year)"

Test 11: Multi-Turn Conversation

Turn 1: "Show me all departments" Expected: "Sales, Marketing, and Engineering"

Turn 2: "Which one has the most employees?" Expected: "Engineering with 6 employees"

Turn 3: "What's their average salary?" Expected: "Approximately $93,200 per year for salaried employees (Taylor: $110k, Regina: $110k, Friedrich: $80k, Arthur: $88k, Alexander: $78k)"

Test 12: Unassigned Employees

Prompt: "Which employees are not assigned to any department?" Expected Result: "Maya Angelou (Chief Editor) and John Lewis (Advocate), both hired in November 2025"

Validation Checklist

After completing your tests, verify:

  • All tool calls returned expected data
  • No authentication or permission errors occurred
  • Multi-turn conversations maintained context appropriately
  • Numeric calculations were accurate
  • Date filtering worked correctly
  • Employee/contractor data was retrieved accurately
  • Payroll data matched expected values
  • Department information was correct
  • Unassigned employees were properly identified
  • Error handling was appropriate for invalid queries
  • Response times were acceptable (< 5 seconds per tool call)

Common Demo Issues

Issue: Super User Session Conflicts

Symptom: Cannot authenticate as company admin Solution: Clear cookies or use incognito/private browsing mode

Issue: Demo Company Not Found

Symptom: "No companies available" after auth Solution: Verify you're logging in with the correct admin credentials

Issue: Empty Payroll Results

Symptom: Queries for specific date ranges return no payrolls Solution: The demo company has payrolls from September-October 2025. Adjust your date filters accordingly.

Issue: Outdated Data

Symptom: Employee counts or names don't match expected values Solution: Demo company may have been modified. Refer to the Expected Test Data section in this guide for the current baseline configuration.

Demo Data Refresh

If demo data becomes stale or inconsistent:

  1. Record current test results
  2. Reset demo company to baseline configuration
  3. Re-run all test scenarios
  4. Compare results to expected outcomes
  5. Document any discrepancies

Transitioning to Production

Once testing is complete with demo data:

  1. Disconnect the demo MCP server
  2. Clear any cached authentication
  3. Follow production setup instructions
  4. Connect to https://mcp.api.gusto.com
  5. Authenticate with your production Gusto account
  6. Start with simple queries to verify connection
  7. Gradually increase complexity as confidence builds

Important: Demo environment is for testing only. Do not use production credentials in demo or demo credentials in production. Do not add production data to the demo environment.

Changelog

February, 2026

Widgetized run_payroll tool live for Claude specific MCP variant, available via https://mcp.api.gusto.com/anthropic

January, 2025

Widgetized run_payroll tool live for ChatGPT specific MCP variant and official App launched, available via https://chatgpt.com/apps/gusto/asdk_app_69375d9f172c8191b23d73be4107128a

December, 2025

Claude specific endpoint live, available via https://mcp.api.gusto.com/anthropic

August, 2025

Core MCP server live, available via https://mcp.api.gusto.com

Updated 17 days ago