Workday MCP Server

Un servidor de solo lectura MCP que expone datos de Workday HCM — trabajadores, organizaciones, organizaciones supervisoras, ubicaciones, perfiles de puesto y centros de coste — como herramientas que un LLM puede llamar, respaldado por la Workday REST API v1.0 (el conjunto de recursos «Common»/Foundation presente en todos los inquilinos de Workday).

Construido con el SDK de Python mcp oficial, que utiliza su transporte HTTP Streamable para poder ejecutarse como un servicio HTTP sin estado normal en Google Cloud Run.

Alcance

La superficie real de la API de Workday está dividida en varias familias de API REST versionadas de forma independiente (Common, Staffing, Absence Management, Compensation, Recruiting, Payroll, Talent, ...). Este proyecto implementa los recursos de Common v1, que son los más útiles en general, de solo lectura y presentes en todos los inquilinos:

Todas las herramientas son de solo lectura (solo peticiones GET).

Para añadir otra familia de la API de Workday (p. ej., Absence Management), añade una nueva función @mcp.tool() en tools.py que llame a client.get(...) con la ruta adecuada; la autenticación, el manejo de errores y el mecanismo de paginación en workday_client.py ya están compartidos por todas las herramientas. Ten en cuenta que algunas familias de la API de Workday tienen versiones diferentes (p. ej., /ccx/api/staffing/v6/... o /ccx/api/absenceManagement/v2/...); si añades herramientas para esas, extiende WorkdayClient con un helper adicional de URL base en lugar de codificar rutas en tools.py.

Related MCP server: Joule HR MCP Server

Archivos

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

Autenticación

El servidor se autentica en Workday usando el flujo de credenciales de cliente OAuth2 contra:

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

Esto requiere un Registered API Client de Workday (usuario de sistema de integración) con acceso a la API habilitado y acceso de lectura a los dominios que quieras consultar (Worker Data, Organization Data, etc.). Configúralo en Workday en System → API Clients, y concede al Integration System User resultante el acceso al grupo de seguridad correspondiente; esa es una tarea de administración de Workday, no algo que este código pueda hacer por ti.

Variables de entorno requeridas

Opcionales:

Tipo de concesión: Client Credentials vs. Authorization Code

Este cliente solo implementa la concesión Client Credentials (de dos partes, máquina a máquina, sin inicio de sesión de usuario) — hace POST al endpoint de token con grant_type=client_credentials y tu ID/secreto de cliente, y nunca toca el endpoint de autorización.

Si tu API Client de Workday está registrado solo para la concesión Authorization Code (consulta System → API Clients en Workday; busca el campo «Authentication Grant Type» y si hay una Redirect URI configurada), una solicitud de token client_credentials será rechazada con 401, por muy correctos que sean el ID y el secreto de cliente. Ese flujo requiere un inicio de sesión interactivo único a través del endpoint de autorización para obtener un refresh token, que es una integración diferente (más grande) de construir; avísanos si eso es lo que necesitas.

Si recibes un 401 y no estás seguro de qué tipo de concesión está habilitado, revisa los registros del servidor al inicio para ver una línea como:

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

y confirma que esa URL coincide exactamente con lo que la página API Client de Workday muestra como endpoint de token para tu cliente.

Si falta cualquiera de las cuatro variables obligatorias, el servidor registra un error claro y se cierra al inicio en lugar de fallar de forma confusa en la primera llamada a una herramienta.

Si tu integración también necesita acceso de escritura, se requerirán scopes/concesiones adicionales en el API client — este servidor solo realiza peticiones GET, por lo que no se necesitan scopes de escritura para lo implementado aquí.

Ejecución local

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

El servidor escucha en http://0.0.0.0:8080/mcp/ (Streamable HTTP). Apunta cualquier cliente compatible con MCP (Claude, un MCP Inspector, etc.) a esa URL.

Comprobación rápida con el MCP Inspector:

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

Despliegue en Google Cloud Run

1. Compila y sube la imagen (usando Cloud Build, para que no necesites Docker instalado localmente):

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

   O compila localmente y sube:

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

2. Guarda el secreto del cliente en Secret Manager (no lo pases como una variable de entorno en texto plano en producción):

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

3. Despliega:

   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 es intencional: este servidor no implementa su propia capa de autenticación (por diseño), por lo que se espera que el control de acceso provenga de Cloud Run IAM (roles/run.invoker) o de un proxy inverso delante de él. Concede run.invoker solo a las identidades/servicios que deberían poder llamarlo, por ejemplo:

   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 establece PORT automáticamente y la aplicación ya escucha en 0.0.0.0:$PORT, por lo que no se necesita configuración adicional. El contenedor es totalmente sin estado (no escribe archivos locales), por lo que escala a cero y vuelve a subir sin problemas, y varias instancias/réplicas pueden ejecutarse a la vez sin tener que preocuparse por estado compartido.

Manejo de errores y comportamiento de paginación

• Las respuestas 4xx/5xx de Workday se convierten en un mensaje de error breve y legible y se devuelven como un error de herramienta MCP (isError: true) — nunca un stack trace en bruto.

• Los fallos de red (DNS, timeout, conexión rechazada) también se capturan y se devuelven de la misma manera.

• Los endpoints de listado devuelven una sola página (limit, por defecto 20, máximo 100; offset, por defecto 0). Si existen más resultados, la respuesta te indica el recuento total y qué offset pasar a continuación, en lugar de obtener todas las páginas automáticamente.