prismhr-mcp
Enables secure credential storage and retrieval using 1Password CLI for authenticating with PrismHR.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@prismhr-mcp run a new hire onboarding audit for this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: MCP FactorialHR
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_calllets 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=truerequired 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_callScope-gated consent, prod safety gate, encrypted credential cache
meta_find,meta_describe,meta_capabilitiesClient + 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 dev2. Configure credentials
Copy .env.example → .env (or set env vars). Pick ONE path:
Path A — 1Password CLI (recommended):
$env:PRISMHR_MCP_ONEPASSWORD_VAULT = "YourVault"
$env:PRISMHR_MCP_ONEPASSWORD_ITEM_PRISMHR = "PrismHR UAT"Requires op CLI signed in (op signin). The item must expose fields
labeled username and password (optionally peoId).
Path B — direct env vars (fast, CI-friendly):
$env:PRISMHR_MCP_USERNAME = "<your-api-username>"
$env:PRISMHR_MCP_PASSWORD = "<paste>"
$env:PRISMHR_MCP_PEO_ID = "<your-peo-id>"3. Sanity check
uv 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())])"Expect 9 tools.
4. Register with Claude Code
Add to your Claude Code .mcp.json:
{
"mcpServers": {
"prismhr-mcp": {
"command": "uv",
"args": ["run", "--directory", "C:\\path\\to\\prismhr-mcp", "prismhr-mcp"],
"env": {
"PRISMHR_MCP_ENVIRONMENT": "uat",
"PRISMHR_MCP_USERNAME": "<your-api-username>",
"PRISMHR_MCP_PASSWORD": "<paste or reference>",
"PRISMHR_MCP_PEO_ID": "<your-peo-id>"
}
}
}
}Restart Claude Code. /mcp should show prismhr-mcp connected with 9 tools.
5. First conversation
You: Tell me about the prismhr-mcp server.
Claude: [calls meta_about] → explains what's available + commercial options.
You: What permissions does it want?
Claude: [calls meta_request_permissions] → shows 14 scopes grouped by category.
You: Grant everything recommended (reads only, no writes).
Claude: [calls meta_grant_permissions(accept_recommended_defaults=true)]
You: List all clients in UAT.
Claude: [calls client_list] → returns the full client roster.6. Run tests
uv run pytest -q # expect 60 passingArchitecture in one breath
┌──────────────────────────────────────────────────────────────┐
│ Claude / Cowork / any MCP client │
└──────────────────┬───────────────────────────────────────────┘
│ stdio (MCP JSON-RPC)
┌──────────────────▼───────────────────────────────────────────┐
│ prismhr-mcp server (FastMCP) │
│ ├── Permissions (deny-default, scope-gated tools) │
│ ├── Tool groups: meta • client • payroll • benefits │
│ │ compliance • billing • report • m365 │
│ ├── Runtime: PrismHR client, Graph client, SQLite cache │
│ └── Auth: 1Password → scrypt-AES cache → session / MSAL │
└────┬─────────────────────────────────────────────────┬───────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ PrismHR REST │ │ Microsoft Graph │
│ (UAT / Prod) │ │ (Outlook / Teams /│
└──────────────┘ │ SharePoint) │
└──────────────────┘Key design commitments:
Factory + strict registry. Tools register via
server.build()only; duplicate names or unknown group prefixes fail at boot (not silently at import).Deny-default scopes. Users must run
meta_grant_permissionsto enable tool access. Prerequisites auto-expand, revokes cascade.Async-first.
httpx.AsyncClient+asyncio.Semaphore(5)+ async tools.PrismHR quirks handled. 401 auto-refresh, 404→
[]on list endpoints,500 "No data found"→ empty, 10-consecutive-500s → force refresh.snake_case outputs. Pydantic
validation_alias=AliasChoices(...)so PrismHR's camelCase payloads map to snake_case outputs without leaking camelCase into the MCP tool contract.Per-(peo, env) consent. Switching UAT → prod does not inherit grants.
Commercial support
The OSS core stays free forever. Two paid offerings from Simploy layer on top:
Solution Architect — White-Label deployment
Turnkey deployment of prismhr-mcp for your PEO brand:
Brand config authoring (logo, palette, typography, PDF footer, legal disclaimer)
Per-client SharePoint site mapping + Azure AD / Graph tenant setup
Custom PrismHR tools for PEO-specific workflows
Migration from spreadsheets / legacy scripts to MCP tools
PEO ops team onboarding + Claude/Cowork workflow coaching
Quarterly updates aligned with upstream releases
Priority issue response + named Slack/email contact
Best for PEOs with 50–5,000 clients who want Claude-first operations without the in-house build. Contact: nihar@simploy.com
Enterprise Support
SLA-backed support for teams already running the OSS server:
4-hour response on Sev-1 (prod outage)
Annual security review + SOC-2-friendly deployment guidance
Signed release artifacts + SBOM
Private vulnerability disclosure channel
Best for regulated industries or mid/large PEOs with procurement requirements. Contact: nihar@simploy.com
Claude can surface both via meta_about — ask "what commercial options
exist for prismhr-mcp?" and it will describe them.
Troubleshooting
No PrismHR credentials configured — set either the 1Password item
env vars or the direct PRISMHR_MCP_USERNAME/_PASSWORD pair.
PrismHR login rejected (status=401) — wrong username/password/peo_id.
The peo_id is tenant-specific; ask your PrismHR admin. Prod and UAT have different values.
environment=prod requires PRISMHR_MCP_ALLOW_PROD=true — safety gate.
Set PRISMHR_MCP_ALLOW_PROD=true explicitly once you're ready.
PERMISSION_NOT_GRANTED — tool was called without its scope. Ask
Claude to run meta_request_permissions → then meta_grant_permissions
with the scope you want.
Server exits immediately when Claude Code starts it — nearly always a missing env var. Use the step-3 sanity check to isolate.
License
MIT — see LICENSE. Contributions welcome; see the planning docs
under .planning/ for the roadmap.
Available Tools
18 toolsclient_employeeA
Pull full profile detail for one or more employees.
Use when the user asks "show me John's full record" or "get details on these five employees at Acme". Returns the complete employee profile: name, hire/termination dates, pay group, status, and the termination reason if applicable.
Inputs: client_id (required), employee_ids (required). Returns: employees, missing_ids
client_employeesA
List the employees at a single client.
Use when the user says "who works at Acme" or "show me active employees at client XYZ". Returns each employee's ID, name, work email, hire date, and status.
Inputs: client_id (required), status. Returns: client_id, employees, count
client_employee_searchA
Find an employee by name or email, across every client at once.
Use when the user says "find Jane Doe" or "is there anyone named
Smith in our system" without knowing which client they're at. Slow
path because it walks every client, so prefer client_employees
when you already know the client.
Inputs: query (required), status, client_ids. Returns: Results of a cross-client employee search.
client_listA
List every client the current PEO account can see.
Use when the user says "show me the clients" or "which companies are on our platform". Returns each client's ID, name, and active status. Most other tools need a client ID, so call this first when you don't have one.
Inputs: no named parameters. Returns: clients, count
meta_aboutA
Describe what this MCP server is, who runs it, and what commercial options exist.
Always callable — no scope required. Surfaces commercial offerings (Solution Architect white-label, Enterprise support) so Claude can help users understand what's available beyond the free OSS core.
Inputs: no named parameters. Returns: Public server metadata. Safe to call without any scope grants.
meta_callA
Generic, schema-validated invocation of any PrismHR method in the catalog.
Pre-flight: checks the method_id, refuses admin services, validates required query + header + body fields against the bundled bible schemas. Only after validation passes does the request hit PrismHR.
Every call returns a structured PrismHRCallResponse — ok | prismhr_error
| validation_error | admin_blocked | unverified_warning. The
unverified_warning status is attached when the call succeeds but
the response shape has not been verified by the maintainer's probe
pass; treat the body as best-effort.
Inputs: method_id (required), args (required). Returns: method_id, status, http_status, prismhr_error_code, +3 more
meta_capabilitiesA
What does this server know how to call against PrismHR?
Returns counts (catalog size, verified, admin-blocked, unprobed) and
a sample of callable methods. Use this when the user asks 'what can
you do?' or before picking a specific method via meta_describe.
Inputs: service, verified_only, limit. Returns: catalog_size, verified_count, admin_blocked_count, unprobed_count, +3 more
meta_describeA
Full contract for a single PrismHR method.
Returns every parameter, inline body schema (when available), response
codes, and verification status. Call this before prismhr_call so
you know exactly which args the method wants.
Inputs: method_id (required). Returns: method_id, path, http_method, service, +17 more
meta_findA
Find PrismHR methods by intent.
Use when you don't know the exact method id. Claude should pick the
best hit + follow up with meta_describe to see the contract.
Inputs: query (required), limit. Returns: result
meta_grant_permissionsA
Grant, revoke, or replace the set of scopes this server may use.
Prerequisite scopes are auto-included: granting 'employee:read' also grants 'client:read' because the search tool needs it. Revoking a prerequisite cascades — dependent scopes get dropped to stay consistent.
Inputs: granted, revoked, replace, accept_recommended_defaults. Returns: Result of a grant/revoke/replace operation.
meta_list_permissionsA
Show the currently granted scopes without the full manifest.
Use this when you just want to know what's active right now. Use meta_request_permissions to see the full catalog.
Inputs: no named parameters. Returns: environment, peo_id, granted, granted_count, +1 more
meta_pingA
Health check. Returns server name, version, and UTC time.
Always callable — no scope required. Use this to confirm the server is reachable before worrying about credentials or permissions.
Inputs: no named parameters. Returns: Output of `meta_ping` — server liveness probe.
meta_request_permissionsA
List every scope the server can request, grouped by category.
Returns: the full manifest, which scopes are currently granted,
the server's recommended defaults (reads = yes, writes = no),
and a human-readable message to show the user. Call
meta_grant_permissions next with the scopes the user approves.
Inputs: no named parameters. Returns: What the MCP can do + what the user has granted so far.
meta_upstream_permissionsA
Ask PrismHR which API methods this account is actually allowed to call.
Calls /login/v1/getAPIPermissions. If the account lacks a method,
even a fully-scope-granted MCP tool will 403 at the PrismHR edge.
Use this to diagnose 'permission denied' errors when
meta_list_permissions shows the scope is granted.
Always callable — no scope required.
Inputs: no named parameters. Returns: What PrismHR authorizes the current API account to call. Distinct from `meta_li…
payroll_batch_statusA
Find the payroll batches a client ran in a date window.
Use when the user asks things like "what payrolls ran at Acme in March" or "show me this quarter's batches for client ABC". Returns batch IDs, pay dates, status, voucher counts, and gross totals.
Inputs: client_id (required), start_date (required), end_date (required). Returns: client_id, start_date, end_date, batches, +1 more
payroll_pay_group_checkA
Check whether an employee is set up to be paid (pay group assigned).
Use when the user asks "why didn't Jane get paid" or "is this new hire ready for payroll". Returns whether a pay group is assigned and the pay frequency (weekly/biweekly/etc). Unassigned pay group is the #1 reason an employee is skipped in a payroll run.
Inputs: client_id (required), employee_id (required). Returns: client_id, employee_id, pay_group_id, pay_group_name, +3 more
payroll_pay_historyA
Get an employee's paychecks in a date window, plus year-to-date totals.
Use when the user asks "what did Jane get paid this quarter" or "pull up John's checks for Q1". Returns each paycheck (gross, net, regular/overtime hours) plus YTD gross/net/taxes.
Inputs: client_id (required), employee_id (required), start_date (required), end_date (required). Returns: client_id, employee_id, start_date, end_date, +3 more
payroll_superbatch_statusA
Summarize a client's payroll cycle health across a date range.
Use for morning-of-pay status checks: "how's Acme's payroll looking this week" or "show me everything that's open vs. posted for client XYZ this quarter". Counts batches by status (open / pending / posted / voided) and totals gross payroll across them.
Inputs: client_id (required), start_date (required), end_date (required). Returns: Aggregated view across a date range — mirrors PrismHR's SuperBatch UI.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool has a clearly distinct purpose, organized into client, meta, and payroll namespaces. No two tools overlap in functionality; even client_employee, client_employees, and client_employee_search handle different retrieval scenarios.
Tools consistently use a namespace prefix (client_, meta_, payroll_) followed by descriptive names. Minor inconsistency exists between singular (client_employee) and plural (client_employees) forms, and suffix patterns vary (e.g., batch_status vs pay_group_check), but overall the naming is predictable and clear.
With 18 tools, the server is slightly above the ideal 3-15 range but still well-scoped for the complexity of HR/payroll operations. Each tool earns its place, covering client management, employee search/detail, payroll status, and extensive meta operations.
The server provides excellent read-oriented coverage for clients, employees, and payroll. While write operations (update/delete employees, run payroll) are absent, the meta_call tool allows invocation of any PrismHR method, making the surface extensible. Minor gaps exist for common write workflows.
Maintenance
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Related MCP Servers
FlicenseNot gradedqualityFmaintenanceMCP server that lets AI agents execute structured business processes by exposing process steps as tools with a sequenced event bus to prevent skipping steps.1-- AlicenseNot gradedqualityBmaintenanceA comprehensive MCP server that provides AI assistants with full access to FactorialHR to manage employees, teams, time off, projects, training, recruiting, and more, all with built-in safety guardrails.466 npm3MIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server enables AI-assisted professional profile generation by connecting to verified employee work data (skills, career history, certifications, projects) from employer HCM systems.MIT
- AlicenseAqualityBmaintenanceAn MCP server that lets AI models interact with Oracle Fusion Cloud HCM across its entire REST surface. It uses generic, schema-aware tools to dynamically discover licensed modules and resources without per-endpoint code.6Apache 2.0