Gusto
Connect Gusto to look up people and pay, review payrolls, add hours and bonuses, track time off, and manage contractors and benefits.
If PopMCP shows Sign in with Gusto with no fields, click it, sign in as a primary or full-access admin and pick the company. If it asks for a Client ID and Secret, create an application in the Gusto Developer Portal, add PopMCP's redirect URL, and enter the application's details.
- Setup time
- 5 min
- Auth
- OAuth authorization
- API base URL
- https://api.gusto.com
- Rate limits
- 200 requests a minute per connection on Gusto's API, on a rolling 60-second window. Going over answers 429 until the window clears.
Before you begin
- A Gusto login with primary or full-access admin rights on the company you want to connect. Other admins and employees cannot approve access.
- To use your own application: a free Gusto Developer Portal account at dev.gusto.com, and PopMCP's redirect URL from the connect form: https://app.popmcp.com/api/providers/gusto/callback
- A new application is a Demo app that reaches test companies only. Real companies through your own application need Gusto's production approval, which Gusto gives to software partners. Sign in with Gusto has no such gate.
Get your credentials
Check whether you need an application at all
Open Gusto in PopMCP. If you see Sign in with Gusto and no fields, click it, sign in as a primary or full-access admin, pick the company on Gusto's page and approve. You are done, so skip the rest of these steps. If the form asks for a Client ID and Secret, carry on.
Create an organization
Sign in at dev.gusto.com (sign up if you are new). In the left navigation click Organizations, then + Create organization. Add the organization name, a team email and your website, then click Create.
Organizations
Create an application with PopMCP's redirect URL
In the left navigation click Applications, then + Create application. Give it a name such as PopMCP, and under redirect URI paste https://app.popmcp.com/api/providers/gusto/callback exactly: Gusto accepts no wildcards. Click Create.
Applications
A new application is a Demo app on Gusto's latest stable API version.
Copy the Client ID and Secret
Open the application and copy its Client ID and Secret.
PopMCP
- Client ID
- qr6L_9FRkbMVL_Gdwv****
- Secret
- 3aQSHRB3596nZhm6****
Enter them in PopMCP and sign in
Enter the Client ID and Secret in PopMCP. Under Environment type demo for a Demo app, or leave it empty for a production app Gusto has approved. Click Sign in with Gusto, sign in as an admin of the company, pick the company and approve.
Connect in PopMCP
Open your workspace, choose Gusto in the marketplace, and fill in the connect dialog:
| Field | What to enter |
|---|---|
| Client IDtext | Only needed to use your own app. Sign in at dev.gusto.com, open Applications and click Create application, add the redirect URL shown here, then copy its Client ID and Secret. A new app is a Demo app with test data; connecting a real company this way needs an app Gusto has approved for production. |
| Secretsecret | On the same page as the Client ID. Stored encrypted and used only on our server.Encrypted with AES-256-GCM on save and never shown again. |
| Environmenttext | Type demo for a Demo app, which is what a new app is. Leave it empty for a production app Gusto has approved. |
https://app.popmcp.com/api/providers/gusto/callbackOn your app at dev.gusto.com add this as the redirect URI. It must match exactly, or Gusto refuses the sign-in. Changing it on a production app means emailing developer@gusto.com.
PopMCP verifies the credential against Gusto immediately. On success the connection flips to Verified and its MCP tools are provisioned.
Permissions PopMCP requests
These are the scopes sent to Gusto at authorization time.
| Scope | Why PopMCP asks for it |
|---|---|
| accounts:write | Required by the tools this connector exposes. |
| benefits:read | Required by the tools this connector exposes. |
| companies:disconnect_app_integration | Required by the tools this connector exposes. |
| companies:read | Reads the company, its locations and its custom fields. Without it PopMCP cannot show the company's name. |
| companies:write | Required by the tools this connector exposes. |
| company_admin:read | Required by the tools this connector exposes. |
| company_benefits:read | Required by the tools this connector exposes. |
| company_benefits:write | Required by the tools this connector exposes. |
| company_reports:read | Required by the tools this connector exposes. |
| company_reports:write | Required by the tools this connector exposes. |
| compensations:read | Shows pay rates on jobs. Without it, employee answers leave pay out. |
| compensations:write | Changes pay rates and schedules pay changes. |
| contractors:manage | Required by the tools this connector exposes. |
| contractors:read | Lists contractors and their payments. |
| contractors:write | Required by the tools this connector exposes. |
| departments:read | Required by the tools this connector exposes. |
| departments:write | Required by the tools this connector exposes. |
| employee_benefits:read | Required by the tools this connector exposes. |
| employee_benefits:write | Required by the tools this connector exposes. |
| employee_time_off_activities:read | Required by the tools this connector exposes. |
| employees:manage | Required by the tools this connector exposes. |
| employees:read | Lists employees and reads their details, addresses and custom fields. |
| employees:write | Updates employee details and home addresses. |
| employments:read | Required by the tools this connector exposes. |
| employments:write | Required by the tools this connector exposes. |
| events:read | Required by the tools this connector exposes. |
| garnishments:read | Required by the tools this connector exposes. |
| garnishments:write | Required by the tools this connector exposes. |
| notifications:read | Required by the tools this connector exposes. |
| pay_schedules:read | Required by the tools this connector exposes. |
| payroll_syncs:read | Required by the tools this connector exposes. |
| payroll_syncs:write | Required by the tools this connector exposes. |
| payrolls:read | Lists payrolls and reads their totals and pay lines. |
| payrolls:write | Prepares a payroll and puts hours and earnings on it. This does not run it. |
| reimbursements:read | Required by the tools this connector exposes. |
| reimbursements:write | Required by the tools this connector exposes. |
| salary_estimates:read | Required by the tools this connector exposes. |
| salary_estimates:write | Required by the tools this connector exposes. |
| time_off_policies:read | Required by the tools this connector exposes. |
| time_off_policies:write | Required by the tools this connector exposes. |
| time_off_requests:read | Lists time off requests. |
| time_sheet:read | Required by the tools this connector exposes. |
| time_sheet:write | Creates and updates time sheets. |
| webhook_subscriptions:read | Required by the tools this connector exposes. |
| webhook_subscriptions:write | Manages webhooks. Your own application only. |
Verify it worked
PopMCP shows Gusto as Connected under your company's name, and gusto_company_overview returns the company with its locations and pay schedules.
Troubleshooting
Gusto shows an error page instead of asking for access
Why: PopMCP's redirect URL is not on your application, or differs by a character.
Fix: On your application at dev.gusto.com set the redirect URI to `https://app.popmcp.com/api/providers/gusto/callback` and connect again. A production application's redirect URI changes only by emailing developer@gusto.com.
"Gusto did not accept the app's Client ID and Client secret"
Why: A value was mistyped, or the Environment does not match the application.
Fix: Copy both again from dev.gusto.com. Type `demo` under Environment for a Demo app, and leave it empty for a production one.
"Gusto signed in but refused to show the company"
Why: The person who signed in is not a primary or full-access admin.
Fix: Sign in as one of those admins and connect again.
A tool answers that it needs a permission, or a scope
Why: Gusto sets which permissions a sign-in or application holds, and this call is outside them.
Fix: The answer names what is missing. For your own application, ask developer@gusto.com to add it. With Sign in with Gusto, see what gusto_list_official_tools offers, or do it in Gusto.
A tool answers that it is for Gusto Embedded apps only
Why: Gusto keeps that endpoint for its Embedded payroll partners.
Fix: Do it in Gusto, or see what gusto_list_official_tools offers if you connected with Sign in with Gusto.
You see only test companies
Why: A new application is a Demo app.
Fix: Use Sign in with Gusto when it is offered. Real companies through your own application need Gusto's Production Pre-Approval and Security Review.