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 に新しい @mcp.tool() 関数を追加し、適切なパスで client.get(...) を呼び出してください。workday_client.py にある認証、エラー処理、ページネーションの仕組みは、すでにすべてのツールで共有されています。一部の Workday API ファミリーはバージョン管理方法が異なる（例: /ccx/api/staffing/v6/... や /ccx/api/absenceManagement/v2/...）ことに注意してください。これらの API に対してツールを追加する場合は、tools.py にパスをハードコードせず、追加のベース URL ヘルパーで WorkdayClient を拡張してください。

Related MCP server: Joule HR MCP Server

ファイル

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

認証

サーバーは Workday への認証に、OAuth2 のクライアント資格情報グラントを次のエンドポイントに対して使用します:

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

これには、API アクセスが有効で、クエリしたいドメイン（Worker Data、Organization Data など）への読み取りアクセス権を持つ Workday 登録済み API クライアント（統合システムユーザー）が必要です。Workday の System → API Clients でこれらを設定し、作成された統合システムユーザーに該当するセキュリティグループのアクセス権を付与してください。これは Workday 管理者の作業であり、このコードが代わりに行うものではありません。

必要な環境変数

任意:

グラントタイプ: クライアント資格情報と認可コード

このクライアントはクライアント資格情報グラント（2-legged、マシン間、ユーザーログインなし）のみを実装しています。トークンエンドポイントに grant_type=client_credentials とクライアント ID/シークレットを POST し、認可エンドポイントには一切アクセスしません。

もし Workday API クライアントが認可コードグラント専用として登録されている場合（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 ページにクライアントのトークンエンドポイントとして表示されているものと完全に一致することを確認してください。

4 つの必須変数のいずれかが欠けている場合、サーバーは最初のツール呼び出しで紛らわしいエラーを出すのではなく、起動時に明確なエラーをログに記録して終了します。

統合で書き込みアクセスも必要な場合は、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. イメージをビルドしてプッシュする（Cloud Build を使用するため、ローカルに Docker をインストールする必要はありません）:

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）またはその前段のリバースプロキシによって行われることを想定しています。run.invoker は、呼び出しを許可すべき ID/サービスにのみ付与してください。例:

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 で待ち受けるため、追加の設定は不要です。コンテナは完全にステートレス（ローカルファイルを書き込まない）であるため、ゼロへのスケールダウンとその後のスケールアップが問題なく行え、共有状態を気にせずに複数のインスタンス/レプリカを同時に実行できます。

エラー処理とページネーションの動作

• Workday からの 4xx/5xx レスポンスは、短く読みやすいエラーメッセージに変換され、MCP ツールエラー（isError: true）として返されます。生のスタックトレースが返されることはありません。

• ネットワーク障害（DNS、タイムアウト、接続拒否）も同様にキャッチされ、同じ方法で返されます。

• リストエンドポイントは 1 ページ分を返します（limit はデフォルト 20、最大 100。offset はデフォルト 0）。さらに結果がある場合、レスポンスは全件数と次に渡すべき offset を通知します。すべてのページを自動的に取得することはありません。