v1.7.0 — State filing status

New tool: get_state_filing_status — lists the employer's state agency account numbers (UC, withholding, SDI) per state, with last-four masking. Use before drafting quarterly filing instructions or when a customer asks "do I have my state account numbers set up?"

Read-only by design. Upserts of account numbers are not exposed via MCP — LLMs are very capable of fabricating plausible account numbers, and we don't want one silently landing on a quarterly UC return. Customers enter via /settings/states or the REST API.

Backed by GET /v1/state-registrations on the NannyKeeper REST API.

Install / upgrade:

npx @nannykeeper/mcp-server

Or pin in your MCP config:

{
  "mcpServers": {
    "nannykeeper": {
      "command": "npx",
      "args": ["@nannykeeper/mcp-server@1.7.0"],
      "env": { "NANNYKEEPER_API_KEY": "..." }
    }
  }
}

v1.6.0 — Voluntary set-aside override

Adds an optional voluntary_set_aside field to the preview_payroll and run_payroll MCP tools, letting agents override or skip an employee's recurring voluntary set-aside rule for a single paycheck.

What's new

• preview_payroll — accepts voluntary_set_aside: { skip?, amount? } to dry-run a paycheck with the rule overridden or skipped.
• run_payroll — same field to override or skip the rule when finalizing payroll.

The recurring rule (e.g., a percentage of gross for OH municipal courtesy withholding) is configured via the dashboard on the employee profile; the API and MCP can override or skip per-paycheck only — they cannot create rules.

Field shape

• { skip: true } — bypass the rule for this paycheck only.
• { amount: 5.00 } — override the computed amount (range: $0–$9,999).
• Omit the field — the recurring rule applies normally.

Compatibility

Backwards compatible with v1.5.0. Existing callers that don't send the field continue to work unchanged.

What is a voluntary set-aside?

A post-tax reduction of net pay tracked as an escrow balance the employer holds for the employee. It does not affect gross pay, federal/state/FICA/FUTA/SUTA taxes, W-2 box 1, or Schedule H. The employer transfers the balance to the employee or to the relevant authority on whatever cadence they choose.

Full API + tool docs: https://www.nannykeeper.com/developers/mcp

v1.5.0 — Scheduled direct deposit payrolls

Direct-deposit payrolls approved more than 5 business days before pay_date now enter a new scheduled state and auto-fire at pay_date - 5 business days, instead of firing ACH immediately on approval. pay_date finally means what it says.

API (POST /v1/payroll/run)

Additive to v1.4.0 — existing callers keep working. New fields on the response when the payroll would schedule:

• status: "scheduled" (new enum value)
• scheduled_send_at — ISO UTC timestamp when the payroll will auto-fire
• is_estimated: true — net pay + tax amounts are estimates and may shift slightly when the scheduled payroll actually fires (YTD + rate configs re-read at fire)

Non-DD payrolls (check/cash) always fire immediately regardless of pay_date.

Amount safeguards (confirm_large_payroll) and ACH debit authorization (confirm_ach_debit) gates now run at approve time for scheduled payrolls; callers still pass them through the same parameters.

MCP tools

• run_payroll — passes through the new scheduled status + fields with no schema changes
• preview_payroll — returns is_estimated: true when pay_date is far enough out that a real run would schedule

Install / upgrade

npx @nannykeeper/mcp-server@1.5.0

Or let your MCP client pull the latest via npx @nannykeeper/mcp-server.

v1.4.0 — Single-call run_payroll

Breaking: run_payroll now finalizes in a single call

Previously run_payroll created a payroll in draft status and required a human in the NannyKeeper dashboard to click through approve + process before money moved. That broke the whole point of a server-to-server payroll tool — agents couldn't complete the workflow.

Now a single run_payroll call creates, approves, and processes the payroll end-to-end. The response reflects the real finalized state:

• processing — direct-deposit ACH debit is in flight
• pending_funding — async DD funding confirmation pending
• completed — check/cash payroll, no DD involved

No UI intervention needed.

pay_date is now optional

Agents have no way to know NannyKeeper's ACH submission cutoff. Now pay_date is optional on both preview_payroll and run_payroll — when omitted, the server picks the earliest valid pay date based on ACH submission lead time (5 business days, holiday-aware) and echoes it back in the response.

If pay_date is supplied and past the submission deadline, the API returns HTTP 400 with next_valid_pay_date in the error details so your agent can retry with a valid date instead of creating an un-processable record.

New: safety gates for direct-deposit payrolls

API callers with DD payments now have explicit safety flags, mirroring the dashboard:

• confirm_large_payroll: true — required when total net pay >$5,000 OR any single net pay >$3,000
• confirm_ach_debit: true — required for the first-ever DD payroll on an employer, or when >30 days have elapsed since the last DD authorization

These exist so an agent running an unexpectedly-large payroll gets a clear 400 instead of quietly moving the money. Your agent should only set them after confirming amounts with the user.

Also in this release

• preview_payroll tool added as a first-class source file (matches the npm tarball; previously only present via published build)
• Full contract test suite for all 4 tools (src/__tests__/tools.test.ts, 30 tests)
• CLAUDE.md / AGENTS.md / README.md refreshed with new tool behavior

Installation

npx @nannykeeper/mcp-server

Or add to Claude Desktop config (see README).

Changelog links

• npm: https://www.npmjs.com/package/@nannykeeper/mcp-server/v/1.4.0
• API changelog: https://www.nannykeeper.com/developers/changelog
• MCP setup guide: https://www.nannykeeper.com/developers/mcp