Gusto MCP Server Documentation

About

This is Gusto's official MCP server for connecting your own Gusto account. If you're building an integration on the Gusto API and looking for developer tooling, see the Embedded Dev Assistant MCP instead.

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, ChatGPT, 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. Gusto's own commitment not to permit training on your data (see our Privacy Notice) applies to the AI providers Gusto directly contracts with; it does not extend to whichever LLM client you choose to connect via MCP, so opting out on your end is the only way to prevent that client from training on your data.

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.

Scoped, least-privilege access: each connection is limited to only the data categories you explicitly grant during setup. Use get_token_info at any time to check exactly which scopes are active, and revoke or change access by disconnecting and reconnecting the server.

Getting Started

Connecting the Gusto MCP server requires a Gusto account with global/full admin permissions.

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
7. Click "Add"
8. If you see "Configure" next to "Gusto," click the ellipsis (...), select "Disconnect" and confirm the disconnection
9. Click "Connect"
10. Select the desired data types for which you'd like to provide access and, if applicable, the company you'd like to connect
11. Click "Authorize"
12. Open up a new chat
13. 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
14. You're now ready to input your first query!

Setup for ChatGPT

1. Click "Plugins" in the left navigation of the ChatGPT interface
2. Input "Gusto" into the search field in the top right corner
3. Click "+"
4. Go through the authorization flow, selecting the company you'd like to connect if prompted
5. In a new chat, click the "+" button
6. If it's not already selected, click "Gusto"
7. 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/"
    }
  }
}

5. Save the updated file
6. Click "Needs login" under "gusto-mcp"
7. Click "Open"
8. Log in to your Gusto account
9. If there are multiple companies, select the relevant company
10. Click "Authorize"
11. Click "Open Cursor"
12. Within the "AI Pane," open up a New Chat
13. 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"
    }
  }
}

2. Start the tool using gemini
3. Authenticate using one of the methods provided
4. Input /mcp auth gusto
5. Log in to your Gusto account
6. If there are multiple companies, select the relevant company
7. Click "Authorize"
8. Confirm the MCP server is connected by inputting /mcp list
9. 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:

• get_company

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.

Example 2: Employee Department Analysis

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

Expected Tools Called:

• list_employees
• list_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_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_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_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_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.

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

MCP Tools 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 72 tools organized into the following categories:

Company & Onboarding

• create_company - Create the user's Gusto company and payroll-admin account during signup (call with confirmed: false first to verify the account email, then confirmed: true to create).
• get_company - Retrieve business profile details: legal name, entity type, EIN, contact info, and locations.
• get_company_onboarding_status - Get the company's onboarding progress: which setup questions remain, whether each is required, and the next step to drive.
• get_company_onboarding_package - Get the company's available plans, add-ons, and benefits during onboarding, plus Gusto's recommended package.
• get_onboarding_answer - Read the current answer for one onboarding question by its key.
• save_company_onboarding_answer - Save a single onboarding answer; a saved answer can re-route which questions remain.
• create_secure_gusto_session - Open a secure Gusto panel for the user to sign a company form or set themselves up as company signatory (never collects a signature or SSN in chat).
• manage_account - Check whether the signed-in account has set a Gusto password, or resend the password-setup email.
• manage_company_members - Add or update one employee or contractor at a time: basics, compensation, employment terms, and work address, with an option to finalize and send a self-onboarding invite.

Bank Connection

• check_plaid_connection_status - Check whether the company's Plaid-linked payroll funding account has connected and verified.
• connect_bank_via_plaid - Open a Plaid-hosted flow for the user to connect the company's payroll funding account (never collects account or routing numbers in chat).

Tax & Business Formation

• check_ein_status - Check whether the company's federal EIN (Form SS-4) filing has been issued yet.
• file_ein - Prepare and validate a federal EIN (Form SS-4) filing from company and responsible-party details (never collects the responsible party's SSN/ITIN).
• pay_ein_filing - Create a Stripe checkout link to pay for a prepared EIN filing.
• check_scorp_election_status - Check whether the company's Form 2553 S-Corp election filing has been finalized.
• file_scorp_election - Prepare a Form 2553 S-Corp election filing from formation, tax-year, and shareholder details (never collects shareholder SSNs; the owner must still mail the completed form to the IRS).
• acknowledge_scorp_recommendation - Mark a Solo S-Corp tax-savings estimate as reviewed, clearing that onboarding step.
• calculate_scorp_tax_savings - Estimate a single-member LLC owner's potential tax savings from electing S-Corp status, given net income, salary, and state (an estimate, not tax advice).
• calculate_reasonable_salary - Calculate an IRS-defensible reasonable W-2 salary for an S-Corp owner from BLS wage data by ZIP code and occupation.
• accept_reasonable_salary - Accept the most recently calculated reasonable-salary estimate as the owner's W-2 salary.
• calculate_rd_tax_credit - Estimate the federal R&D tax credit a business could claim, from headcount, average pay, and industry (an estimate, not tax advice or a qualification determination).
• check_rd_credit_qualification - Assess whether a business's work could qualify for the federal R&D tax credit, and what would strengthen the case (not tax advice; never returns a "does not qualify" verdict).
• search_business_info - Resolve a free-text description into verified NAICS industry codes or BLS occupation codes for the user to choose from.
• search_workers_comp_class - Resolve a description of an employee's work into that state's workers' comp risk-class codes (Washington and Wyoming only).
• look_up_employment_compliance - Search Gusto's compliance knowledge base for US employment rules (minimum wage, overtime, leave, and similar) by jurisdiction; returns matching summaries only.
• read_employment_compliance_knowledge_units - Read the full text of specific compliance rules found by look_up_employment_compliance.

Reports

• create_reports - Enqueue one or more reports (payroll journal, cash requirements, contractor payments summary, or international contractor payments) for a payroll or date range.
• get_reports - Check the status of reports queued by create_reports and retrieve their CSV content once ready.

Payroll

• get_payroll - Get detailed information about a specific payroll, including worker earnings, taxes, deductions, and net pay.
• list_payrolls - List all payroll runs with filtering (filters by pay period dates by default, not check dates).
• list_payroll_blockers - Identify issues preventing a specific payroll from being processed.
• update_payroll - Update an unprocessed payroll's hours, earnings, PTO, memos, or payment methods for up to 100 employees per call.
• run_payroll - Calculate and submit an existing unprocessed payroll.

Employees & Organization

• get_employee - Get detailed information about a specific employee.
• list_employees - List all employees with filtering options.
• get_employee_earnings_summary - Get per-employee earning breakdowns (commissions, bonuses, tips) across processed payrolls in a date range.
• get_employee_home_address - Get details for a specific home address record.
• list_employee_home_addresses - List all home addresses on file for an employee.
• get_employee_rehire - Get rehire details for an employee returning after a previous departure.
• get_employee_work_address - Get details for a specific work location assignment.
• list_employee_work_addresses - List all work locations assigned to an employee.
• list_employee_custom_fields - List custom field values set for an employee.
• list_employee_employment_history - List an employee's work history: positions held, role changes, and status transitions.
• list_employee_terminations - List offboarding and separation records for an employee.
• list_employee_jobs - List all job positions held by an employee.
• list_job_compensations - Get pay rate history for a job position.
• get_compensation - Get details for a specific pay rate record.
• get_job - Get details for a specific job position.
• get_department - Get details for a specific department.
• list_departments - List all departments in the company's org structure.
• get_location - Get details for a specific company location.
• list_locations - List all company locations.
• list_custom_fields_schema - Get the company's custom field definitions.
• list_earning_types - List all earning type categories configured for the company.

Contractors

• list_contractors - List all independent contractors with pagination and search.
• get_contractor - Get detailed information about a specific contractor.
• get_contractor_payment - Get details for a specific contractor payment.
• list_contractor_payments - List payments made to contractors within a date range.
• get_contractor_payment_group - Get all individual payments within a batched contractor payment run.
• list_contractor_payment_groups - List batched contractor payment runs for the company.

Time Tracking

• get_time_off_balances - Get employees' current time-off balances (available, accrued, used, and pending hours per policy).
• get_time_off_request - Get full detail for a specific time-off request.
• list_time_off_requests - List a company's time-off requests, filterable by status, date range, and employee.
• get_time_sheet - Get detailed time entries for a specific timesheet (third-party time tracking only).
• list_time_records - List time records for a pay period, routed automatically to the company's native or third-party time tracking.
• record_time - Record admin-entered time for a single worker over a pay period, routed automatically to native or third-party time tracking.

Pay Schedules

• get_pay_schedule - Get details for a specific pay schedule.
• list_pay_schedules - List all configured pay schedules for the company.
• list_pay_periods - List pay periods with links to their associated payroll runs.
• list_pay_schedule_assignments - Show which employees are assigned to which pay schedules.

Utility

• get_token_info - Get the current access token's granted scopes and accessible company resources.
• submit_feedback - Submit feedback about the Gusto MCP integration itself (bugs, missing tools, confusing descriptions) to the team that builds it.

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. If you exceed a rate limit, you'll receive a 429 error with a Retry-After header indicating when you can retry. Specific thresholds are not published here, since they are subject to change; if you're building against this at scale, handle a 429 response gracefully rather than hardcoding an expected limit.

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., location_uuid, terminated)
• Cache frequently accessed data when possible

