prismhr-mcp

The open-source Model Context Protocol server for PrismHR. Turn Claude (and any MCP-aware agent) into a PEO operations native — payroll, benefits, compliance, billing, and Microsoft 365 actions, all exposed as composable, scope-gated tools.

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

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

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 refresh, retry, pagination, and PrismHR's quirks (camelCase schemas, 500 "No data found" gotchas, batch-of-20 caps, silent 401s).

prismhr-mcp centralizes that once, as an MCP server. Claude orchestrates; the server owns auth, caching, retries, normalization, and PEO domain logic. Other PEOs drop it in and immediately get a productive Claude experience against their own PrismHR instance — no custom code.

Status

Early but working. Current milestone: Phase 1.5 complete.

• Auth + session + HTTP client: done. 1Password CLI, scrypt-encrypted disk cache, PrismHR session with 55-min TTL, proactive + forced + 401 refresh, keepalive, concurrency cap, retry with jittered backoff, 500→empty quirk handling, pagination, batching.
• Connect-time consent system: done. Scope manifest across 14 scopes, 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.
• Tool inventory: 9 live (meta_* ×5, client_* ×4). 39 more across payroll, benefits, compliance, billing, branded reporting, and M365 connectors planned.
• Test suite: 60 passing (pytest + respx).

See .planning/architecture.md for the full 48-tool plan.

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

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 = "claudedemo"
$env:PRISMHR_MCP_PASSWORD = "<paste>"
$env:PRISMHR_MCP_PEO_ID   = "624*D"

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": "claudedemo",
        "PRISMHR_MCP_PASSWORD": "<paste or reference>",
        "PRISMHR_MCP_PEO_ID": "624*D"
      }
    }
  }
}

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(a

... [View full README on GitHub](https://github.com/nikulk2992-jpg/prismhr-mcp#readme)