# 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][admin], open **Copilot → Cost management**. Follow Microsoft's [billing setup][billing-setup] and [spending-policy][spending-policies] 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][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][foundry] 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][server-options]. 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:

   ```text
   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:

```bash
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:

```bash
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][permissions] 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:

```http
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](/docs/ai-control-plane/mcp-gateway/remote-servers) using Microsoft's public upstream URL:

   ```text
   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//v2.0`                                 |
| Authorization endpoint                 | `https://login.microsoftonline.com//oauth2/v2.0/authorize`                |
| Token endpoint                         | `https://login.microsoftonline.com//oauth2/v2.0/token`                    |
| 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:

```text
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:

```json
{ "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][cost-api] 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.

[admin]: https://admin.microsoft.com
[billing-setup]: https://learn.microsoft.com/en-us/microsoft-365/copilot/usage-based-billing-copilot-credits-setup
[spending-policies]: https://learn.microsoft.com/en-us/microsoft-365/copilot/usage-based-billing-manage-copilot-credits
[credits-guide]: https://aka.ms/CopilotCredits/LicensingGuide
[foundry]: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/mcp/quickstart/foundry
[permissions]: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/permissions
[server-options]: https://learn.microsoft.com/en-us/microsoft-agent-365/tooling-servers-overview
[cost-api]: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/api/admin-settings/cost-management/overview

---

Index of every Speakeasy page for agents: [llms.txt](https://www.speakeasy.com/llms.txt). AI control plane and MCP gateway content in one file: [llms-full.txt](https://www.speakeasy.com/llms-full.txt). Any page is available as markdown by appending `.md` to its URL or by requesting it with `Accept: text/markdown`.