Where Workday's MCP server is and what it takes to use it

Workday's MCP server is the Agent Gateway endpoint https://{agentGatewayRegionEndpoint}/{tenantName}/mcp (in the US, https://us.agent.workday.com/{tenantName}/mcp), and an outside agent can call it only after the agent is registered in the tenant's Agent System of Record (ASOR), its skills are enabled for chosen security groups, and a user has signed in to give it an Agent System User (ASU) token. Until all three are in place, no outside platform can call a single tool.

Workday's page on connecting external agents says the capability is for Extend Professional customers (Workday has since renamed that SKU Extend AI). Under the Universal Main Subscription Agreement (UMSA) the feature is available automatically. An organization still on the Main Service Agreement (MSA) has to opt in to UMSA and enable the feature through Innovation Services, although Workday's registration page says UMSA isn't required in non-Production tenants for self-built agents.

What sits behind the endpoint

The tools your agent sees are Workday's Agent-Ready MCP tools: Workday-built interfaces over Workday functions, with flattened schemas and descriptions written for a model to read. The MCP Explorer on the Developer Site groups them into three types: Basic (read-only), Advanced (write) and Prompt (read-only tools that supply the prompt-value IDs some write tools need).

Two properties decide how you build against them:

  • Delegate security. In delegate mode the agent acts for the signed-in user and is never given more than that user's access. Every call is checked against both the agent's registration and the user's security.
  • No versioning. Workday's change policy says tool names, schemas, field names and descriptions change without notice, the MCP Explorer updates weekly on Tuesdays, and binding prompts or code to specific tool names is prohibited. The tools are for AI agents only, not for hard-coded integrations.

Workday's change policy lists the MCP protocol versions the server supports: 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25. A client on another version may not connect.

Step 1: set up Agent System of Record

ASOR has to be set up in each tenant before anything else, because Workday has no way to migrate ASOR configuration between tenants. Setup means enabling the Agent System of Record functional area with the Maintain Functional Areas task, configuring the ASOR domain security policies, and running Activate Pending Security Policy Changes. The people doing the next steps need Setup: Agents, Manage: Agents and Agent Management Hub in the Agent System of Record functional area, plus Set Up: Tenant Setup - Security in the System functional area for registration.

Step 2: choose the tools

Browse the MCP Explorer and copy the WID of each tool the agent should have. If a write tool lists required prompts in its Details section, copy the WIDs of those prompt tools too; Workday says you must always include both. For example, Workday's sample preferred-name agent registers create_worker_preferred_name_change together with four prompt tools that list valid name salutations, titles and suffixes.

To search programmatically, the ASOR Agent Resource Search API at GET https://us.agent.workday.com/asor/agentResourceSearch/v1 takes searchString, toolType (AGENT_READY for Workday's tools), operationType and protocol=MCP, and returns each tool's wid. Workday's troubleshooting page writes the same API's path as /asor/v1/agentResourceSearch, so check which form your region's gateway accepts.

Step 3: register the agent through the ASOR API

External agents can only be registered through the API, with a POST to https://us.agent.workday.com/asor/v1/agentDefinition, an Authorization: Bearer token for a user with Setup: Agents, and a wd-agent-tenant-alias header. The body follows Workday's ASOR v1.2 schema on GitHub. The part that matters for MCP is workdayConfig, which lists each skill's tools by WID and sets its execution mode:

"workdayConfig": [
  {
    "skillId": "preferred_name_change",
    "executionMode": { "id": "Mode=Delegate" },
    "workdayResources": [
      {
        "description": "Create Worker Preferred Name Change",
        "tool_name": "create_worker_preferred_name_change",
        "agent_resource": { "id": "<WID from the MCP Explorer>" }
      }
    ]
  }
]

