prismhr-mcp

The open-source Model Context Protocol (MCP) server for PrismHR. Connect Claude, Cursor, or any MCP-compatible AI agent directly to your PrismHR PEO platform. Automate payroll, benefits enrollment, compliance reporting, AR/billing, carrier EDI files, and Microsoft 365 actions — with verified-schema tools, scope-gated consent, and zero custom integration code.

Built for PEOs, brokers, and payroll operators who want AI agents that actually work against PrismHR — not another brittle script farm.

Maintained by Simploy. MIT-licensed, PyPI-distributed, plugin-friendly. The fundamental layer for PrismHR × agentic AI.

mcp-name: io.github.nikulk2992-jpg/prismhr-mcp

Keywords: PrismHR API, PrismHR integration, MCP server, Model Context Protocol, PEO automation, payroll automation, AI for HR, Claude for PrismHR, agentic AI, benefits enrollment automation, 834 EDI, 401(k) file automation, HRIS AI agent, PEO software integration.

Why this exists

Every PEO running PrismHR ends up with the same Frankenstein stack: Python scripts, Postman collections, Playwright automations, one-off Node apps. Each one re-implements login, session keepalive, retry logic, pagination, and PrismHR's quirks (camelCase schemas, 500 "No data found" gotchas, batch-of-20 caps, silent 401s).

prismhr-mcp centralizes all of that once, as a production-grade MCP server. The AI agent orchestrates; the server owns auth, caching, retries, normalization, and PEO domain logic. Any PEO drops it in and gets a productive AI experience against their own PrismHR tenant — no glue code, no guesswork, no hallucinated endpoints.

Who this is for:

• PEOs running PrismHR who want to wire Claude / Cursor / ChatGPT Desktop directly into their ops stack
• Benefit brokers and carriers building enrollment automations
• Payroll teams replacing brittle Postman / Playwright workflows
• Consultants shipping PEO AI pilots on tight timelines

Status

Production-ready core. Live on PyPI and the MCP Registry.

• Auth + session + HTTP client: done. 1Password CLI integration, scrypt-encrypted disk credential cache, PrismHR session with proactive keepalive (no mid-workflow 401s), automatic refresh on failure, concurrency cap, retry with jittered backoff, 500→empty quirk handling, pagination, batching.
• Verified-schema gate: every tool grounded in a live UAT probe — no guessed endpoints, no invented fields. 102 response shapes verified and rising.
• 447-method catalog: full PrismHR REST surface indexed across 18 services. meta_call lets the agent invoke any verified method safely.
• Connect-time consent system: 15-scope manifest, per-(peo, env) JSON consent store with prerequisite expansion and cascade revoke. Default posture = deny all. Tools enforce scope at call time.
• Production safety gate: PRISMHR_MCP_ALLOW_PROD=true required to point at prod PrismHR. Prevents accidental first-run blast radius.
• MCP Registry listed: discoverable by every MCP-aware client.
• Test suite: passing via pytest + respx.

See .planning/architecture.md for the full roadmap and .planning/assistants-roadmap.md for the paid tier details.

What this unlocks for PEOs

Once wired into your PrismHR tenant, an AI agent (Claude, ChatGPT, Cursor) can run any of these workflows against live data — read-only by default, write actions opt-in and scoped.

Daily ops

• New Hire Onboarding Audit — every new hire checked for missing SSN, address, E-Verify clearance, required deductions, garnishment setup. Flags problems before first paycheck.
• Payroll Batch Health Check — real-time status of every open batch; catches stale INIT, stuck approvals, pay-date-past without post, negative net, missing vouchers.
• Terminated Employee Cleanup — post-termination checklist: final check issued, deductions stopped, benefits ended, COBRA record created, PTO paid out, ACH retired.
• Manual Check Audit — flags off-cycle checks without reason codes, excessive amounts, duplicates within a window, repeat-monthly patterns.

Compliance

• ACA Configuration Integrity — catches the setup errors PrismHR itself flags as the #1 cause of 1094-C/1095-C penalty exposure.
• 1095-C Value Consistency Audit — post-generation audit of every 1095-C form; flags code 1H posted while employee was enrolled, safe-harbor conflicts, status-type-change-driven code drift, waiting-period miscoding, ICHRA codes used for pre-2020 years.
• Dependent Coverage Age-Out — dependents past the ACA age threshold, or nearing it in the next 30/60/90 days.
• COBRA Eligibility Sweep — qualifying events, notice-window countdown, election-deadline warnings.
• Garnishment Payment History — active garnishments with no payments, overdue remittances, multi-garnishment priority checks.
• W-2 Readiness Check — pre-flight for January: SSN present + correct format, federal withholding configured, YTD sanity.

Reconciliation

