---
name: iblai-connect-gusto
description: "Read and write Gusto data through the Gusto API (App Integrations and Gusto Embedded Payroll) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Gusto data, or to set up a Gusto MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Gusto connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/gusto — not part of the iblai/vibe repository. Checked against Gusto's documentation on October 20, 2026; test it against your own Gusto setup before you rely on it.

Payroll, benefits and HR platform for small businesses. A Gusto company holds employees and contractors, compensation, pay schedules, payrolls, time off, departments, and payroll tax filings.

## Auth & conventions

- **API:** Gusto API (App Integrations and Gusto Embedded Payroll) (REST). REST endpoints for companies, employees, contractors, compensations, pay schedules and payrolls. App Integrations read and write data for shared Gusto customers; Embedded Payroll lets partners run payroll inside their own product.
- **Base URL:** https://api.gusto.com (demo: https://api.gusto-demo.com)
- **Access:** Partner or license program. Built for established software companies serving shared customers; individual Gusto customers connecting their own systems are excluded. Demo keys come from the Developer Portal; production keys need an approved Production Pre-Approval and Security Review.
- **Auth:** OAuth 2.0 authorization code; System access token (client credentials, partner-level). Company admins authorize the app; exchange the code at /oauth/token for an access token (2 hours) and refresh token. Embedded partners get a system access token with grant_type system_access, then company-level tokens per company.
- **Limits:** 200 requests per minute per OAuth grant (per access token), on a 60-second rolling window. Over the limit, requests get HTTP 429 until the window clears.
- Keep Gusto credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Companies** — Company records, locations and departments.
- **Employees** — Employee and contractor records, jobs and compensation.
- **Payrolls** — Payroll runs, pay periods and payroll history with totals.
- **Pay schedules** — Pay schedules and upcoming pay periods.

## Writes

- **Create or update employee** — Add an employee or update job and compensation details.
- **Update payroll** — Enter hours, earnings and reimbursements on an unprocessed payroll.
- **Submit payroll** — Calculate and submit a payroll; this pays people and triggers tax payments. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

Gusto publishes an official MCP server, Gusto MCP (https://support.gusto.com/article/250715155353740/connect-gusto-to-chatgpt-claude-and-slack). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - Gusto supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "List everyone on the next Gusto payroll with their gross pay"
- "How much did we spend on payroll last quarter, by department?"
- "Which employees have a compensation change effective this month?"
- "Show contractors paid more than $600 this year"

## Guardrails

- Holds payroll and tax PII: Social Security numbers, bank accounts, wages, tax withholding and benefits. Treat as highly sensitive; payroll submission moves money and creates tax filings.
- Request the narrowest Gusto scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Gusto App Integrations introduction: https://docs.gusto.com/app-integrations/docs/introduction
- Gusto API rate limits: https://docs.gusto.com/app-integrations/docs/rate-limits
- Gusto Embedded Payroll getting started: https://docs.gusto.com/embedded-payroll/docs/getting-started
- Gusto MCP: https://support.gusto.com/article/250715155353740/connect-gusto-to-chatgpt-claude-and-slack
- This connector on ibl.ai: https://ibl.ai/developer/connectors/gusto
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections