io.github.hyperdrift-io/deputy-workforce-mcp

Deputy Workforce Operations MCP

A read-only Model Context Protocol server that turns Deputy workforce records into five grounded, operational workflows for AI assistants.

What a Deputy manager can ask

• “Where are the coverage gaps from 20 to 26 July, using a minimum of two people?”
• “Which combined completed and rostered workloads cross our 40-hour planning threshold?”
• “Show timesheet exceptions above a 15-minute tolerance.”
• “Which rosters overlap recorded unavailability or approved leave?”
• “Summarise staffing by location and day for this week.”

The tools answer those questions directly instead of exposing Deputy's endpoint catalogue.

Representative results

The examples below use fictional records and compact the structured response to the fields a manager can act on.

Coverage gaps

{
  "period": { "start": "2026-07-20", "end": "2026-07-26", "timezone": "Europe/London" },
  "findings": [{ "kind": "coverage_gap", "sources": [{ "resource": "Roster", "id": 1001 }], "rule": "active roster has fewer than 2 people" }],
  "limits": []
}

Overtime risk

{ "period": { "start": "2026-07-20", "end": "2026-07-26", "timezone": "Europe/London" }, "findings": [{ "worker_id": 7, "planned_hours": 43.5, "threshold_hours": 40, "sources": [{ "resource": "Timesheet", "id": 2007 }, { "resource": "Roster", "id": 1007 }], "rule": "completed plus remaining rostered hours exceeds threshold" }], "limits": [] }

Timesheet exceptions

{ "period": { "start": "2026-07-20", "end": "2026-07-26", "timezone": "Europe/London" }, "findings": [{ "kind": "start_time_variance", "roster_id": 1002, "minutes": 22, "tolerance_minutes": 15, "sources": [{ "resource": "Roster", "id": 1002 }, { "resource": "Timesheet", "id": 2002 }], "rule": "timesheet start differs from roster beyond tolerance" }], "limits": [] }

Availability conflicts

{ "period": { "start": "2026-07-20", "end": "2026-07-26", "timezone": "Europe/London" }, "findings": [{ "kind": "recorded_unavailability_conflict", "sources": [{ "resource": "Roster", "id": 1002 }, { "resource": "EmployeeAvailability", "id": 4001 }], "rule": "roster interval overlaps recorded unavailability" }], "limits": [] }

Staffing summary

{ "period": { "start": "2026-07-20", "end": "2026-07-26", "timezone": "Europe/London" }, "findings": [{ "location": "North", "day": "2026-07-21", "rostered_hours": 16, "completed_hours": 12, "assigned": 3, "unassigned": 1, "sources": [{ "resource": "Roster", "id": 1008 }, { "resource": "Timesheet", "id": 2008 }], "rule": "group roster and timesheet hours by location and local day" }], "limits": [] }

Every finding names its period, source record identifiers, and the rule or threshold that produced it. Empty data gives a confidence limit rather than a false all-clear.

Safety and data handling

• Every tool is read-only, idempotent, and non-destructive.
• The server never creates or changes shifts, timesheets, leave, payroll, or employee data.
• Workload thresholds are operational planning signals, not payroll, employment, or legal advice.
• Telemetry excludes tool arguments, employee and location IDs, dates, result content, and tokens.
• Standard MCP analytics are disabled unless the deployment owner provides a PostHog project token; the privacy allowlist is documented in PRIVACY.md.
• V1 is single-tenant by deployment: one Deputy installation and one MCP bearer token per instance.
• Authentication, bounded HTTP transport, rate limiting, structured results, and stdio lifecycle use MCP Maker's shared @hyperdrift-io/mcp-service-kit; Deputy keeps its provider and workflow logic.

See SECURITY.md and PRIVACY.md for the complete contracts.

Local installation

Node.js 22 or later is required; npm ships with it. The quickest safe inspection uses the public package and fictional fixture data:

DEPUTY_MODE=fixture npx -y @hyperdrift-io/deputy-workforce-mcp@latest

For a visible tool-list and tool-call proof, see the fixture demonstration. The package is also distributed through the official MCP Registry and as a one-file MCP Bundle on Smithery. Maintainers can reproduce the local bundle with:

npm run mcpb:pack

To work from source:

git clone https://github.com/hyperdrift-io/deputy-workforce-mcp.git
cd deputy-workforce-mcp
npm install
npm run build
DEPUTY_MODE=fixture node dist/stdio.js

Fixture mode contains fictional Worker 01-style records and is safe for evaluation. To connect a Deputy installation, copy .env.example to .env.local, choose DEPUTY_MODE=live, and provide a customer-owned base URL and OAuth access token. Live resource shapes still require the first sandbox verification recorded in docs/DEPUTY_API.md.

Example client configuration:

{
  "mcpServers": {
    "deputy-workforce": {
      "command": "node",
      "args": ["/absolute/path/to/deputy-workforce-mcp/dist/stdio.js"],
      "env": { "DEPUTY_MODE": "fixture" }
    }
  }
}

Remote deployment

The same five tools can run over authenticated streamable HTTP. Remote mode requires an MCP bearer token of at least 32 bytes, authenticates before parsing requests, limits bodies to 1 MiB, and uses bounded in-memory rate protection.

DEPUTY_MODE=fixture \
MCP_BEARER_TOKEN="replace-with-at-least-32-random-bytes" \
PORT=3013 \
npm start

• Health: GET /health
• MCP: authenticated POST /mcp

See docs/DEPLOYMENT.md before operating a remote instance.

Tool reference

The server registers exactly five tools:

• find_coverage_gaps
• flag_overtime_risk
• list_timesheet_exceptions
• find_availability_conflicts
• summarise_staffing

Inputs, rules, and output limits are documented in docs/TOOLS.md.

Status

Fixture mode, stdio, and authenticated streamable HTTP are operational. Live Deputy mode remains explicitly pending a customer-owned sandbox token and field-shape verification. The public API is still in prototype discovery and may evolve from real workflow feedback.

Built as MCP Maker delivery 001

Deputy Workforce Operations MCP is the flagship public implementation from MCP Maker: Hyperdrift turns established SaaS APIs into secure, production-ready AI integrations.

The open-source core remains useful on its own. MCP Maker offers managed deployment, security hardening, custom workflows, and operational support for organisations that want a production integration tailored to their environment.