This documentation is actively maintained. See the Changelog for the most recent tool and feature updates.

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 MCP Tools 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 the MCP Tools 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/terms/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 sign up, authentication, or usage of the tools

Data Retention

• Usage metrics & logs: Stored in accordance with Gusto's general Terms and Privacy Notice
• OAuth tokens: Stored securely, refreshed automatically, revoked on disconnect

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

• Name: Gusto MCP Server
• Version: 0.1.0
• Privacy Policy: https://gusto.com/legal/terms/privacy
• Terms of Service: https://gusto.com/legal/terms/gusto-mcp
• Support: [email protected]
• Support URL: https://support.gusto.com/mcp

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

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

Connecting to the demo environment requires a Gusto account with global/full admin permissions, and access to a demo Gusto company with sample data.

Test Account Credentials

• For standardized testing by AI platform providers, use the email address and password provided to you by Gusto. This account will be pre-configured in the correct state for standardized testing.
• All other testing can be done using a standard demo account, provisioned via https://dev.gusto.com

Demo Environment Servers

Core MCP: https://mcp.api.gusto-demo.com
Claude: https://mcp.api.gusto-demo.com/anthropic
ChatGPT: https://mcp.api.gusto-demo.com/openai

Expected Test Data

When you log in with the test account credentials, you'll have access to a company called "MCP Test Company" with the following 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.

September, 2026

• contractor_payments_summary report type added to create_reports
• cash_requirements report type added to create_reports
• create_reports and get_reports tools released
• check_rd_credit_qualification tool released
• calculate_rd_tax_credit tool released
• acknowledge_scorp_recommendation tool released
• EIN filing tools (file_ein, pay_ein_filing, check_ein_status) wired into the onboarding flow

August, 2026

• check_plaid_connection_status tool released; compliance tools renamed to look_up_employment_compliance and read_employment_compliance_knowledge_units; search_workers_comp_class split into its own tool
• connect_bank_via_plaid tool released
• Employment-compliance lookup tools released, flag-gated

July, 2026

• update_payroll tool released

June, 2026

• submit_feedback tool released
• calculate_reasonable_salary tool released
• accept_reasonable_salary tool released
• search_business_info tool released, covering industry and occupation lookup
• get_company_onboarding_package tool released
• get_onboarding_answer tool released
• get_company_onboarding_status tool released
• save_company_onboarding_answer tool released

May, 2026

• list_time_records tool released
• list_time_sheets tool deprecated

April, 2026

• get_employee_earnings_summary tool released
• Various tool optimizations and adjustments

March, 2026

• Various tool optimizations and adjustments

February, 2026

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

January, 2026

• 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