# workday-mcp-reference

A vendor-neutral, clean-room reference implementation of a **Workday MCP server**.
It reproduces the architecture of a production Workday Model Context Protocol
server — OAuth broker, opaque session tokens with silent refresh, a REST + SOAP
Workday client, regex SOAP parsing, text/HTML formatters, and per-tool gating —
**without any company-specific data**. Use it as a starting point for your own
Workday MCP integration.

## Stack

- Python 3.11+, modern typing, absolute imports.
- MCP: official [`mcp`](https://pypi.org/project/mcp/) SDK `FastMCP`, streamable-HTTP transport.
- HTTP: `requests` (shared `Session` + retry on idempotent verbs only).
- Logging: stdlib `logging`. Metrics: a no-op `Metrics` protocol (inject your own).
- Tracing: optional OpenTelemetry, gated on `OTEL_EXPORTER_OTLP_ENDPOINT`.
- Config: `os.environ` + `python-dotenv`.

## Quick start

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"          # add ,otel,redis as needed
cp .env.example .env             # fill in your tenant + OAuth client
workday-mcp-reference            # serves streamable-HTTP on :8000/mcp
```

## How auth works

1. An MCP client calls `/mcp` with no valid bearer → the server returns `401` +
   `WWW-Authenticate` pointing at `/.well-known/oauth-protected-resource`.
2. The client discovers the authorization server (RFC 8414), optionally registers
   (RFC 7591), then opens `/authorize` → the server 302s the user to Workday.
3. Workday redirects to `/callback?code=…`; the server exchanges the code, resolves
   the user email, stores the Workday tokens under an opaque UUID, and returns that
   UUID. The client uses the UUID as its bearer thereafter.
4. Each tool call resolves the live Workday token from the store, refreshing
   silently when it is within 5 minutes of expiry.

## Layout

```
src/workday_mcp_reference/
  config.py                 environment-driven configuration
  metrics.py                Metrics protocol + NoopMetrics
  server.py                 FastMCP + Bearer gate + OAuth/health routes + main()
  auth/
    token_store.py          opaque-id → Workday tokens, silent refresh
    oauth.py                authorize/callback broker + discovery metadata
  workday/
    client.py               WorkdayClient (REST + SOAP), uniform envelope
    parsers.py              regex SOAP parsing (no lxml)
    formatters.py           text + optional HTML artifacts
  tools/
    __init__.py             register_all + get_client/resolve_me_wid helpers
    me.py                   exemplar tool module (workday_me)
    pay.py                  compensation + one-time payment (REST + SOAP)
    benefits.py             enrollments, elections, total rewards
    time.py                 time off: scheduled, balance, eligible types, request
    org.py                  manager, reports, org chart, search, lookup
    inbox.py                inbox tasks: list, approve, deny
    admin.py                job profiles, pay groups, hire steps, BP status
    headcount.py            open positions, approvals, position detail (RaaS/WQL)
```

The eight category tools each take an `action` argument and dispatch to one
implementation — mirroring how a production server keeps the MCP tool surface
small. `headcount.py` depends on tenant-specific RaaS reports and WQL fields, so
its report names and field mappings are driven entirely by env config (see
`.env.example`); the other modules use standard Workday REST/SOAP APIs.

## Adding a tool module

Copy `tools/me.py`. Expose `def register(mcp: FastMCP) -> None`, define your
`@mcp.tool()` functions inside it, and call `get_client()` / `resolve_me_wid(client)`
— never read tokens directly. Add your module name to `_TOOL_MODULES` in
`tools/__init__.py`.