Workday MCP Server

Ein schreibgeschützter MCP-Server, der Workday-HCM-Daten – Mitarbeiter, Organisationen, aufsichtsführende Organisationen, Standorte, Jobprofile und Kostenstellen – als Tools bereitstellt, die ein LLM aufrufen kann, unterstützt durch die Workday REST API v1.0 (die "Common"/Foundation-Ressourcen, die in jedem Workday-Mandanten vorhanden sind).

Erstellt mit dem offiziellen mcp Python SDK, das den Streamable-HTTP-Transport verwendet, sodass er als normaler zustandsloser HTTP-Dienst auf Google Cloud Run ausgeführt werden kann.

Umfang

Workdays reale API-Oberfläche ist in viele unabhängig versionierte REST-API-Familien aufgeteilt (Common, Staffing, Absence Management, Compensation, Recruiting, Payroll, Talent, ...). Dieses Projekt implementiert die Common v1-Ressourcen, die am breitesten nutzbar, schreibgeschützt und in jedem Mandanten vorhanden sind:

Alle Tools sind schreibgeschützt (nur GET-Anfragen).

Um eine weitere Workday-API-Familie hinzuzufügen (z. B. Absence Management), füge eine neue @mcp.tool()-Funktion in tools.py hinzu, die client.get(...) mit dem entsprechenden Pfad aufruft – die Authentifizierungs-, Fehlerbehandlungs- und Paginierungslogik in workday_client.py ist bereits für alle Tools gemeinsam. Beachte, dass einige Workday-API-Familien unterschiedlich versioniert sind (z. B. /ccx/api/staffing/v6/... oder /ccx/api/absenceManagement/v2/...); wenn du Tools für diese hinzufügst, erweitere WorkdayClient um einen zusätzlichen Basis-URL-Helper, anstatt Pfade in tools.py hart zu codieren.

Related MCP server: Joule HR MCP Server

Dateien

server.py           MCP server entrypoint (FastMCP + Streamable HTTP transport)
tools.py            Tool definitions: params, docstrings, JSON -> summary text
workday_client.py   Workday REST client: OAuth2 auth, requests, error handling
requirements.txt    Pinned dependencies
Dockerfile          Slim, non-root container image for Cloud Run

Authentifizierung

Der Server authentifiziert sich bei Workday über einen OAuth2-Client-Credentials-Grant gegen:

{WORKDAY_HOST}/ccx/oauth2/{WORKDAY_TENANT}/token

Dies erfordert einen Registered API Client (Integration System User) mit aktiviertem API-Zugriff und Lesezugriff auf die Domänen, die du abfragen möchtest (Worker Data, Organization Data usw.). Richte diese in Workday unter System → API Clients ein und gewähre dem resultierenden Integration System User den entsprechenden Sicherheitsgruppenzugriff – das ist eine Workday-Admin-Aufgabe, die dieser Code nicht für dich erledigen kann.

Erforderliche Umgebungsvariablen

Optional:

Grant-Typ: Client Credentials vs. Authorization Code

Dieser Client implementiert nur den Client-Credentials-Grant (2-legged, Maschine-zu-Maschine, ohne Benutzeranmeldung) – er sendet eine POST-Anfrage an den Token-Endpunkt mit grant_type=client_credentials und deiner Client-ID/Geheimnis und berührt den Autorisierungsendpunkt überhaupt nicht.

