nathan/nexus-mcp
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
nexus-mcp/Workday/Planning/workday-mcp-implementation-plan.md
Nathan Castaldi 2343cf439d
Updated folder structure (#1) 
Co-authored-by: nathan <nathan@castaldifamily.com>
2026-04-03 09:41:31 -04:00

5.7 KiB
Raw Blame History

title, description, type, version, author, date
title description type version author date
Workday MCP — implementation and auth plan Execution plan to build a read-only Workday MCP server using the proven Identity MCP pattern. Implementation Plan v1 N. Castaldi 2026-03-11

Objective

Build a read-only Workday MCP server by reusing the implementation pattern that succeeded in the Identity MCP server, while replacing the AD/PowerShell adapter with a Workday REST/OAuth adapter.

Scope for first release

Included:

  • Read-only tools only:
    • workday.getWorker(identifier)
    • workday.getWorkerStatus(identifier)
    • workday.getWorkerOrgAttributes(identifier)
    • workday.getWorkerManager(identifier)
    • workday.getWorkerEffectiveDates(identifier)
  • Workday MCP project scaffolding equivalent to the Identity MCP structure
  • In-memory backend for local contract testing
  • API backend for Workday REST integration
  • Unit tests and integration smoke tests
  • Logging and audit controls

Excluded:

  • Any write actions to Workday
  • Any HR transaction support
  • Ticketing automation from Workday MCP
  • Correlation/remediation execution logic beyond read-only outputs

Current decisions captured

  • API family for v1: REST only
  • Security model: least privilege, read-only field scope
  • Deployment model: phased rollout aligned to existing Workday install guide
  • Architecture pattern: dual backend (memory default, api production)

Build plan (execution sequence)

  1. Clone the Identity MCP skeleton into Workday equivalents.
  2. Create Workday backend contract with five async tool methods.
  3. Implement in-memory backend with safe sample worker payloads.
  4. Implement FastMCP server entrypoint and tool wrappers.
  5. Implement Workday REST adapter with OAuth token handling.
  6. Add config and secret-loading contract.
  7. Add adapter unit tests with mocked HTTP/token responses.
  8. Add non-prod integration smoke tests for end-to-end validation.
  9. Validate output schema allowlist and excluded fields.
  10. Publish runbook updates and final verification checklist.

Files to create for parity with Identity MCP

  • workday_mcp_server.py
  • workday_backend.py
  • workday_adapter.py
  • debug_workday_connectivity.py
  • pyproject.toml
  • .gitignore
  • tests/test_workday_adapter.py
  • tests/test_integration.py

Authentication implementation requirements

  1. Use Workday REST API with OAuth 2.0 for API calls.
  2. Use a dedicated Integration System User (ISU) for MCP access.
  3. Register and manage a dedicated Workday API client for this service.
  4. Restrict security group and domain permissions to approved read-only fields.
  5. Keep separate credentials and client configuration for non-production and production.
  6. Store client secret/token material in approved secret storage, never in code.
  7. Enforce token refresh, timeout, retry, and rate-limit handling in adapter logic.

Data to gather (required before build proceeds)

A. Workday auth and tenant details

  • Tenant name(s) for non-production and production
  • Base API host URL(s)
  • Approved OAuth grant type for this integration
  • Token endpoint details and expected token lifetime
  • Refresh token policy and rotation requirements

B. Identity and access control details

  • ISU account name and owner
  • Integration security group name
  • Exact domain permissions approved for read-only use
  • Explicit list of denied domains/fields

C. Endpoint and schema contract

  • Exact Workday REST endpoints for each of the 5 tools
  • Required request parameters and lookup identifiers
  • Expected success payload shape per endpoint
  • Error payload examples for 401/403/404/429/5xx

D. Operations and observability

  • Required logging sink and retention policy
  • Required audit fields per MCP invocation
  • Retry/backoff thresholds and timeout limits
  • Rate-limit constraints provided by tenant admins

Current blockers

  1. OAuth grant type is not finalized.
  2. Ownership for credential and security-group provisioning is not assigned.
  3. Non-production Workday tenant/sandbox access is not yet available.
  4. Exact endpoint-to-tool mapping is not finalized.
  5. Approved field allowlist and denylist are not yet locked to testable schema contracts.

Dedicated next steps

  1. Assign owner for Workday auth provisioning (HRIS or IAM/Security) and confirm accountable approver.
  2. Finalize OAuth grant type and token lifecycle policy in a short design decision record.
  3. Provision non-production tenant access and generate non-prod API client credentials.
  4. Confirm ISU + security group + domain permissions for read-only scope.
  5. Produce endpoint mapping table (tool -> endpoint -> fields -> error contract).
  6. Create initial Workday project scaffold and run server in memory mode.
  7. Implement adapter token flow and one tool end-to-end in non-prod.
  8. Expand to all five tools and complete unit plus integration test gates.
  9. Validate logs and outputs for secret safety and field-scope compliance.
  10. Update install guide with exact run/test commands once implementation is proven.

Verification checklist

  • All blocker items are resolved and documented.
  • Server starts in memory mode and API mode.
  • All five tools return only approved fields.
  • Unit tests pass with mocked auth and API error scenarios.
  • Integration tests pass against non-production tenant.
  • No secrets appear in logs.
  • Audit logs capture tool name, parameters, timestamp, and result status.

Related documents