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 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.

Related MCP server: DB MCP (HR CSV to SQLite)

Quick start

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.