# The Winslow MCP

One server. Every Winslow capability. Connect Claude, ChatGPT, Cursor, Lovable, or any MCP-capable agent to the same API your admin UI uses — full read/write, gated by role, audited on every action.

## What is the Winslow MCP?

### One protocol, every Winslow capability.

The Winslow MCP server is a Model Context Protocol endpoint that exposes **50+ first-class tools** covering employees, payroll, benefits, documents, time off, approvals, custom properties, and your agent runtime. It uses the same authorization layer as the admin UI — agents inherit the role of the API key, not a separate "service" permission.

- **Full read/write** — not a read-only wrapper around a public API  
- **Workspace-scoped** — API keys resolve workspace automatically  
- **Per-field role gating** — agents see and write what the key's role allows  
- **Audit log** — every agent action is a first-class event, exportable to your SIEM  
- **Webhooks + events** — agents can subscribe to hires, terminations, writes, comp changes

## Supported tools

### 50+ tools, organized by domain.

Every tool listed below is callable through the MCP endpoint with the auth model described above. Parameter shorthand uses ? for optional, with the most common required params shown first.

- **[Workspace & Identity](/content/builders/mcp/#cat-workspace/index.html)**  
- **[Employees](/content/builders/mcp/#cat-employees/index.html)**  
- **[Organization](/content/builders/mcp/#cat-org/index.html)**  
- **[Employee Documents](/content/builders/mcp/#cat-documents/index.html)**  
- **[Benefits](/content/builders/mcp/#cat-benefits/index.html)**  
- **[Payroll](/content/builders/mcp/#cat-payroll/index.html)**  
- **[Payroll Adjustments](/content/builders/mcp/#cat-adjustments/index.html)**  
- **[Contractor Invoices](/content/builders/mcp/#cat-invoices/index.html)**  
- **[Approvals](/content/builders/mcp/#cat-approvals/index.html)**  
- **[Time Off & Holidays](/content/builders/mcp/#cat-time-off/index.html)**  
- **[Terminations](/content/builders/mcp/#cat-terminations/index.html)**  
- **[Custom Properties](/content/builders/mcp/#cat-custom-properties/index.html)**  
- **[Artifacts](/content/builders/mcp/#cat-artifacts/index.html)**  
- **[Winslow Events](/content/builders/mcp/#cat-events/index.html)**  
- **[AI & Knowledge Base](/content/builders/mcp/#cat-ai/index.html)**  
- **[OAuth App Management](/content/builders/mcp/#cat-oauth/index.html)**  
- **[Feedback](/content/builders/mcp/#cat-feedback/index.html)**  
- **[API Documentation](/content/builders/mcp/#cat-api-docs/index.html)**

### Workspace & Identity

#### Tool
- **get_workspace**  
  Get the workspace associated with the calling API key (id, name).

#### Parameters
- —

- **get_me**  
  Get the user tied to the API key and any linked employee record.

#### Parameters
- —

### Employees

#### Tool
- **get_employee**  
  Look up one employee by record id. Returns system + custom properties.

#### Parameters
- employeeRecordId

- **list_employees**  
  List employees. Defaults to W-2 / full-time; pass `employeeTypes` to widen.

#### Parameters
- workspaceId?, includeInactive?, employeeTypes?

### Organization

#### Tool
- **list_departments**  
  List departments derived from the system-department dropdown.

#### Parameters
- workspaceId?

- **list_org_chart**  
  Get the active org hierarchy as a tree.

#### Parameters
- workspaceId?

### Employee Documents

#### Tool
- **list_employee_documents**  
  List documents for one employee. Optionally filter by type.

#### Parameters
- employeeRecordId, type?

- **get_employee_document**  
  Look up document metadata. Returns a `publicLink` (cloud URL).

#### Parameters
- employeeRecordId, employeeDocumentId

- **find_employee_documents**  
  Ranked search across an employee's documents by name or agentData.

#### Parameters
- employeeRecordId, searchQuery, type?, limit?

- **upload_employee_document**  
  Upload base64 file (≤100 MB). Creates the document and cloud storage entry.

#### Parameters
- employeeRecordId, fileName, fileBase64, type?

- **get_employee_document_resource**  
  Return document bytes as an MCP embedded resource (≤50 MB).

#### Parameters
- employeeRecordId, employeeDocumentId

- **get_employee_document_content**  
  Extract text (PDF/DOCX/MD/TXT) or render PDF pages as PNG (≤10 pages).

#### Parameters
- employeeRecordId, employeeDocumentId, format

- **set_employee_document_validation**  
  Set agent-side validation flag and/or agentData on a document.

#### Parameters
- employeeRecordId, employeeDocumentId, validation?, agentData?

### Benefits

#### Tool
- **get_employee_benefits**  
  Medical, dental, vision summary for the current coverage timeline.

#### Parameters
- employeeRecordId

- **get_employee_benefit_spd**  
  Download SPD PDFs from enrolled plans. Returns base64 resources.

#### Parameters
- employeeRecordId, planTypes?

### Payroll

#### Tool
- **get_payroll**  
  Fetch one payroll run with full line items and contractor payments.

#### Parameters
- payrollId

- **list_payrolls**  
  List payroll runs. Filter by payday date range.

#### Parameters
- workspaceId?, paydayAfter?, paydayBefore?, limit?

### Payroll Adjustments

#### Tool
- **list_payroll_adjustment_templates**  
  List recurring adjustment templates.

#### Parameters
- workspaceId?

- **get_payroll_adjustment_template**  
  Get one template by id.

#### Parameters
- templateId

- **create_payroll_adjustment_template**  
  Create a template with targeting + amount rules (one-time, monthly, half-month).

#### Parameters
- name, targetType, recurrenceType, amountType, …

- **update_payroll_adjustment_template**  
  Partial update of a template.

#### Parameters
- templateId, …

- **delete_payroll_adjustment_template**  
  Delete a template by id.

#### Parameters
- templateId

- **list_payroll_adjustments**  
  List adjustment instances. Filter by payroll or employee.

#### Parameters
- workspaceId?, checkPayrollId?, employeeRecordId?

- **get_payroll_adjustment**  
  Get one adjustment instance by id.

#### Parameters
- adjustmentId

- **create_payroll_adjustment**  
  Create a one-off adjustment, optionally linked to a template or payroll.

#### Parameters
- employeeRecordId, name, amount, checkPayrollItemType, …

- **update_payroll_adjustment**  
  Update an instance. Syncs the change back to the payroll engine.

#### Parameters
- adjustmentId, …

- **delete_payroll_adjustment**  
  Delete an instance and remove linked engine earnings.

#### Parameters
- adjustmentId

### Contractor Invoices

#### Tool
- **create_invoice**  
  Submit a contractor invoice (PDF URL + metadata).

#### Parameters
- employeeRecordId, employeeInvoiceNumber, submissionDate, dueDate, amount, cloudURL, note?

- **approve_invoice**  
  Approve a submitted invoice.

#### Parameters
- invoiceId

- **reject_invoice**  
  Reject an invoice. Not allowed once linked to a payroll.

#### Parameters
- invoiceId

- **unapprove_invoice**  
  Move an approved invoice back to SUBMITTED.

#### Parameters
- invoiceId

- **cancel_invoice**  
  Hard-delete an invoice. Not allowed once linked to a payroll.

#### Parameters
- invoiceId

### Approvals

#### Tool
- **get_approval_state**  
  Get the status of an approval task.

#### Parameters
- approvalId

- **update_approval**  
  Update name, description, or status (ACCEPTED / REJECTED / CANCELLED).

#### Parameters
- approvalId, name?, description?, status?

- **cancel_approval**  
  Cancel a non-terminal approval task.

#### Parameters
- approvalId

### Time Off & Holidays

#### Tool
- **list_time_off**  
  List PENDING and APPROVED requests. Defaults to current month.

#### Parameters
- workspaceId?, startDate?, endDate?

- **approve_request**  
  Approve or reject a time-off request.

#### Parameters
- timeOffRequestId, status

- **list_company_holidays**  
  Resolve company holidays for a year, including floating dates.

#### Parameters
- workspaceId?, year?

### Terminations

#### Tool
- **list_terminations**  
  List all termination records for the workspace.

#### Parameters
- workspaceId?

### Custom Properties

#### Tool
- **list_custom_properties**  
  List the workspace's custom properties (excludes app-namespaced).

#### Parameters
- workspaceId?

- **list_app_properties**  
  List custom properties created by one app (prefixed with appId).

#### Parameters
- appId

- **create_app_property**  
  Create an app-namespaced custom property. Label is auto-prefixed with `appId-`.

#### Parameters
- appId, label, display, type, required?, settings?, group?

### Artifacts

#### Tool
- **list_artifacts**  
  List artifacts on one employee, optionally filtered by appId.

#### Parameters
- employeeRecordId, appId?

- **get_artifact**  
  Retrieve one artifact by id.

#### Parameters
- artifactId

- **create_artifact**  
  Create an artifact on an employee record. Auto-registers the app on first use.

#### Parameters
- employeeRecordId, appId, type, …

- **update_artifact**  
  Merge-update an artifact. Omitted fields are preserved.

#### Parameters
- artifactId, …

- **delete_artifact**  
  Remove an artifact from an employee record.

#### Parameters
- artifactId

- **list_artifact_apps**  
  List all apps storing data on employees in the workspace.

#### Parameters
- —

- **register_artifact_app**  
  Explicitly register an app namespace. Usually not needed.

#### Parameters
- appId, name, description, faviconUrl?

### Winslow Events

#### Tool
- **poll_winslow_events**  
  Poll events after a millisecond cursor. Ascending by `firedAt, id`. Up to 1,000 per call.

#### Parameters
- sinceMs, workspaceId?, agentStatusFilter?

- **set_winslow_event_agent_fields**  
  Set `agentStatus` and/or `agentData` on an event row. No new events emitted.

#### Parameters
- winslowEventId, agentStatus?, agentData?

### AI & Knowledge Base

#### Tool
- **ask_policy_question**  
  Ask a question against the workspace knowledge base (uploaded HR policies, handbooks). Context-aware to the asker.

#### Parameters
- question

- **ask_reporting_question**  
  Ask a natural-language reporting question. Returns structured tabular data.

#### Parameters
- question

### OAuth App Management

#### Tool
- **register_oauth_app**  
  Register an OAuth app. Returns credentials, code snippets, .env content, and the auth URL.

#### Parameters
- name, redirectUris, scopes, description?, framework?

- **list_oauth_apps**  
  List OAuth apps registered in the workspace.

#### Parameters
- —

- **delete_oauth_app**  
  Deactivate an OAuth app. Existing tokens work until expiry; no new tokens are issued.

#### Parameters
- clientId

### Feedback

#### Tool
- **report_bug**  
  Open a bug report on the MCP API.

#### Parameters
- title, description?, toolName?, agentContext?

- **suggest_improvement**  
  Suggest an improvement to the MCP API.

#### Parameters
- title, description?, toolName?, agentContext?

### API Documentation

#### Tool
- **get_api_docs**  
  Get Winslow API documentation (OAuth, REST, MCP, auth, quickstart) inline.

#### Parameters
- section?

## Sample prompts

### What it looks like in practice.

Real prompts you can drop into Claude or ChatGPT once your MCP is connected. The right-hand side shows the tools the model picks up to answer.

"Who's on PTO next week and is anyone managing more than 8 direct reports?"  
→ list_time_off + list_org_chart + list_employees

"Pay everyone in the Boston office a $500 spot bonus on the next payroll."  
→ list_employees (filter by office) → create_payroll_adjustment (per employee)

"Find Cooper's signed offer letter and check it's been countersigned."  
→ find_employee_documents + get_employee_document_content + set_employee_document_validation

"Build me a dashboard of comp by department for engineering."  
→ ask_reporting_question (natural-language) or list_employees + list_departments

"What does our parental leave policy say for someone in NY on the PPO plan?"  
→ ask_policy_question (context-aware: pulls plan + state from the asker's record)

## Build something in an afternoon.

Point your favorite agent at the MCP and build the People-team tool you've been waiting on procurement for. We'll show you how if you want help — or get out of your way if you don't.