The provider ID comes from the View Agent Provider task and the platform ID from View Agent Platforms. To get the registration token, Workday Extend users can sign in to a tenant from the Developer Site user menu (Tenant > Sign In to Tenant) and use that session; otherwise register an API client with the Authorization Code Grant and the Agent System of Record scope. Re-posting a definition with the same name, version and provider updates it instead of creating a new agent.

The guide to connecting a custom agent to Agent System of Record walks through the registration body field by field.

Step 4: configure and activate the agent

In the Agent Management Hub report, open Agent Registry, select the agent and click Configure Agent:

  1. Turn on each skill the agent should use.
  2. For each delegate skill, fill Available To with the security groups allowed to use it. Those groups also need access to the domains or business process policies behind the skill's tools; the View Security for Agent Skill report shows which.
  3. Enter the agent's Redirect URI, the callback your MCP client or agent platform uses for OAuth.
  4. Save. On first configuration Workday shows the OAuth details once: authorize endpoint, token endpoint, MCP endpoint URL and the client ID and secret. Copy them now. The page won't show the secret again, though you can generate a new one later on the agent's Credentials tab.
  5. Back in Agent Registry, click Activate Agent.

Workday then creates the agent's ASU and an Agent Security Group, which the All AI Agent Accounts report lists.

Step 5: get an ASU token

Workday's MCP authentication is OAuth 2.1 with PKCE, and most agent platforms run that flow themselves. To test by hand in Bruno or Postman:

GET  https://us.agent.workday.com/auth/authorize/<tenant>
     ?response_type=code&client_id=<id>&redirect_uri=<uri>

POST https://us.agent.workday.com/auth/oauth2/<tenant>/token
     Content-Type: application/x-www-form-urlencoded
     grant_type=authorization_code&code=<code>&client_id=<id>&client_secret=<secret>

The authorize step sends the person to a Workday sign-in, then an Allow/Deny page; the token response holds an access token and a refresh token. On lifetimes, Workday's own pages disagree: the MCP connection page says access tokens last 60 minutes and refresh tokens should be renewed after 24 hours, while the ASU considerations page gives 14,400 seconds (4 hours) for access tokens and 24 hours for refresh tokens. Build the client to refresh on expiry rather than on a fixed clock. Workday also says expires_in may arrive as a string or an integer, so parse both.

Step 6: confirm the connection, then add it to your agent

Send a tools/list request with the ASU token:

curl --request POST \
  --url "https://us.agent.workday.com/<tenant>/mcp" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <ASU token>" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Workday's page says a 200 with the list of your registered tools means the wiring is right. The list holds the tools registered on your agent, not the whole MCP Explorer catalogue.

Then configure your platform. Workday says any MCP-capable platform (it names Google Agentspace, Amazon Bedrock AgentCore and Microsoft Copilot Studio, and its overview page names Claude and Cursor) uses the same endpoint and OAuth client. Its Cursor example is a custom MCP entry in mcp.json with the endpoint URL and an Authorization: Bearer header. A static bearer token works for a first test, but it expires; for daily use, let the client run the OAuth flow with the client ID, secret and redirect URI from step 4.

What usually goes wrong at this stage

  • A tool you registered isn't listed. Workday's troubleshooting page for Custom Agent Actions, which reach agents through the same Agent Gateway, says a tool is listed only when its skill is enabled and the signed-in user is in a group in Available To, and that no error is returned otherwise; the tool is just absent.
  • You added a tool and the agent still can't see it. The same page says an access token issued before a registration change doesn't include the new resources. Sign in again.
  • Calls fail for some users only. Their security groups lack a policy behind the tool. Look for Review Required or Config Required in the View Security for Agent Skill report.
  • A long tool name breaks the client. Workday acknowledges some hosts have limits on tool-name length and suggests removing those tools from the registration and reporting them.
  • Calls are throttled under load. Workday's service protections allow 2,000 concurrent requests, with a refresh rate and a burst limit of 500 requests each.

Testing Workday MCP tools covers how to prove each tool does what the agent thinks it does once the connection is up, and Agent-Ready Tools explained covers how they're billed.