WorkIQ

Connect Microsoft’s unified Work IQ MCP to Speakeasy with a customer-owned Microsoft Entra application. Each user signs in with their Microsoft account. Start with one pilot user and a private server before distributing access.

You need a Microsoft 365 user with access to the workloads you will test, permission to add a remote MCP in Speakeasy, and administrators authorized to register Entra apps, approve delegated permissions, and configure Microsoft usage-based billing. Agree on the Azure subscription, service scope, limits, and alerts before activating paid usage. Keep credentials and returned business data out of source control, screenshots, and support transcripts.

Set up WorkIQ

1. Configure usage-based billing

In the Microsoft 365 admin center, open Copilot → Cost management. Follow Microsoft’s billing setup and spending-policy instructions.

1. From Get Started, select Customize setup configuration before activation. The default setup can cover the entire organization. Alternatively, create a separate spending policy under Configuration.
2. Scope the policy to the pilot user, or a security group containing only that user if group selection is required. Prefer direct membership for the pilot.
3. Select Work IQ API for custom apps and agents as the covered service.
4. Turn Auto-apply new services off.
5. Select the approved billing method and Azure subscription. Review resource group and region under advanced settings where available.
6. Set limited policy and per-user budgets, and enable administrator alerts. Limits use credits, not necessarily currency; the portal can impose minimums.
7. Review the service, audience, and billing method, activate the policy, and confirm it shows Enabled.

The October 2026 Copilot Credits Guide, page 14, permits Work IQ API usage on behalf of any Microsoft 365 user with tenant enablement and usage-based billing, subject to underlying workload licenses. Work IQ APIs are not included as Copilot license entitlements. The older June Foundry quickstart instead requires a Microsoft 365 Copilot license per user. Confirm current requirements with Microsoft if needed. Use the current guide’s rate card; do not assume one MCP call equals one credit.

2. Install the unified Work IQ MCP for the user

Use the unified Work IQ MCP, not the separate workload-specific servers. Microsoft describes those as a legacy experience for testing and backward compatibility; see the server comparison. No local CLI or self-hosted MCP is needed.

1. Ask your Microsoft administrator for the tenant-approved unified Work IQ MCP catalog entry and user installation instructions. The exact self-install URL and click path were not captured during validation; confirm them for your tenant.
2. Have the pilot user open that entry and complete installation for their own account, with any required administrator approval.
3. Verify that the unified item is installed for that user.

Administrators can inspect Agents → Tools in the Microsoft 365 admin center. That admin registry view is distinct from user installation; administrator assignment as a substitute for self-installation was not independently validated.

In testing, reads first succeeded after user installation despite an already enabled spending policy. Treat installation as a setup check, not a proven universal cause of entitlement failures; concurrent Microsoft backend changes were not ruled out.

3. Register and restrict the Entra application

In Entra → App registrations, create a dedicated pilot application.

1. Select Accounts in this organizational directory only for a single-tenant app.

2. Record its Application (client) ID and Directory (tenant) ID. The application’s object ID is not its client ID.

3. Add a Web platform redirect URI. For hosted Speakeasy, the validated callback is:

   https://ai.speakeasy.com/mcp/remote_login_callback

   When configuring Speakeasy below, verify that this exactly matches the callback displayed in Settings → Authentication for your deployment. Do not use an MCP client’s localhost callback.

4. Under Certificates & secrets, create a short-lived pilot client secret. Store its Value, not its Secret ID, in your approved password manager for Speakeasy setup. Entra displays the value only once.

5. In the corresponding Enterprise application → Properties, require user assignment. Under Users and groups, assign only the pilot user.

This connection uses delegated access as the signed-in user. Do not enable application-only access as a substitute.

4. Add the Work IQ permission and consent

Microsoft’s public Work IQ identifiers are:

Item	Value
Resource application ID	fdcc1f02-fc51-4226-8753-f668596af7f7
Delegated permission	WorkIQAgent.Ask
Delegated permission ID	0b1715fd-f4bf-4c63-b16d-5be31f9847c2

Check the active tenant and whether the resource service principal already exists:

az account show --query tenantId -o tsv
az ad sp list \
  --filter "appId eq 'fdcc1f02-fc51-4226-8753-f668596af7f7'" \
  --query '[].{id:id,appId:appId}' -o json

Only if the query succeeds with no match, provision the resource service principal:

az ad sp create --id fdcc1f02-fc51-4226-8753-f668596af7f7

Reuse an existing resource. A conflict is not an instruction to delete it. Creating the resource does not configure billing or grant your client access.

In the pilot app, add the Work IQ delegated permission WorkIQAgent.Ask. Review Microsoft’s permission description first.

This is a broad read/write permission

WorkIQAgent.Ask includes read and write capabilities. Running read-only tests does not make the grant read-only. Obtain explicit administrator approval for its breadth and keep the pilot user restriction in place.

