# workday-mcp

Read-only MCP server for [Workday](https://www.workday.com/). Reads your
Workday org chart, worker profiles, pay, benefits, performance, and any task or
data card, and returns them as structured JSON. Every request routes through your own signed-in
`*.myworkday.com` tab via the [ContextMint Bridge](https://github.com/nullnet-app/contextmint-bridge)
browser extension, reusing your existing SSO-authenticated session.

> ⚠️ Workday gives employees no personal API. This server reads the same internal
> `*.htmld` endpoints the Workday web app calls, dispatched through your own
> signed-in browser tab. It is **read-only** and touches only your own data.
> Check your employer's acceptable-use policy. Use at your own discretion.
>
> 🤖 This project was developed and is maintained by AI (Claude Code).

## Why a bridge instead of the official API?

The official Workday REST/SOAP API requires a tenant administrator to register
an OAuth API client + Integration System User — an employee can't self-provision
it. Tenants also sit behind corporate SSO (Ping/Okta/Entra) with MFA, so there's
no server-side login. The only surface an employee can reach for their own data
is their **live browser session**, which is what this server relays.

## Install

See [SKILL.md](./skills/workday-mcp/SKILL.md) for full setup. In brief:

```json
{
  "mcpServers": {
    "workday": {
      "command": "npx",
      "args": ["-y", "workday-mcp"],
      "env": { "WORKDAY_TENANT": "your-tenant-slug" }
    }
  }
}
```

Then install ContextMint Bridge from its
[releases page](https://github.com/nullnet-app/contextmint-bridge/releases)
(Chrome: unzip the chrome zip and load it unpacked in `chrome://extensions`;
Safari is not available yet — it will ship inside the ContextMint app, which has
no public download link, so use Chrome for now) and sign into Workday in your browser.

ContextMint Bridge is the fetchproxy browser extension under its new name, from
the same maintainer — fetchproxy's own
[README](https://github.com/chrischall/fetchproxy#extension) points to it. Its
source is public at <https://github.com/nullnet-app/contextmint-bridge>: build it
yourself, or check a release zip against the `.sha256` file published beside it
(`shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256`).

## Tools

| Tool | What it does |
| --- | --- |
| `workday_get_apps` | List your Workday apps with launchable task ids — the discovery entry point |
| `workday_open_app` | Open an app **by name** ("Talent and Performance", "Absence") and follow it down to the child cards holding its real content |
| `workday_get_task` | Read any task/data card by id or path → fields, full table rows, references, related tasks, export links. `expand: true` crawls hub pages |
| `workday_get_org_chart` | Your reporting chain — each person with title, location, report count, and a `profileUri` to drill into |
| `workday_get_worker` | A worker's profile: the **catalog** of everything readable about them (9 sections, ~40 named tasks) |
| `workday_get_worker_task` | Open one named item from that catalog — "Compensation", "Performance Reviews", "Management Chain" |
| `workday_get_my_profile` | The same catalog, for yourself |
| `workday_get_team` | The people on the teams you manage — each with worker id, position, location and profile link |
| `workday_get_reviews` | A worker's performance reviews (period, rating), or one review in full: manager and employee ratings and comments, goals, development items |
| `workday_get_feedback_status` | Every feedback request you made, on yourself or your team — who has answered, who is still to, and the answers |
| `workday_get_feedback` | Feedback you or a team member received, gave, or requested — grouped by item, every answer with its author; requests show who has answered and who is still to |
| `workday_get_inbox` | Your inbox ("My Tasks"): review comments to provide, feedback requests, questionnaires, approvals — each with a `uri` to open read-only. `category: "archive"` for completed items. Also takes `view: "brief"` (additive to `compact`/`full`): one line per task, `<title> — <ISO date | no date> — <status>`, in the untrusted-data envelope, with `-- ` note lines (`-- none`, `-- N of M shown`) |
| `workday_get_my_requests` | The requests you created (e.g. promotion consideration forms) with their status |
| `workday_get_team_snapshot` | One table of everyone in your organization — grade, job profile, last promotion, rating, pay — from the My Team hub's associates report |
| `workday_get_request` | Your open requests (e.g. promotion forms you started), or one request's questions with its saved answers |
| `workday_update_request` | **Write.** Change answers on an open request and Save for Later or Submit it — confirmation-token gated, verified by re-read |
| `workday_get_request_form` | A request type's form (e.g. a promotion consideration form): instructions plus every question, required flag, answer type and options. Opens a new request to read it and cancels it before returning, so nothing is created |
| `workday_get_benefits` | Your current benefit elections — plan, coverage, dependents, beneficiaries, what you and the company pay per period — or your dependents, beneficiaries, election history |
| `workday_get_benefit_enrollment` | An open enrollment event, read without changing it: the deadline, what's elected if you do nothing, cost changes vs today, and every plan on offer with prices (`rates: true` adds the price at each coverage level) |
| `workday_update_benefit_enrollment` | **Write.** Choose or waive plans and set HSA/FSA amounts in an open enrollment, then Save for Later or sign and Submit — confirmation-token gated, verified by re-read |
| `workday_run_report` | Run a report by task id (`1422$242`), its browser URL, or its name on one of your dashboards, and get its rows keyed by column. Prompt reports run with their defaults, or with `prompts` you pass by label; the prompt form is always cancelled afterwards and business-process forms are refused |
| `workday_get_dashboard` | A dashboard (e.g. "Year End Dashboard") by name: every tab's worklets and report links, each with a `reportId` for `workday_run_report`; `run: true` runs every worklet too |
| `workday_give_feedback` | **Write.** Give a colleague feedback, optionally with a badge and a `sharing` choice (`everyone` / `private` / `confidential`) — confirmation-token gated; the preview shows the recipient, badge and visibility as Workday resolved them, verified by re-read |
| `workday_request_feedback` | **Write.** Ask colleagues for feedback on yourself, or (as a manager) on someone on your team or under you — Workday offers no peers or managers here — with a feedback template (its `[BLANK]`s filled in via `fill`) and/or your own questions, and `sharing: "confidential"` to keep the answers from the person they are about — confirmation-token gated; the preview lists every question |
| `workday_fetch` | Raw `.htmld` read with secrets redacted — the escape hatch for pages the parser doesn't model yet |
| `workday_graphql` | Read-only GraphQL against Workday's PEX surface (mutations refused). The only route to Inbox / search |
| `workday_healthcheck` | Verify the bridge + session end-to-end with an actionable hint |

The parser understands seven Workday page families — data cards, **grids**
(real tables, with chunking and export links), form-style detail pages, worker
profiles, org charts, app hubs, and report prompt forms — and labels each page
with its `kind`. See [docs/WORKDAY-API.md](./docs/WORKDAY-API.md).

### Manager quick start

```
workday_get_org_chart                                   → who reports where, with profileUris
workday_get_worker         { worker: "<profileUri>" }   → that person's full catalog
workday_get_worker_task    { worker: "…", task: "Compensation" }
workday_open_app           { app: "talent" }            → a whole app hub, crawled
```

### Review and promotion season

```
workday_get_team                                        → your reports, with workerIds
workday_get_reviews        { worker: "247$42" }         → their review history
workday_get_reviews        { worker: "247$42", review: "latest" }   → ratings + comments
workday_get_feedback       { worker: "Justin K" }       → feedback received
workday_get_feedback_status                             → all your open requests: who answered, who hasn't
workday_get_request_form   { requestType: "promotion consideration" } → the form's questions
workday_get_inbox                                       → review steps and requests waiting on you
workday_get_my_requests                                 → status of what you submitted
workday_get_team_snapshot                               → grade, last promotion, rating for everyone
workday_get_request        { request: "20447$18949" }  → a draft's questions + saved answers
workday_update_request     { request, answers: { "8": "…" }, action: "save" }  → preview + confirmToken
workday_update_request     { …same…, confirmToken }     → writes, then re-reads to verify
workday_get_dashboard      { dashboard: "year end" }    → worklets + report links, with reportIds
workday_request_feedback   { about: "Pat Doe", from: ["Sam Roe"], template: "feedback on me" }  → preview + confirmToken
workday_give_feedback      { to: "Pat Doe", feedback: "…", badge: "own it" }              → preview + confirmToken
workday_run_report         { report: "1422$242", prompts: { "Supervisory Organization": "My Org" } }
```

### Benefits enrollment season

```
workday_get_benefits                                    → what you have now, and what it costs
workday_get_benefit_enrollment                          → deadline, next year's cost changes, every plan on offer
workday_get_benefit_enrollment { planType: "medical", rates: true }  → each plan's price at every coverage level
workday_get_benefits       { show: "dependents" }       → who you can cover
```

Making elections — confirmation-gated, like the request write:

```
workday_update_benefit_enrollment { changes: [{ planType: "dependent care", waive: true },
                                              { planType: "health savings", annualContribution: 7800 }],
                                    action: "save" }      → preview + confirmToken
workday_update_benefit_enrollment { …same…, confirmToken } → writes, then re-reads to verify
workday_update_benefit_enrollment { changes: [], action: "submit" }   → Review and Sign, I Accept, Submit
```

### Writes

Two tools change anything: `workday_update_request` and
`workday_update_benefit_enrollment` (choose or waive plans, set an HSA/FSA
amount, then Save for Later or sign and Submit). Both are gated
by the fleet confirm flow (`@chrischall/mcp-utils` `confirmWrite`): the first
call returns a preview of every changed answer and a single-use `confirmToken`
and sends nothing; only a repeat call with that token writes. The token is
bound to the request (or enrollment event), the action, the answers (or
changes), the preview and a hash of what is saved from a fresh read, so it is
refused if any of them changes. A benefits `submit` signs Workday's electronic
signature on your behalf — the preview says so. Configure with `MCP_CONFIRM_MODE` / `MCP_CONFIRM_TTL_SECONDS` /
`MCP_CONFIRM_SECRET`.

All ids are discovered at runtime from your own app menu and org chart — nothing
tenant-specific is hardcoded, so this works on any Workday tenant.

## Development

```bash
npm install
npm test          # vitest
npm run build     # tsc --noEmit + esbuild bundle → dist/bundle.js
```

The widget-tree parser (`src/parse.ts`) is the durable core; see
[docs/WORKDAY-API.md](./docs/WORKDAY-API.md) for the captured endpoint shapes and
schema. License: MIT.