• YTD Payroll Reconciliation — bulk year-to-date totals vs sum of voucher history; finds silent drift before W-2 season.
• 941 Quarterly Reconciliation — federal tax return tie-out per quarter; wages, FIT, Social Security, Medicare, Additional Medicare.
• Benefits-Deduction Audit — enrolled-but-not-deducted and deducted-but-not-enrolled mismatches; the silent premium leaks.
• Billing-vs-Payroll Wash Audit — per-employee plan-level check.
• Billing-vs-Payroll Reconciliation (client level) — monthly controller tie-out.
• 401(k) Match Rule Compliance — employer match vs plan formula, 402(g) limit watch, catch-up eligibility for 50+.
• 401(k) True-Up Calculation — year-end match owed for employees who hit deferral limit early and lost proportional match.

Benefits + AR

• FSA/HSA Contribution Limit Tracker — IRS 2026 limits watched with over-limit, approaching-limit, and projected-overage findings.
• Retirement Loan Status — default risk + past-term loans + deemed-distribution exposure.
• Workers Comp Exposure — estimated premium per class code per state using current wages × rate × experience modifier.
• Outstanding Invoice Aging — AR bucketing + at-risk-client flag.
• PTO Balance Reconciliation — negative balances, over-cap, stale accrual, missing class assignment.
• Doc Expiration Sweep — I-9 + identity documents expiring in the next 30/60/90 days.
• Client Go-Live Readiness — pre-payroll checklist + readiness score for new PEO clients.

Carrier + distribution

• Carrier Enrollment (834 5010) — generic writer + per-carrier companion-guide configs. Guardian model live; BCBS Michigan, Sun Life EDX, Voya PDI, Empower PDI on the pilot roadmap.
• W-2 Distribution Assistant — bulk download, certified-mail shipping, electronic delivery with consent check, SharePoint archive — all composable.

Every workflow returns structured findings with severity and remediation hints, so an AI agent can chain them into higher-order reports (month-end close pack, year-end filing pack, new-client go-live pack, etc.).

Tiering: the OSS core is free. The workflows above ship in the paid prismhr-mcp-simploy tier — source-available, per-PEO license. Contact nihar@simploy.com.

Editions

prismhr-mcp ships in three tiers. Core is free forever. Paid tiers layer commercial PEO intelligence on top.

Tier 1 — prismhr-mcp (this repo, MIT, free)

The foundation. What's in the box:

• PrismHR session manager with keepalive + auto-refresh
• 447-method catalog + verified-schema meta_call
• Scope-gated consent, prod safety gate, encrypted credential cache
• meta_find, meta_describe, meta_capabilities
• Client + employee + payroll read tools grounded in live UAT
• MCP Registry listing, PyPI distribution

Use this if you want to run Claude against your PrismHR tenant today with zero custom code.

Tier 2 — prismhr-mcp-simploy (paid, source-available) — in active build

Named AI Assistants that ship PEO workflows end-to-end. Built on the OSS core. Licensed per-PEO.

Shipping now:

• Carrier Enrollment Assistant — generic 834 5010 EDI writer + carrier companion-guide configs. Guardian model prototype live (8 tests green). BCBS Michigan, Sun Life EDX, Voya PDI, Empower PDI on deck for Phase 1 pilot. SFTP delivery + delta tracking next.
• 401(k) file automation — Empower PDI, Voya payroll, Fidelity tape-spec fixed-width formats.

On the roadmap:

• Payroll Ops Assistant — void/correction workflows, deduction conflict detection, overtime anomaly flags, superbatch reconciliation
• Benefits Admin Assistant — benefit election audits, COBRA eligibility, ACA status, carrier sync verification
• Compliance Assistant — W2/941 reconciliation, garnishment tracking, state tax setup, I-9 audits, workers' comp codes
• AR / Billing Assistant — billing-vs-payroll audits, invoice summaries, employer tax liability
• Branded reporting — Simploy-branded PDF/XLSX via pluggable brand + template registry (white-label ready)
• Microsoft 365 connectors — Graph API email, SharePoint upload, Teams posts, Outlook events/tasks

Tier 3 — prismhr-mcp-broker (paid, hosted) — planned

Multi-tenant hosted MCP endpoint so carriers, ERPs, and EDI providers can reach any PrismHR PEO through a single integration. One endpoint, many tenants, centralized compliance. Deferred until Tier 2 ships with a second PEO.

Interested in Tier 2 or Tier 3? Contact nihar@simploy.com.

Quick start — UAT smoke test

Only UAT is supported without an explicit opt-in right now. Prod is guarded behind PRISMHR_MCP_ALLOW_PROD=true.

1. Install

cd C:\path\to\prismhr-mcp    # or wherever you cloned
uv sync --extra dev

2. Configure credentials