Zero to Your First Workday Extend App with Claude

Before you start

This guide takes you from nothing to your own Workday Extend app, built and deployed with Claude's help. Plan on an afternoon: about 2–3 hours of work, plus up to an hour waiting for Workday's email. It was written after doing every step for real (October 2026); the Watch out notes are mistakes that cost us time.

What you'll end up with

• A personal developer account on Workday's Developer Site (developer.workday.com).
• A personal development tenant: your own private, free copy of Workday, full of fake demo employees, safe to experiment in.
• Claude Code on your computer, able to build, check, upload and deploy Extend apps for you, and to ask Workday's own Developer Agent for help.
• Your first Extend app (a custom app that runs inside Workday), open in your tenant.
• Optionally, Claude reading your tenant's demo data (people, teams, time off) directly.

What you need

• A Mac you can install software on. Windows and Linux work too, but the commands here are for a Mac.
• A web browser (Chrome works well).
• A personal email address (for example Gmail or iCloud) for the Workday account. Don't use your work email.
• A Claude subscription that includes Claude Code.
• Optional: a GitHub account, to keep your app's history online.

The steps at a glance

1. Get a personal developer account (15 min).
2. Request your tenant and sign in to it (15 min, plus waiting for the email).
3. Install Claude Code, wdcli, VS Code and the Developer Agent (30–45 min). You can do this while you wait for step 2's email.
4. Sign wdcli in (10 min).
5. Connect Claude Code to Workday (10 min).
6. Build your first app with Claude (30–60 min).
7. Check, upload and deploy it (10 min).
8. Switch on security in the tenant and open your app (10 min).

After that: how Claude can also read your tenant's data, how to give Claude a memory of your project (CLAUDE.md), how to make changes later, and a troubleshooting table.

Words you'll see

• Tenant: one Workday system. Yours has a short name called the tenant alias, for example abcdefgh_extdev. This guide writes <your-alias> wherever you put yours.
• Demo user: the fake employee you sign in to your tenant as. On personal tenants it's usually lmcneil (Logan McNeil, a Chief HR Officer with a team).
• Extend app: an app you build that lives inside Workday, with its own pages and, if you want, its own data.
• wdcli: Workday's command-line tool. It creates, checks, uploads and deploys your app, and it's also how Claude Code talks to Workday.
• Developer Agent: Workday's own AI coding assistant for Extend, which runs inside VS Code. Claude can send it questions.
• MCP server: a plug-in that gives Claude Code extra tools. You'll add one for Workday.
• Terminal: the app where you type commands (on a Mac: Applications → Utilities → Terminal). In the Claude desktop app you can also just ask Claude to run a command for you.

How to use this guide: do the steps in order, and don't skip the Check at the end of each one. Workday changes its screens from time to time; if a button's name doesn't match exactly, look for the closest one. When you're stuck, paste the error into Claude and ask what to do.

Step 1: Get a personal developer account (15 minutes)

Your developer account is your login to Workday's Developer Site, where you request a tenant and download Workday's tools.

1. Go to https://developer.workday.com in your browser.
2. Choose to sign up for a personal developer account (Workday also calls this the Open Developer Platform). Don't pick an enterprise option: that's for companies that already run Workday.
3. Fill in your name and your personal email address, not your work email. Accept the terms.
4. Open the confirmation email Workday sends you and confirm your address. Check your spam folder if it doesn't arrive.
5. Sign in to developer.workday.com with your new account.

Why a personal email: this account belongs to you, not your employer, and it stays yours if you change jobs.

Write down the email you used. You'll sign in with it again in Step 4.

Check: you can sign in to developer.workday.com and open the menu at the top left, which has a Console section.

Step 2: Get your personal tenant (15 minutes, plus waiting for an email)

Your tenant is your own practice Workday. You request it on the Developer Site, and Workday emails you when it's ready.