Wenn dein Workday-API-Client nur für den Authorization-Code-Grant registriert ist (prüfe System → API Clients in Workday – suche nach dem Feld „Authentication Grant Type" und ob eine Redirect-URI gesetzt ist), wird eine client_credentials-Token-Anfrage mit 401 abgelehnt, egal wie korrekt Client-ID/Geheimnis sind. Dieser Ablauf erfordert eine einmalige interaktive Anmeldung über den Autorisierungsendpunkt, um ein Refresh-Token zu erhalten, was eine andere (größere) Integration darstellt – lass uns wissen, falls du das benötigst.

Wenn du eine 401 erhältst und dir nicht sicher bist, welcher Grant-Typ aktiviert ist, überprüfe die Server-Logs beim Start auf eine Zeile wie:

Workday client configured: token_url=... api_base=... client_id=...

und bestätige, dass diese URL genau dem Token-Endpunkt entspricht, den die Workday-API-Client-Seite für deinen Client anzeigt.

Wenn eine der vier erforderlichen Variablen fehlt, protokolliert der Server beim Start eine klare Fehlermeldung und beendet sich, anstatt beim ersten Tool-Aufruf verwirrend zu scheitern.

Wenn deine Integration auch Schreibzugriff benötigt, sind zusätzliche Scopes/Grants auf dem API-Client erforderlich – dieser Server sendet nur GET-Anfragen, daher sind für das hier Implementierte keine Schreib-Scopes erforderlich.

Lokale Ausführung

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export WORKDAY_TENANT=acme_gms
export WORKDAY_HOST=https://wd2-impl-services1.workday.com
export WORKDAY_CLIENT_ID=your-client-id
export WORKDAY_CLIENT_SECRET=your-client-secret

python server.py

Der Server lauscht auf http://0.0.0.0:8080/mcp/ (Streamable HTTP). Richte einen beliebigen MCP-kompatiblen Client (Claude, einen MCP Inspector usw.) auf diese URL.

Schnellprüfung mit dem MCP Inspector:

npx @modelcontextprotocol/inspector http://localhost:8080/mcp/

Bereitstellung auf Google Cloud Run

1. Build und Push des Images (mit Cloud Build, damit du Docker nicht lokal installiert haben musst):

   gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/workday-mcp

   Oder lokal bauen und pushen:

   docker build -t gcr.io/YOUR_PROJECT_ID/workday-mcp .
   docker push gcr.io/YOUR_PROJECT_ID/workday-mcp

2. Speichere das Client-Geheimnis in Secret Manager (übergib es in Produktion nicht als Klartext-Umgebungsvariable):

   echo -n "your-client-secret" | gcloud secrets create workday-client-secret --data-file=-

3. Bereitstellen:

   gcloud run deploy workday-mcp \
     --image gcr.io/YOUR_PROJECT_ID/workday-mcp \
     --region YOUR_REGION \
     --set-env-vars WORKDAY_TENANT=acme_gms,WORKDAY_HOST=https://wd2-impl-services1.workday.com,WORKDAY_CLIENT_ID=your-client-id \
     --set-secrets WORKDAY_CLIENT_SECRET=workday-client-secret:latest \
     --no-allow-unauthenticated

   --no-allow-unauthenticated ist beabsichtigt: Dieser Server implementiert keine eigene Authentifizierungsschicht (wie vorgesehen), daher wird erwartet, dass die Zugriffskontrolle über Cloud Run IAM (roles/run.invoker) oder einen vorgelagerten Reverse-Proxy erfolgt. Gewähre run.invoker nur den Identitäten/Diensten, die ihn aufrufen können sollten, z. B.:

   gcloud run services add-iam-policy-binding workday-mcp \
     --region YOUR_REGION \
     --member="serviceAccount:your-caller@your-project.iam.gserviceaccount.com" \
     --role="roles/run.invoker"

4. Cloud Run setzt PORT automatisch und die App lauscht bereits auf 0.0.0.0:$PORT, daher ist keine weitere Konfiguration erforderlich. Der Container ist vollständig zustandslos (es werden keine lokalen Dateien geschrieben), sodass er sauber auf null und wieder hochskaliert, und mehrere Instanzen/Replikate können ohne gemeinsamen Zustand gleichzeitig ausgeführt werden.

Fehlerbehandlung & Paginierungsverhalten

• 4xx/5xx-Antworten von Workday werden in eine kurze, lesbare Fehlermeldung übersetzt und als MCP-Tool-Fehler (isError: true) zurückgegeben – niemals als roher Stack-Trace.

• Netzwerkfehler (DNS, Timeout, Verbindungsabgelehnt) werden ebenfalls abgefangen und auf die gleiche Weise zurückgegeben.

• Listen-Endpunkte geben eine einzelne Seite zurück (limit, Standard 20, Maximum 100; offset, Standard 0). Wenn weitere Ergebnisse vorhanden sind, teilt die Antwort dir die Gesamtzahl und den nächsten offset mit, anstatt automatisch jede Seite abzurufen.