Workday MCP Server

Workday HCM 데이터(작업자, 조직, 상위 조직, 위치, 직무 프로필, 원가 센터)를 LLM이 호출할 수 있는 도구로 노출하는 읽기 전용 MCP 서버로, Workday REST API v1.0(모든 Workday 테넌트에 존재하는 "Common"/Foundation 리소스 세트)을 기반으로 합니다.

공식 mcp Python SDK로 구축되었으며, Streamable HTTP 전송 방식을 사용하여 Google Cloud Run에서 일반적인 무상태 HTTP 서비스로 실행할 수 있습니다.

범위

Workday의 실제 API 표면은 독립적으로 버전이 관리되는 여러 REST API 패밀리(Common, Staffing, Absence Management, Compensation, Recruiting, Payroll, Talent 등)로 나뉘어 있습니다. 이 프로젝트는 가장 광범위하게 유용하고 읽기 전용이며 모든 테넌트에 존재하는 Common v1 리소스를 구현합니다:

모든 도구는 읽기 전용입니다(GET 요청만).

다른 Workday API 패밀리(예: Absence Management)를 추가하려면 tools.py에 적절한 경로로 client.get(...)을 호출하는 새 @mcp.tool() 함수를 추가하세요. workday_client.py의 인증, 오류 처리, 페이지네이션 파이프라인은 이미 모든 도구에서 공유됩니다. 일부 Workday API 패밀리는 다르게 버전이 관리됩니다(예: /ccx/api/staffing/v6/... 또는 /ccx/api/absenceManagement/v2/...). 이러한 API에 대해 도구를 추가하는 경우 tools.py에 경로를 하드코딩하지 말고 WorkdayClient에 추가 base-URL 헬퍼를 확장하세요.

Related MCP server: HRIS MCP Connector

파일

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

인증

서버는 OAuth2 클라이언트 자격 증명(client credentials) 그랜트를 사용하여 Workday에 인증합니다:

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

이를 위해서는 API 액세스가 활성화되고 쿼리하려는 도메인(Worker Data, Organization Data 등)에 대한 읽기 액세스 권한이 있는 Workday 등록 API 클라이언트(통합 시스템 사용자)가 필요합니다. Workday의 System → API Clients에서 설정하고, 생성된 Integration System User에게 관련 보안 그룹 액세스 권한을 부여하세요. 이는 Workday 관리자 작업이며, 이 코드가 대신 수행할 수 있는 작업이 아닙니다.

필수 환경 변수

선택 사항:

그랜트 유형: 클라이언트 자격 증명 vs. 인증 코드

이 클라이언트는 클라이언트 자격 증명 그랜트(2-legged, 머신 간, 사용자 로그인 없음)만 구현합니다. grant_type=client_credentials와 클라이언트 ID/시크릿으로 토큰 엔드포인트에 POST하며 인증 엔드포인트는 전혀 사용하지 않습니다.

Workday API 클라이언트가 인증 코드 그랜트(Authorization Code Grant) 전용으로 등록된 경우(Workday의 System → API Clients에서 "Authentication Grant Type" 필드와 Redirect URI 설정 여부를 확인하세요), 클라이언트 ID/시크릿이 아무리 정확해도 client_credentials 토큰 요청은 401로 거부됩니다. 이 흐름은 리프레시 토큰을 얻기 위해 인증 엔드포인트를 통한 일회성 대화형 로그인이 필요하며, 이는 구축해야 할 다른(더 큰) 통합입니다. 필요한 경우 알려주세요.

401 오류가 발생하고 어떤 그랜트 유형이 활성화되어 있는지 확실하지 않은 경우, 서버 시작 시 로그에서 다음과 같은 줄을 확인하세요:

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

그리고 해당 URL이 Workday의 API Client 페이지에 클라이언트의 토큰 엔드포인트로 표시된 것과 정확히 일치하는지 확인하세요.

네 가지 필수 변수 중 하나라도 누락된 경우, 서버는 첫 번째 도구 호출에서 혼란스럽게 실패하는 대신 시작 시 명확한 오류를 기록하고 종료합니다.

통합에 쓰기 액세스도 필요한 경우 API 클라이언트에 추가 스코프/그랜트가 필요합니다. 이 서버는 GET 요청만 발행하므로 여기에 구현된 기능에는 쓰기 스코프가 필요하지 않습니다.

로컬 실행

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

서버는 http://0.0.0.0:8080/mcp/(Streamable HTTP)에서 수신 대기합니다. MCP 호환 클라이언트(Claude, MCP Inspector 등)를 해당 URL에 연결하세요.

MCP Inspector로 빠른 확인:

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

Google Cloud Run에 배포

1. 이미지 빌드 및 푸시(로컬에 Docker를 설치할 필요 없이 Cloud Build 사용):

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

   또는 로컬에서 빌드하고 푸시:

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

2. Secret Manager에 클라이언트 시크릿 저장(프로덕션에서 일반 환경 변수로 전달하지 마세요):

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

3. 배포:

   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는 의도적입니다. 이 서버는 설계상 자체 인증 계층을 구현하지 않으므로, 액세스 제어는 Cloud Run IAM(roles/run.invoker) 또는 앞단의 리버스 프록시에서 제공될 것으로 예상됩니다. 호출할 수 있어야 하는 ID/서비스에만 run.invoker를 부여하세요. 예:

   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이 PORT를 자동으로 설정하고 앱이 이미 0.0.0.0:$PORT에서 수신 대기하므로 추가 구성이 필요 없습니다. 컨테이너는 완전히 무상태(로컬 파일 기록 없음)이므로 0으로 스케일 다운 후 다시 정상적으로 스케일 업할 수 있으며, 공유 상태에 대한 걱정 없이 여러 인스턴스/복제본을 동시에 실행할 수 있습니다.

오류 처리 및 페이지네이션 동작

• Workday의 4xx/5xx 응답은 짧고 읽기 쉬운 오류 메시지로 변환되어 MCP 도구 오류(isError: true)로 반환됩니다. 원시 스택 트레이스는 절대 반환되지 않습니다.

• 네트워크 오류(DNS, 타임아웃, 연결 거부)도 동일한 방식으로 포착되어 반환됩니다.

• 목록 엔드포인트는 단일 페이지를 반환합니다(limit, 기본값 20, 최대 100; offset, 기본값 0). 더 많은 결과가 있는 경우, 모든 페이지를 자동으로 가져오는 대신 응답에 총 개수와 다음에 전달할 offset이 표시됩니다.