1. On developer.workday.com, open the menu at the top left → Console → Tenants.
2. Click + under Development Tenants to request a new tenant.
3. Wait for the email saying your tenant is ready. It usually takes about 15 minutes. Check your spam folder. While you wait, you can start Step 3.
4. Click the sign-in link in the email and sign in as the demo user it names, usually lmcneil (Logan McNeil).
5. Set a new password straight away, and save it in your password manager.
6. Click around as a normal user: your profile, your team, the org chart. This fake data is what your app will show later.
7. Back on developer.workday.com, open Console → Tenants and write down your tenant alias (it looks like abcdefgh_extdev). You'll need it in Steps 4, 7 and 8.
8. In the browser, note the start of your tenant's web address while you're signed in, for example https://something.wd119.myworkday.com/<your-alias>/.... That's your tenant host, used in Step 8.

House rules for personal tenants

• Change the password within 72 hours of the email, or the account goes stale.
• The tenant is deleted after 7 days with no sign-in. Sign in at least once a week to keep it.
• You can have one active tenant at a time, and at most two created within 6 hours. Deleting a tenant can't be undone.
• Everything in it is fake demo data. Don't put real personal data in it.

Check: you can sign in to your tenant in the browser as your demo user, and you have your tenant alias and tenant host written down.

Step 3: Install the tools (30–45 minutes)

You need five things on your computer: Claude Code, Python, Workday's wdcli, VS Code, and Workday's Developer Agent extension for VS Code. You can do this step while you wait for the tenant email.

1. Claude Code. Install the Claude desktop app from https://claude.ai/download, sign in, and open the Code tab. That's where you'll talk to Claude about your app. (Claude Code also runs in Terminal as claude, and inside VS Code.)