Adding a requested permission is separate from granting consent. Use the minimum approved consent scope. For a one-user pilot, an authorized administrator can grant principal-specific consent with Microsoft Graph, after inspecting existing grants:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
  "clientId": "<CLIENT_SERVICE_PRINCIPAL_OBJECT_ID>",
  "consentType": "Principal",
  "principalId": "<PILOT_USER_OBJECT_ID>",
  "resourceId": "<WORK_IQ_SERVICE_PRINCIPAL_OBJECT_ID>",
  "scope": "WorkIQAgent.Ask"
}

Here, clientId and resourceId are service-principal object IDs, not application/client IDs. The principalId is the pilot user’s object ID. Tenant-wide admin consent is broader and requires a separate decision. Do not add unrelated Graph permissions as a speculative fix.

Speakeasy setup

Add the server in Speakeasy

1. Select the intended Speakeasy project.

2. Add a remote MCP server using Microsoft’s public upstream URL:

   https://workiq.svc.cloud.microsoft/mcp

3. Keep the server private and undistributed during setup. Private visibility does not replace explicit access controls.

4. Open Settings → Authentication and verify that the displayed callback exactly matches the Entra Web redirect URI registered above.

Connect credentials

In the server’s Settings → Authentication, add a new custom authorization server. Use manual, pre-registered client setup rather than automatic client registration. Do not modify a provider shared by unrelated servers.

Field	Value
Issuer URL	https://login.microsoftonline.com/<TENANT_ID>/v2.0
Authorization endpoint	https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize
Token endpoint	https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token
Client ID	<CLIENT_ID> from your Entra application
Client secret	The secret Value, entered only in the secure field
Selected token endpoint authentication	client_secret_post
Scopes	openid profile offline_access fdcc1f02-fc51-4226-8753-f668596af7f7/WorkIQAgent.Ask

Use discovery to populate endpoints, then verify the tenant and values. In the client credentials/session client section, select Token endpoint authentication as client_secret_post (tokenEndpointAuthMethod). Save and reopen the provider to confirm that selection persisted, and attach this provider to the remote MCP.

The discovery field Token endpoint authentication methods lists supported methods; it does not show the selected client method. Selecting client_secret_post resolved invalid_client in the pilot. Other advertised methods may require different credentials or key configuration.

Work IQ advertised the GUID-prefixed scope above through its protected-resource metadata:

https://workiq.svc.cloud.microsoft/.well-known/oauth-protected-resource/mcp

Microsoft examples also use api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask. Preserve the working advertised scope; do not substitute a Microsoft Graph scope.

Connect and test

1. Use Connect/Authorize in Speakeasy and sign in as the assigned pilot user.
2. Copy the Speakeasy MCP endpoint from the connection settings into your MCP client, rather than connecting directly to Microsoft for this test.
3. Complete that client’s authorization separately. A successful dashboard connection does not authenticate every separate client.
4. Initialize MCP and list tools.

Use search_paths and get_schema to discover operations, then run small, explicitly read-only fetch requests one at a time. Discovery alone does not prove data access.

Workload	entityUrls entry	Expected result
Mail	/me/messages?$select=id&$top=1	HTTP 200 and a collection
Calendar	/me/events?$select=id&$top=1	HTTP 200; an empty collection is valid
Teams	/me/chats?$select=id&$top=1	HTTP 200 and a collection
OneDrive	/me/drive?$select=id,driveType	HTTP 200 and drive metadata

Example arguments for the discovered fetch tool:

{ "entityUrls": ["/me/messages?$select=id&$top=1"] }

Do not use create_entity, update_entity, delete_entity, or do_action as connectivity checks. A broad ask prompt is not a guaranteed read-only smoke test. Record success/failure and error codes, not returned record IDs or business content.

An empty calendar confirms an authorized read, not useful calendar coverage. Drive metadata does not prove file-content retrieval. These smoke tests do not validate token refresh, writes, file content, Copilot reasoning, or cross-user isolation. Test those separately, with actual workflows and Speakeasy policy/logging behavior, before rollout.

If OAuth fails with invalid_client, check the attached provider’s application/client ID, tenant-specific endpoints, Web callback, unexpired secret Value, and selected client_secret_post method. Save, reopen, and reauthorize the client.

If reads report a missing WorkIQ billing policy or notEntitled, check the enabled policy’s service and user/group scope, unified Work IQ MCP installation, and billing activation. An enabled policy alone does not prove eligibility. Microsoft’s read-only cost-management diagnostics can help an authorized administrator: a selected policy with remaining credits and isConsumptionAllowed: false indicates an entitlement denial, not an exhausted budget or a specific missing license. Do not broaden the Work IQ app’s grants, raise budgets, or buy licenses solely from this error. Escalate unresolved failures to Microsoft with sanitized request IDs and timestamps.

When retiring the pilot, revoke only dedicated credentials, grants, assignments, and resources after checking dependencies. Do not delete the shared Microsoft Work IQ resource service principal or a Dataverse environment.