{
  "markdown": "# prismhr-mcp\n\n**The open-source Model Context Protocol (MCP) server for PrismHR.**\nConnect Claude, Cursor, or any MCP-compatible AI agent directly to your\nPrismHR PEO platform. Automate payroll, benefits enrollment, compliance\nreporting, AR/billing, carrier EDI files, and Microsoft 365 actions — with\nverified-schema tools, scope-gated consent, and zero custom integration code.\n\nBuilt for PEOs, brokers, and payroll operators who want **AI agents that\nactually work against PrismHR** — not another brittle script farm.\n\nMaintained by [Simploy](https://simploy.com). MIT-licensed, PyPI-distributed,\nplugin-friendly. The fundamental layer for **PrismHR × agentic AI**.\n\n`mcp-name: io.github.nikulk2992-jpg/prismhr-mcp`\n\n**Keywords:** PrismHR API, PrismHR integration, MCP server, Model Context\nProtocol, PEO automation, payroll automation, AI for HR, Claude for PrismHR,\nagentic AI, benefits enrollment automation, 834 EDI, 401(k) file automation,\nHRIS AI agent, PEO software integration.\n\n---\n\n## Why this exists\n\nEvery PEO running PrismHR ends up with the same Frankenstein stack: Python\nscripts, Postman collections, Playwright automations, one-off Node apps.\nEach one re-implements login, session keepalive, retry logic, pagination,\nand PrismHR's quirks (camelCase schemas, `500 \"No data found\"` gotchas,\nbatch-of-20 caps, silent 401s).\n\n`prismhr-mcp` centralizes all of that once, as a production-grade MCP server.\nThe AI agent orchestrates; the server owns auth, caching, retries,\nnormalization, and PEO domain logic. Any PEO drops it in and gets a\nproductive AI experience against their own PrismHR tenant — no glue code,\nno guesswork, no hallucinated endpoints.\n\n**Who this is for:**\n- PEOs running PrismHR who want to wire Claude / Cursor / ChatGPT Desktop\n  directly into their ops stack\n- Benefit brokers and carriers building enrollment automations\n- Payroll teams replacing brittle Postman / Playwright workflows\n- Consultants shipping PEO AI pilots on tight timelines\n\n---\n\n## Status\n\nProduction-ready core. Live on PyPI and the MCP Registry.\n\n- **Auth + session + HTTP client:** done. 1Password CLI integration,\n  scrypt-encrypted disk credential cache, PrismHR session with proactive\n  keepalive (no mid-workflow 401s), automatic refresh on failure,\n  concurrency cap, retry with jittered backoff, 500→empty quirk handling,\n  pagination, batching.\n- **Verified-schema gate:** every tool grounded in a live UAT probe —\n  **no guessed endpoints, no invented fields**. 102 response shapes\n  verified and rising.\n- **447-method catalog:** full PrismHR REST surface indexed across 18\n  services. `meta_call` lets the agent invoke any verified method safely.\n- **Connect-time consent system:** 15-scope manifest, per-(peo, env) JSON\n  consent store with prerequisite expansion and cascade revoke. Default\n  posture = **deny all**. Tools enforce scope at call time.\n- **Production safety gate:** `PRISMHR_MCP_ALLOW_PROD=true` required to\n  point at prod PrismHR. Prevents accidental first-run blast radius.\n- **MCP Registry listed:** discoverable by every MCP-aware client.\n- **Test suite:** passing via pytest + respx.\n\nSee `.planning/architecture.md` for the full roadmap and\n`.planning/assistants-roadmap.md` for the paid tier details.\n\n---\n\n## What this unlocks for PEOs\n\nOnce wired into your PrismHR tenant, an AI agent (Claude, ChatGPT,\nCursor) can run any of these workflows against live data — read-only\nby default, write actions opt-in and scoped.\n\n### Daily ops\n\n- **New Hire Onboarding Audit** — every new hire checked for missing\n  SSN, address, E-Verify clearance, required deductions, garnishment\n  setup. Flags problems before first paycheck.\n- **Payroll Batch Health Check** — real-time status of every open\n  batch; catches stale INIT, stuck approvals, pay-date-past without\n  post, negative net, missing vouchers.\n- **Terminated Employee Cleanup** — post-termination checklist: final\n  check issued, deductions stopped, benefits ended, COBRA record\n  created, PTO paid out, ACH retired.\n- **Manual Check Audit** — flags off-cycle checks without reason\n  codes, excessive amounts, duplicates within a window, repeat-monthly\n  patterns.\n\n### Compliance\n\n- **ACA Configuration Integrity** — catches the setup errors PrismHR\n  itself flags as the #1 cause of 1094-C/1095-C penalty exposure.\n- **1095-C Value Consistency Audit** — post-generation audit of every\n  1095-C form; flags code 1H posted while employee was enrolled,\n  safe-harbor conflicts, status-type-change-driven code drift,\n  waiting-period miscoding, ICHRA codes used for pre-2020 years.\n- **Dependent Coverage Age-Out** — dependents past the ACA age\n  threshold, or nearing it in the next 30/60/90 days.\n- **COBRA Eligibility Sweep** — qualifying events, notice-window\n  countdown, election-deadline warnings.\n- **Garnishment Payment History** — active garnishments with no\n  payments, overdue remittances, multi-garnishment priority checks.\n- **W-2 Readiness Check** — pre-flight for January: SSN present +\n  correct format, federal withholding configured, YTD sanity.\n\n### Reconciliation\n\n- **YTD Payroll Reconciliation** — bulk year-to-date totals vs sum of\n  voucher history; finds silent drift before W-2 season.\n- **941 Quarterly Reconciliation** — federal tax return tie-out per\n  quarter; wages, FIT, Social Security, Medicare, Additional Medicare.\n- **Benefits-Deduction Audit** — enrolled-but-not-deducted and\n  deducted-but-not-enrolled mismatches; the silent premium leaks.\n- **Billing-vs-Payroll Wash Audit** — per-employee plan-level check.\n- **Billing-vs-Payroll Reconciliation (client level)** — monthly\n  controller tie-out.\n- **401(k) Match Rule Compliance** — employer match vs plan formula,\n  402(g) limit watch, catch-up eligibility for 50+.\n- **401(k) True-Up Calculation** — year-end match owed for employees\n  who hit deferral limit early and lost proportional match.\n\n### Benefits + AR\n\n- **FSA/HSA Contribution Limit Tracker** — IRS 2026 limits watched\n  with over-limit, approaching-limit, and projected-overage findings.\n- **Retirement Loan Status** — default risk + past-term loans +\n  deemed-distribution exposure.\n- **Workers Comp Exposure** — estimated premium per class code per\n  state using current wages × rate × experience modifier.\n- **Outstanding Invoice Aging** — AR bucketing + at-risk-client flag.\n- **PTO Balance Reconciliation** — negative balances, over-cap, stale\n  accrual, missing class assignment.\n- **Doc Expiration Sweep** — I-9 + identity documents expiring in the\n  next 30/60/90 days.\n- **Client Go-Live Readiness** — pre-payroll checklist + readiness\n  score for new PEO clients.\n\n### Carrier + distribution\n\n- **Carrier Enrollment (834 5010)** — generic writer + per-carrier\n  companion-guide configs. Guardian model live; BCBS Michigan, Sun\n  Life EDX, Voya PDI, Empower PDI on the pilot roadmap.\n- **W-2 Distribution Assistant** — bulk download, certified-mail\n  shipping, electronic delivery with consent check, SharePoint\n  archive — all composable.\n\nEvery workflow returns structured findings with severity and\nremediation hints, so an AI agent can chain them into higher-order\nreports (month-end close pack, year-end filing pack, new-client\ngo-live pack, etc.).\n\n**Tiering:** the OSS core is free. The workflows above ship in the\npaid `prismhr-mcp-simploy` tier — source-available, per-PEO license.\nContact `nihar@simploy.com`.\n\n---\n\n## Editions\n\n`prismhr-mcp` ships in three tiers. Core is free forever. Paid tiers layer\ncommercial PEO intelligence on top.\n\n### Tier 1 — `prismhr-mcp` (this repo, MIT, free)\n\nThe foundation. What's in the box:\n\n- PrismHR session manager with keepalive + auto-refresh\n- 447-method catalog + verified-schema `meta_call`\n- Scope-gated consent, prod safety gate, encrypted credential cache\n- `meta_find`, `meta_describe`, `meta_capabilities`\n- Client + employee + payroll read tools grounded in live UAT\n- MCP Registry listing, PyPI distribution\n\nUse this if you want to run Claude against your PrismHR tenant today with\nzero custom code.\n\n### Tier 2 — `prismhr-mcp-simploy` (paid, source-available) — *in active build*\n\nNamed AI Assistants that ship PEO workflows end-to-end. Built on the OSS\ncore. Licensed per-PEO.\n\n**Shipping now:**\n- **Carrier Enrollment Assistant** — generic 834 5010 EDI writer + carrier\n  companion-guide configs. Guardian model prototype live (8 tests green).\n  BCBS Michigan, Sun Life EDX, Voya PDI, Empower PDI on deck for Phase 1\n  pilot. SFTP delivery + delta tracking next.\n- **401(k) file automation** — Empower PDI, Voya payroll, Fidelity\n  tape-spec fixed-width formats.\n\n**On the roadmap:**\n- **Payroll Ops Assistant** — void/correction workflows, deduction\n  conflict detection, overtime anomaly flags, superbatch reconciliation\n- **Benefits Admin Assistant** — benefit election audits, COBRA\n  eligibility, ACA status, carrier sync verification\n- **Compliance Assistant** — W2/941 reconciliation, garnishment tracking,\n  state tax setup, I-9 audits, workers' comp codes\n- **AR / Billing Assistant** — billing-vs-payroll audits, invoice\n  summaries, employer tax liability\n- **Branded reporting** — Simploy-branded PDF/XLSX via pluggable brand +\n  template registry (white-label ready)\n- **Microsoft 365 connectors** — Graph API email, SharePoint upload,\n  Teams posts, Outlook events/tasks\n\n### Tier 3 — `prismhr-mcp-broker` (paid, hosted) — *planned*\n\nMulti-tenant hosted MCP endpoint so carriers, ERPs, and EDI providers can\nreach any PrismHR PEO through a single integration. One endpoint, many\ntenants, centralized compliance. Deferred until Tier 2 ships with a second\nPEO.\n\nInterested in Tier 2 or Tier 3? Contact `nihar@simploy.com`.\n\n---\n\n## Quick start — UAT smoke test\n\n> Only UAT is supported without an explicit opt-in right now. Prod is\n> guarded behind `PRISMHR_MCP_ALLOW_PROD=true`.\n\n### 1. Install\n\n```powershell\ncd C:\\path\\to\\prismhr-mcp    # or wherever you cloned\nuv sync --extra dev\n```\n\n### 2. Configure credentials\n\nCopy `.env.example` → `.env` (or set env vars). Pick ONE path:\n\n**Path A — 1Password CLI (recommended):**\n```powershell\n$env:PRISMHR_MCP_ONEPASSWORD_VAULT = \"YourVault\"\n$env:PRISMHR_MCP_ONEPASSWORD_ITEM_PRISMHR = \"PrismHR UAT\"\n```\nRequires `op` CLI signed in (`op signin`). The item must expose fields\nlabeled `username` and `password` (optionally `peoId`).\n\n**Path B — direct env vars (fast, CI-friendly):**\n```powershell\n$env:PRISMHR_MCP_USERNAME = \"<your-api-username>\"\n$env:PRISMHR_MCP_PASSWORD = \"<paste>\"\n$env:PRISMHR_MCP_PEO_ID   = \"<your-peo-id>\"\n```\n\n### 3. Sanity check\n\n```powershell\nuv run python -c \"from prismhr_mcp.server import build; b = build(); import asyncio; print([t.name for t in asyncio.run(b.server.list_tools())])\"\n```\nExpect 9 tools.\n\n### 4. Register with Claude Code\n\nAdd to your Claude Code `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"prismhr-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"C:\\\\path\\\\to\\\\prismhr-mcp\", \"prismhr-mcp\"],\n      \"env\": {\n        \"PRISMHR_MCP_ENVIRONMENT\": \"uat\",\n        \"PRISMHR_MCP_USERNAME\": \"<your-api-username>\",\n        \"PRISMHR_MCP_PASSWORD\": \"<paste or reference>\",\n        \"PRISMHR_MCP_PEO_ID\": \"<your-peo-id>\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Code. `/mcp` should show `prismhr-mcp` connected with 9 tools.\n\n### 5. First conversation\n\n```\nYou: Tell me about the prismhr-mcp server.\nClaude: [calls meta_about] → explains what's available + commercial options.\n\nYou: What permissions does it want?\nClaude: [calls meta_request_permissions] → shows 14 scopes grouped by category.\n\nYou: Grant everything recommended (reads only, no writes).\nClaude: [calls meta_grant_permissions(accept_recommended_defaults=true)]\n\nYou: List all clients in UAT.\nClaude: [calls client_list] → returns the full client roster.\n```\n\n### 6. Run tests\n\n```powershell\nuv run pytest -q      # expect 60 passing\n```\n\n---\n\n## Architecture in one breath\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ Claude / Cowork / any MCP client                             │\n└──────────────────┬───────────────────────────────────────────┘\n                   │ stdio (MCP JSON-RPC)\n┌──────────────────▼───────────────────────────────────────────┐\n│ prismhr-mcp server (FastMCP)                                 │\n│   ├── Permissions (deny-default, scope-gated tools)          │\n│   ├── Tool groups: meta • client • payroll • benefits        │\n│   │                 compliance • billing • report • m365     │\n│   ├── Runtime: PrismHR client, Graph client, SQLite cache    │\n│   └── Auth: 1Password → scrypt-AES cache → session / MSAL    │\n└────┬─────────────────────────────────────────────────┬───────┘\n     │                                                 │\n     ▼                                                 ▼\n┌──────────────┐                           ┌──────────────────┐\n│ PrismHR REST │                           │ Microsoft Graph   │\n│ (UAT / Prod) │                           │ (Outlook / Teams /│\n└──────────────┘                           │  SharePoint)      │\n                                           └──────────────────┘\n```\n\nKey design commitments:\n- **Factory + strict registry.** Tools register via `server.build()` only;\n  duplicate names or unknown group prefixes fail at boot (not silently at\n  import).\n- **Deny-default scopes.** Users must run `meta_grant_permissions` to\n  enable tool access. Prerequisites auto-expand, revokes cascade.\n- **Async-first.** `httpx.AsyncClient` + `asyncio.Semaphore(5)` + async tools.\n- **PrismHR quirks handled.** 401 auto-refresh, 404→`[]` on list endpoints,\n  `500 \"No data found\"` → empty, 10-consecutive-500s → force refresh.\n- **snake_case outputs.** Pydantic `validation_alias=AliasChoices(...)` so\n  PrismHR's camelCase payloads map to snake_case outputs without leaking\n  camelCase into the MCP tool contract.\n- **Per-(peo, env) consent.** Switching UAT → prod does not inherit grants.\n\n---\n\n## Commercial support\n\nThe OSS core stays free forever. Two paid offerings from Simploy layer on top:\n\n### Solution Architect — White-Label deployment\n\nTurnkey deployment of `prismhr-mcp` for your PEO brand:\n- Brand config authoring (logo, palette, typography, PDF footer, legal disclaimer)\n- Per-client SharePoint site mapping + Azure AD / Graph tenant setup\n- Custom PrismHR tools for PEO-specific workflows\n- Migration from spreadsheets / legacy scripts to MCP tools\n- PEO ops team onboarding + Claude/Cowork workflow coaching\n- Quarterly updates aligned with upstream releases\n- Priority issue response + named Slack/email contact\n\nBest for PEOs with 50–5,000 clients who want Claude-first operations\nwithout the in-house build. Contact: **nihar@simploy.com**\n\n### Enterprise Support\n\nSLA-backed support for teams already running the OSS server:\n- 4-hour response on Sev-1 (prod outage)\n- Annual security review + SOC-2-friendly deployment guidance\n- Signed release artifacts + SBOM\n- Private vulnerability disclosure channel\n\nBest for regulated industries or mid/large PEOs with procurement\nrequirements. Contact: **nihar@simploy.com**\n\nClaude can surface both via `meta_about` — ask \"what commercial options\nexist for prismhr-mcp?\" and it will describe them.\n\n---\n\n## Troubleshooting\n\n**`No PrismHR credentials configured`** — set either the 1Password item\nenv vars or the direct `PRISMHR_MCP_USERNAME`/`_PASSWORD` pair.\n\n**`PrismHR login rejected (status=401)`** — wrong username/password/peo_id.\nThe `peo_id` is tenant-specific; ask your PrismHR admin. Prod and UAT have different values.\n\n**`environment=prod requires PRISMHR_MCP_ALLOW_PROD=true`** — safety gate.\nSet `PRISMHR_MCP_ALLOW_PROD=true` explicitly once you're ready.\n\n**`PERMISSION_NOT_GRANTED`** — tool was called without its scope. Ask\nClaude to run `meta_request_permissions` → then `meta_grant_permissions`\nwith the scope you want.\n\n**Server exits immediately when Claude Code starts it** — nearly always a\nmissing env var. Use the step-3 sanity check to isolate.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE). Contributions welcome; see the planning docs\nunder `.planning/` for the roadmap.\n",
  "bytes": 16063,
  "sha": "9347fb9b07a31dfecfc20d9a982fa71c0fa870881415b6be199fdfdc4c3b9fa1",
  "repo_slug": "nikulk2992-jpg/prismhr-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nikulk2992_jpg_prismhr_mcp_93fff9eb/readme"
}