2. Python 3 and git (used for signing in to Workday's data, and for version history). Open Terminal and run:

   python3 --version
   git --version
   

   If either says it isn't installed, run xcode-select --install and follow the prompts, then try again.

3. wdcli (Workday's command-line tool).

   • Sign in to developer.workday.com, go to https://developer.workday.com/downloads, download WDCLI for macOS, and run the installer.

   • If macOS blocks it ("cannot be opened"), go to System Settings → Privacy & Security, scroll down, and click Open Anyway.

   • Close Terminal, open it again, and check:

     wdcli version
     

     You should see a version number (we used 1.9.43).

   • If you see command not found, wdcli's bin folder isn't on your PATH. Ask Claude to find where wdcli was installed and add it to ~/.zshrc for you, or add the line export PATH="/path/to/wdcli/bin:$PATH" yourself.

   • Tell wdcli you have a personal account, so you never forget the flag in Step 4:

     echo 'export WDCLI_ENVIRONMENT=personal' >> ~/.zshrc
     

4. VS Code. Download it from https://code.visualstudio.com, drag it into Applications, and open it. Then press Cmd-Shift-P, type Shell Command: Install 'code' command in PATH, and press Return. This lets you open folders in VS Code from Terminal with code ..

5. Workday Developer Agent extension. Go to https://developer.workday.com/developer-agent, choose VS Code, and follow the steps there. If you're given a .vsix file, press Cmd-Shift-P in VS Code, choose Extensions: Install from VSIX…, and pick the file. You'll sign in to it after Step 4, because it shares wdcli's login.

6. A folder for your work. Make a folder for your apps, for example workday-apps in your home folder. In the Claude desktop app, start a new Code session and choose that folder. Pick a local session (on your computer), not a cloud one: only a local session can use wdcli and VS Code.

Check: python3 --version, git --version and wdcli version all print a version, and VS Code shows a Workday Developer Agent icon in its side bar.

Step 4: Sign wdcli in (10 minutes)

wdcli needs two separate sign-ins: one to your developer account (to create and upload apps), and one to your tenant (to deploy them). You type these yourself, because they open a browser page where you enter your password.

1. Sign in to your developer account:

   wdcli auth login -e personal
   

   A browser page opens. Sign in with the personal email from Step 1.

   Watch out: a plain wdcli auth login (without -e personal) signs you in to Workday's enterprise environment. Everything after it then fails or shows nothing.

2. Check it worked:

   wdcli whoami
   wdcli tenant list
   

   whoami shows your name and account, and tenant list shows your tenant alias.

3. Sign in to your tenant, using your tenant alias:

   wdcli tenant login <your-alias>
   

   A browser page opens. Sign in as your demo user (for example lmcneil).

   Watch out: leave Terminal alone until it says Success: token saved. If you close the browser tab or press Enter too early, nothing is saved, and the next deploy says "Authentication required" even though you thought you'd signed in.

4. Sign in to the Developer Agent. In VS Code, open the Workday Developer Agent panel and sign in. It uses the same login as wdcli.

The tenant sign-in expires after a while. Whenever a deploy says "Authentication required", run step 3 again and wait for Success: token saved.

Check: wdcli tenant list shows your alias, Terminal said Success: token saved after the tenant login, and the Developer Agent panel in VS Code shows you as signed in.

Step 5: Connect Claude Code to Workday (10 minutes)

wdcli has a built-in connection for AI assistants, called an MCP server. Adding it to Claude Code lets Claude hand questions and tasks to Workday's Developer Agent.

1. Add the server. Run this in Terminal (or ask Claude in your Code session to run it):

   claude mcp add --scope user workday -- wdcli mcp
   

   Watch out: keep --scope user. Without it, the server only works in the folder where you ran the command, and Claude in any other folder won't see it.

2. Start a new Claude Code session in your apps folder, so it picks up the new server.

3. Open the same folder in VS Code (File → Open Folder, or code . in Terminal from that folder), and make sure the Developer Agent panel is signed in. Claude's Workday tool only works while VS Code is open on the folder Claude is working in.

4. Test it. Ask Claude: "Can you connect to the Workday MCP?" It should say it has a tool that sends tasks to the Workday Developer Agent. You can also run claude mcp list in Terminal and look for workday: wdcli mcp - ✔ Connected.

Where Claude Code can do this

How the pieces fit: Claude Code writes and checks your app's files and runs wdcli. When it needs Workday-specific knowledge, such as the exact syntax for a page formula or a field name in your tenant, it asks the Developer Agent, which has Workday's documentation. Anything the Developer Agent wants to change shows up in VS Code for you to approve.

Good to know: if Claude tries to read Workday's documentation directly, it gets "MCP features are only available to the Workday Developer Agent". That's expected: Workday keeps its docs for the Developer Agent, so Claude asks the agent instead.

What it isn't: this connection is only for building Extend apps (connection A). It doesn't let Claude read your tenant's data. For that, see The three ways Claude connects to Workday below (connections B and C).

Check: Claude confirms it can see the Workday Developer Agent tool.

Step 6: Build your first app with Claude (30–60 minutes)

Start small: one page that shows your team. You describe it in plain English, and Claude builds it.

1. Make sure VS Code is open on your apps folder and the Developer Agent is signed in (Step 5).

2. Ask Claude for the app. In your Code session, type something like this, with your own app name:

   "Create a new Workday Extend app called Team Explorer with wdcli app create. It should have one page that shows me, my manager and my direct reports, using the Workday common API. Add a security domain called TeamExplorerAccess and a task so it shows up in Workday search. Use the Workday Developer Agent to check any PMD syntax or field names you're unsure of, then validate it. Set the folder up as a git repository and commit as you go."

3. Claude creates the app. It runs a command like this:

   wdcli app create "Team Explorer" --app-type EXTEND --ci
   

   This registers the app with Workday and downloads a folder for it. The folder's name ends with a short code for your account, for example teamExplorer_abc123. That full name is your app ID, used in Steps 7 and 8.

4. Claude fills in the app's files. You don't need to edit them, but it helps to know what they are:

   File	What it does
   appManifest.json	The app's ID and name. wdcli writes this; leave it alone.
   presentation/*.pmd	One file per page: what's on it and where its data comes from.
   presentation/*.amd	The list of pages, and the Workday APIs the app uses.
   presentation/*.smd	Site settings, such as signing in through Workday.
   model/*.securitydomain	Who's allowed in. You switch this on in Step 8.
   model/*.task	Makes the app findable from Workday search.
   model/*.businessobject	Only if your app stores its own data, like a feedback form.

5. Approve the Developer Agent when asked. When Claude asks the Developer Agent something, VS Code may ask you to approve. Approve it there, and Claude carries on. If Claude seems stuck, look at the Developer Agent panel.

6. Ask questions as you go. For example: "Explain what this page shows and where the data comes from."

Tips for a first app

• Read Workday's data rather than storing your own. Apps with their own data (business objects) need more security setup, and "View and Modify" access in Step 8.
• Keep it to one page. Add pages once the first one works in your tenant.
• Let the Developer Agent check field names. Field names on Workday objects can differ between tenants. Guessed names are the most common cause of a page that shows nothing.

Things that tripped us up (worth telling Claude if it hits them):

• Selection widgets return lists of IDs, so the selected value is self.value[0], not self.value.
• A picker (instanceList) needs exactly one of instanceList or values. A search-only picker shows blank until you type; for short lists, load everyone into values.
• Inside a horizontal section, each child must itself be a container. Wrap each one in a section.
• Business object field labels allow only letters, digits, spaces, : and -. No brackets.

Check: Claude says the app was created and validation found no issues.

Step 7: Check, upload and deploy (10 minutes)

Three commands take your app from your computer into your tenant. Ask Claude "Validate, upload and deploy the app to my tenant" and it runs them, or run them yourself from the folder that contains your app's folder. Replace <app-id> with your app's folder name (for example teamExplorer_abc123) and <your-alias> with your tenant alias.

1. Validate checks the files for mistakes. It takes seconds, so run it before every upload:

   wdcli app validate -d <app-id>
   

   You want: No validation issues found. If it lists problems, paste them into Claude.

2. Upload sends the app to Workday and builds it:

   wdcli app upload <app-id> --ci
   

   You want: Successfully uploaded and Build completed, then a table with a Version ID and Build ID.

3. Deploy installs the latest build into your tenant:

   wdcli app deploy --app-id <app-id> --latest-version --tenant-alias <your-alias> --ci
   

   You want: a table with Success set to true.

If deploy says "Authentication required": your tenant sign-in has expired, or never finished saving. Run wdcli tenant login <your-alias> again (Step 4), wait for Success: token saved, then run the deploy again. If it still fails straight after a successful login, wait a few seconds and retry once.

Watch out: validation only checks that the files are well formed. It can't tell whether the page shows the right thing, or whether a formula works when the page runs. You still open the app and look, in Step 8.

Check: the deploy table shows Success: true.

Step 8: Switch on security and open your app (10 minutes)

A freshly deployed app is locked: nobody can use it until you tell Workday who's allowed in. You do this yourself in the tenant, once per new app. Claude doesn't change security settings in a live system.

1. Sign in to your tenant in the browser as your demo user.

2. In the Workday search bar, type Workday Extend App Manager and open it.

3. Find your app (for example Team Explorer) and choose Configure.

4. Under Model Components, find your app's security domain (named like Team Explorer: Access) and click Create to make its security policy:

   • Who: for a practice tenant, All Users is fine.
   • What they can do: View for an app that only shows data. If people save things in the app, also tick Modify, or saving fails.

5. Activate the change. Search for the task Activate Pending Security Policy Changes, run it, type a short comment such as "Team Explorer access", tick Confirm, and click OK.

   Watch out: this is the step people forget. Until you activate, nothing you set in step 4 above takes effect, and the app says you don't have access.

6. Open your app. Use any of these:

   • Its web address: https://<tenant-host>/<your-alias>/d/wday/app/<app-id>/<app-id>.htmld. The tenant host is the start of the address you noted in Step 2. Bookmark it.
   • Workday search: type the app's name, if Claude gave it a task (Step 6).
   • The Apps menu: run the task Configure Global Navigation Menu and add your app's task, so it appears in Workday's menu.

7. Check what it shows. Compare the page with what you see elsewhere in Workday, for example your team on your profile. If something's wrong, describe it to Claude (a screenshot helps) and ask it to fix it, then repeat Step 7.

Watch out: Extend cards for the Home page didn't show up in Home Page Configuration on a personal tenant (it probably needs a paid Extend subscription). Use the app's address or the Apps menu instead.

You only redo this step for a new app, or when an app gets a new security domain. Ordinary changes to an existing app just need Step 7.

Done: your app opens inside Workday and shows your team.

The three ways Claude connects to Workday

Claude can connect to Workday in three separate ways. Each has its own sign-in and does a different job. Steps 1–8 only need the first one, which you've already set up. The other two are optional, for when you want Claude to read or change your tenant's data (people, teams, time off).

Which should you use?

• Building an Extend app: A only. Your app reads Workday data by itself when it runs, so Claude doesn't need B or C for that.
• Asking Claude questions about your tenant's data: B. It's quicker to set up, needs no secret, and is the one we've confirmed works on a personal tenant.
• Wanting Workday's own data tools inside Claude: C, once you've done B and want more, and once there's a way to register an agent on your tenant (see below). Keep the two MCP servers under different names (workday for A, workday-data for C) so they don't clash.

The word "MCP" shows up in both A and C, but they're different servers. A runs on your computer and only knows about building apps. C is Workday's hosted server and only knows about your data.

How to set up A: build apps

This is Steps 3–5 above: install wdcli, sign it in, then add it to Claude Code with claude mcp add --scope user workday -- wdcli mcp. Nothing to do in the tenant.

How to set up B: data through REST (about 20 minutes)

1. Register an API client inside your tenant. Workday's docs say to create it on the Developer Site under Console → API Clients, but personal accounts don't have that menu, so you do it in the tenant. Sign in as your demo user (for example lmcneil), search for the task Register API Client, and fill it in exactly like this:

   Field	Value
   Client Name	claude-code (any name works)
   Client Grant Type	Authorization Code Grant
   Access Token Type	Bearer
   Redirection URI	https://example.com/callback
   Support Proof Key for Code Exchange (PKCE)	Ticked. This is why no client secret is ever needed.
   Scope (Functional Areas)	Staffing, Time Off and Leave, Organizations and Roles, System, Agent System of Record
   Include Workday Owned Scope	Ticked

   Click OK. Workday may still show a client secret. You won't need it, but don't put it in any file or chat.

2. Copy the client's details. Run the report View API Clients and open your client. Copy four values: Client ID, Authorization Endpoint, Token Endpoint and Workday REST API Endpoint. None of these are secret.

3. Give them to Claude. Paste the four values into chat and ask: "Save these and set up a REST sign-in to my tenant with this API client." If you don't already have a sign-in script, Claude writes one for you. Ours is called wd.py, and it keeps these non-secret settings in a file called tenant.env.

4. Sign in. Claude gives you a sign-in link. Open it, sign in as your demo user, and approve. The browser lands on https://example.com/callback?code=..., and that page may not load. Copy the whole address from the address bar and paste it to Claude. The code in it works once, expires in minutes, and is useless without a key saved on your computer, so it's safe to paste.

5. Ask a question. For example: "Who am I, and who reports to me?" Our first answer was Logan McNeil, Chief Human Resources Officer, with two direct reports.

Check: Claude shows your own worker record. When answers start failing with "401" (after about an hour), repeat step 4.

If an answer comes back empty or with "403", the API client is missing the scope for that kind of data. Add it in the tenant (step 1), then sign in again.

How to set up C: data through Workday's MCP server (about 45 minutes)

We haven't got this route working on a personal tenant yet. Use B for data. Below is what C needs, what we tried, and the steps to follow if you do get an agent.

What C needs: an agent registered in Workday's Agent System of Record, then switched on in the tenant's Agent Management Hub. Switching it on shows a Client ID and Client Secret once. An agent is a different thing from the API client in B, although B's client has the Agent System of Record scope.

What we tried (October 2026), so you don't have to:

Still to check: whether the tenant has its own screen for creating an agent. Search the tenant for agent and look at Agent Management Hub and View Agent Platforms.

If you do get an agent:

1. Switch it on. In Agent Management Hub → Agent Registry → your agent, turn its skills on, choose Available To (a security group your demo user is in), and set the redirect URI to https://example.com/callback.
2. Save the secret straight away. Copy the Client ID, Client Secret and endpoint URLs into a password manager. Workday shows the secret once; if you lose it, you have to generate a new one.
3. Put them in workday.env yourself, never in tenant.env and never pasted into chat. workday.env stays on your computer and out of git. GitHub secrets don't help here: GitHub never lets anyone read a secret back.
4. Sign in and connect. Ask Claude to sign in the agent (the same paste-the-address sign-in as B), list its tools, and add Workday's server to Claude Code as workday-data, so it doesn't replace the workday server from A.
5. Ask a question that uses the tools, for example "Use the Workday data tools to list my team."

Check: Claude lists Workday's tools (such as getWorkers) and answers from them. The login expires after about an hour, and then the server has to be reconnected.

Give Claude a memory: CLAUDE.md (10 minutes, do this once)

Claude starts every new session knowing nothing about your project. A file called CLAUDE.md in your apps folder fixes that: Claude Code reads it automatically at the start of every session, so it knows your tenant, your commands and your rules without you repeating them.

1. Create it. Ask Claude: "Create a CLAUDE.md in this folder using the template from my setup guide, and fill in my tenant alias, demo user and app IDs." Or copy the template below into a file called CLAUDE.md yourself.
2. Keep it current. At the end of each working session, ask: "Update CLAUDE.md with where we left off and anything we learned." This is the single most useful habit for picking up where you left off.
3. Commit it with your app, so it's backed up and travels with the code.

Template (replace everything in angle brackets):

# <Your project name>

Workday Extend apps for my personal development tenant, built with Claude Code and wdcli.

## Start of every session
1. `git pull` if I also work on another computer or in the cloud.
2. For deploys: `wdcli tenant login <your-alias>` (I sign in; wait for "Success: token saved").
3. VS Code must be open on this folder for the Workday Developer Agent hand-off.

## Tenant
- Alias: `<your-alias>`. Sign in as `<demo user, e.g. lmcneil>`.
- Tenant host: `https://<tenant-host>`.
- The tenant is deleted after 7 days without a sign-in.
- Never put passwords, client secrets or tokens in any file in this folder, or in chat.

## Apps
- `<app-id>`: <one line on what it does>.
- App address: `https://<tenant-host>/<your-alias>/d/wday/app/<app-id>/<app-id>.htmld`

## Build and deploy
    wdcli auth login -e personal            # personal accounts need -e personal
    wdcli app validate -d <app-id>
    wdcli app upload <app-id> --ci
    wdcli app deploy --app-id <app-id> --latest-version --tenant-alias <your-alias> --ci

After deploying a NEW security domain, I create the policy in Workday Extend App Manager
and run Activate Pending Security Policy Changes. Claude doesn't change tenant security.

## How to work with me
- Check PMD syntax and Workday field names with the Workday Developer Agent; don't guess.
- Run validate before every upload.
- Commit after each working change. Ask before pushing to GitHub.
- After a deploy, remind me what to check in the tenant.

## Things learned the hard way
- Selection widgets return lists of IDs: use `self.value[0]`.
- <add new lessons here as you hit them>

## Where we left off (<date>)
- <what's done, what's deployed, what's not checked yet>

## Open items
- <next things to build or fix>

More tips that help you (and Claude) catch up

• Keep a .gitignore so secrets and sign-in tokens never get committed. Ask Claude: "Add a .gitignore for workday.env, sign-in token folders, .DS_Store and node_modules."
• Put lessons in CLAUDE.md, not just in chat. When something takes more than one try (a field name, a security step, a sign-in quirk), ask Claude to add it under Things learned the hard way. Chat history doesn't carry over to new sessions; CLAUDE.md does.
• Write open items down. A short Open items list means you can start any session with "Pick up the next open item."
• Working in more than one place? Push your commits to GitHub at the end of a session and git pull at the start of the next, or one place falls behind (we lost an hour to exactly this).
• A setup checker saves time. Ask Claude to write scripts/check-setup.sh: a read-only script that checks Python, git, wdcli, its sign-ins, the workday MCP server and the VS Code extension, and prints how to fix anything missing. Run it at the start of a session.
• Starting a fresh session on an old project? Say: "Read CLAUDE.md and the last few commits, then tell me where we left off."

Making changes later

After the first time, a change is one request to Claude. For example: "On the results page, round the averages to one decimal. Check the syntax with the Developer Agent, then validate, upload, deploy and commit." Claude edits the files, runs Step 7, and saves the change in git. Then you open the app and check it looks right.

Each time you sit down to work

1. Open VS Code on your apps folder, and start a local Claude Code session in the same folder.
2. If you haven't deployed for a while, run wdcli tenant login <your-alias> first and wait for Success: token saved.
3. Describe the change. Ask Claude to check anything Workday-specific with the Developer Agent.
4. When Claude has deployed, open the app and check the change in the tenant.
5. Optional: ask Claude to push the commits to GitHub, so your work is backed up.

Keep your tenant alive: sign in to it at least once a week, or it's deleted after 7 days without a sign-in.

Good habits: one change per request; ask Claude to explain anything you don't follow; and never paste passwords, client secrets or tokens into chat.

When something goes wrong