# WorkIQ Connect Microsoft's unified Work IQ MCP to Speakeasy for employees within **one Entra tenant**, using one customer-owned single-tenant application. Administrators configure billing, application access, and consent once; each employee signs in with their own Microsoft account and authorizes a separate delegated session. Expand access in approved employee groups after validation. Each employee needs Microsoft 365 and access to the relevant workloads. Identify the Entra, billing, security-approval, and Speakeasy owners. Administrators need authority to register apps, approve delegated permissions, and configure Microsoft usage-based billing; the Speakeasy owner needs permission to add and distribute a remote MCP. Start in the [Microsoft 365 admin center][admin]; ask your Microsoft administrator to open the Entra application-registration area for your tenant when needed. 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. ### 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. Choose **Specific groups** and select directly populated employee rollout security groups. Include individual users through security groups. Expand by approved wave; use **All users** only after explicitly approving the broader tenant audience. 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 policy and per-user budgets, and enable 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**. Reconcile existing and overlapping policies before expanding: additional policies have independent limits, not a shared cap inherited from the default policy. Billing audiences, enterprise-app assignments, catalog availability, and Speakeasy access are separate controls; align their intended employee populations. 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. **This licensing conflict is unresolved:** confirm requirements with Microsoft for direct MCP access before committing employee eligibility or buying licenses; do not infer a license requirement from an entitlement error. Recheck the mutable Credits Guide before purchase or publication. Use the current guide's rate card; do not assume one MCP call equals one credit. ### Verify unified Work IQ availability for employees Use the unified **Work IQ MCP**, not the legacy workload-specific servers; see the [server comparison][server-options]. No local CLI or self-hosted MCP is needed. 1. Ask the Microsoft administrator to identify the exact tenant-approved unified item, its type, and the supported employee onboarding route. **Agents → Tools** is an admin registry/governance view, not proof of employee installation. 2. If the item is an installable **plugin or skill**, follow the documented [admin deployment][tool-governance] path: **Agents → Tools → select plugin/skill → Install → Specific users or groups → review → Install**. Verify availability for the rollout groups. This plugin/skill procedure does not establish deployment requirements for a standalone MCP server. 3. If it is an **MCP registry item**, follow the tenant's MCP approval, consent, and tool-governance workflow instead. Do not assume plugin installation or admin assignment replaces employee installation, or invent a universal self-install route. 4. Validate the approved route with a newly onboarded ordinary employee and record the exact item and steps before expanding. Catalog availability does not replace billing, OAuth consent, application assignment, or each employee's sign-in. The source pilot reports reads succeeding after user installation, but captured no exact self-install link and did not exclude concurrent backend changes. Microsoft's [overview][work-iq-overview], [tenant enablement][tenant-enablement], and [Foundry quickstart][foundry] do not establish a universal additional employee catalog-install prerequisite. Confirm with Microsoft or compare fresh employee accounts before removing this check. ### Register and restrict the Entra application In **Entra → App registrations**, create one dedicated, production-managed application for this organization. Single-tenant means one home tenant, not one user; it can also include guests ([audience guidance][app-audience]). **Before creating a client secret:** Entra displays its **Value** only once. Be ready to store it in your approved password manager; never put it in screenshots or support transcripts. 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. Enter the callback for your Speakeasy deployment: ```text https://ai.speakeasy.com/mcp/remote_login_callback ``` During [Speakeasy credential setup](#connect-speakeasy-credentials), verify that the displayed **Redirect URI** exactly matches this **Web** callback. Do not use an MCP client's localhost callback. 4. Under **Certificates & secrets**, create a client secret with an approved lifetime. 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**, set **Assignment required? → Yes**. Under **Users and groups**, assign approved employee rollout groups. [Group assignment][app-assignment] requires Entra ID P1/P2 and does **not** expand nested groups; use direct membership or direct user assignment if group assignment is not licensed. Keep an owner and expiry/rotation procedure for the secret; employees must not receive it or another employee's access/refresh tokens. Single-tenant alone is not employee-only: exclude guests from assignments. Global Administrators can bypass the assignment restriction, so validate allowed and denied access with ordinary accounts ([application properties][app-properties]). This connection uses delegated access as the signed-in user. Do not enable application-only access as a substitute. ### 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. **Warning:** `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 employee assignment restrictions in place. Access remains bounded by the signed-in user's permissions. In the dedicated app, add the Work IQ **delegated** permission **WorkIQAgent.Ask**. Review Microsoft's [permission description][permissions] first. Adding a requested permission is separate from granting consent. Inspect existing grants first. An authorized administrator must approve **tenant-wide delegated consent** for employee rollout using the [Entra portal workflow][admin-consent]: 1. Open **Entra ID → App registrations → select the dedicated app → API permissions**. 2. Verify the requested Work IQ permission is **Delegated: WorkIQAgent.Ask**, then select **Grant admin consent for **. Review the permissions and confirm only the approved grant. 3. Verify consent is granted and **Assignment required?** remains **Yes** on the enterprise application. Tenant-wide delegated consent (`AllPrincipals`) approves the scope; it is not application-only access, employee assignment, billing enrollment, or a shared employee session. Employees still sign in individually. Do not add unrelated Graph permissions as a speculative fix. If administrators separately automate consent through Graph, `clientId` and `resourceId` refer to service-principal **object IDs**, not application/client IDs; review existing grants rather than blindly creating duplicates. ### Optional pilot before expansion Use a directly populated pilot employee group for billing, application assignment, and any verified catalog deployment. Keep Speakeasy distribution limited until acceptance tests pass. The same single-tenant registration can serve later employee waves; a separate app per employee is unnecessary. Before expansion, verify two ordinary employees authorize separately and see only their own accessible data; test that an unassigned employee and guest are denied, plus token refresh, offboarding, and actual per-user billing. Validate Speakeasy session isolation in your deployment; Microsoft documentation does not establish Speakeasy's implementation. Start with tiny read-only tests despite the broad read/write grant. [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 [work-iq-overview]: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/mcp/overview [tenant-enablement]: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/enable-work-iq [tool-governance]: https://learn.microsoft.com/en-us/microsoft-agent-365/admin/manage-plugins-skills-mcp-servers [app-audience]: https://learn.microsoft.com/en-us/entra/identity-platform/single-and-multi-tenant-apps [app-assignment]: https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal [app-properties]: https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/application-properties [admin-consent]: https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent ### Add the server in Speakeasy Configure one server for the approved employee audience in your organization. An administrator configures the OAuth client once; each employee signs in with their own Microsoft account. Share the server configuration, never an employee's access or refresh token. Keep access limited to the validation group until the rollout checks below pass; private visibility alone is not an access control. 1. Select the intended project in the Speakeasy AI Control Plane. 2. In the sidebar, under **MCP Gateway**, select **MCP**. 3. Click **Add new** to open **Add MCP server**. 4. Choose **Hosted remotely**. 5. On **New remote MCP server**, enter this **MCP server URL**: ```text https://workiq.svc.cloud.microsoft/mcp ``` 6. Leave **User session issuer** at its default. 7. Click **Verify connectivity**. 8. Under **Identity**, select **User Identity**. 9. Leave **Guardrails** off unless your organization requires one. 10. Click **Save** to open the server's **Overview**. If the server stays **Disabled** and asks you to finish setup in **Settings > Identity**, continue below. Connectivity verification does not prove access to Microsoft 365 data. ### Connect your credentials Use the dedicated, single-tenant application from [Register and restrict the Entra application](#register-entra-application). Do not modify an identity provider shared by unrelated servers. Use a custom provider with a manually registered client, not automatic client registration. The source pilot used **Settings → Authentication**. The native flow below uses **Settings > Identity**. The source pilot required the selected client method `client_secret_post`; do not treat an issuer's list of supported methods as proof that this method is selected. If your deployment does not expose the client-method control, ask your Speakeasy administrator to verify the selected method before continuing. 1. Open the server's **Settings > Identity**. 2. Select **User Identity**. 3. Open **Choose an identity provider** and click **Create a custom identity provider**. This opens **Remote Identity Providers**. 4. Click **New Remote Identity Provider**. 5. In **Issuer URL**, enter the following, replacing `` with the **Directory (tenant) ID** from [Register and restrict the Entra application](#register-entra-application): ```text https://login.microsoftonline.com//v2.0 ``` 6. Click **Discover** to populate the endpoints. 7. Under **Endpoints**, verify **Authorization Endpoint**: ```text https://login.microsoftonline.com//oauth2/v2.0/authorize ``` 8. Verify **Token Endpoint**: ```text https://login.microsoftonline.com//oauth2/v2.0/token ``` 9. Keep the derived **Slug** and click **Create**. 10. On the dedicated provider, click **Add Client**. 11. Set **Client Type** to **Manual**. 12. Paste the application's **Application (client) ID** into **Client ID**. 13. Paste the secret **Value** from [Register and restrict the Entra application](#register-entra-application) into **Client Secret (optional)**. A secret is required for this flow despite the field's optional label. 14. In **Scope (override)**, enter the following comma-separated scopes: ```text openid,profile,offline_access,fdcc1f02-fc51-4226-8753-f668596af7f7/WorkIQAgent.Ask ``` 15. In the client credentials/session client section, select **Token endpoint authentication** as `client_secret_post` (`tokenEndpointAuthMethod`), using the equivalent client-method control on your deployment. 16. Confirm that the displayed **Redirect URI** matches the **Web** callback registered in [Register and restrict the Entra application](#register-entra-application). 17. Save the client with **Create**, or the equivalent save control on your deployment. 18. Reopen the provider and confirm that `client_secret_post` persisted as the selected client method. 19. Return to the server's **Settings > Identity** and select **User Identity**. 20. In **Choose an identity provider**, select the dedicated provider you created. 21. Choose **Existing client** and pick the new client under **Client**. 22. Click **Save**. If prompted, confirm with **Save changes**. 23. If the server is **Disabled**, open **Settings > Danger Zone > Server Availability** and turn on **Enable MCP server** so it shows **Enabled**. The discovery field **Token endpoint authentication methods** lists supported methods, not the selected client method. The source pilot reports that selecting `client_secret_post` resolved `invalid_client`; other advertised methods may need different credentials or key configuration. That result was not retested for this migration. The requested scope set is the following space-separated OAuth value; the custom-provider **Scope (override)** input above uses commas between entries: ```text openid profile offline_access fdcc1f02-fc51-4226-8753-f668596af7f7/WorkIQAgent.Ask ``` The source reports that Work IQ advertised the GUID-prefixed scope through this protected-resource metadata URL: ```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 pilot's working advertised scope; do not substitute a Microsoft Graph scope or leave the configured scope blank. ### Connect as an employee and test An administrator must first complete the Entra consent, employee assignments, billing audience, and tenant availability checks in [Microsoft setup](external.md). Tenant-wide consent does not sign employees in or give them a shared session. Employees do not need the Entra client secret. 1. Use **Connect/Authorize**, or the equivalent authorization control in your deployment, and sign in with your own assigned employee account. 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. The migration did not rerun the source pilot’s tests. 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 affected employee's assignment, the enabled policy's service and user/group scope, tenant-approved Work IQ availability or installation requirements, 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. ### Validate and distribute employee access Before widening access, have at least two assigned employees connect independently through the Speakeasy MCP endpoint. Verify that `/me` requests run as the correct employee and do not reuse the administrator's or another employee's session. Use approved test data; do not copy business content into logs or the rollout record. Verify refresh or reauthorization and test that an unassigned account is denied, using an ordinary nonadministrator test account. These are required rollout checks, not capabilities established by the source pilot. Have your Speakeasy administrator grant server access to the approved employee audience using the access controls available in your deployment, and distribute the Speakeasy MCP endpoint and employee sign-in instructions. The exact sharing UI and its enforcement have not been validated for this guide. Do not make the server public as a substitute. Keep **User Identity** selected; one dashboard connection does not authenticate everyone. Align the approved employee population across Entra assignment, billing policies, any tenant catalog controls, and Speakeasy access. Each control is separate. If tenant installation or licensing requirements remain unresolved, keep the rollout restricted until your Microsoft administrator confirms eligibility. ### Maintain and revoke access Assign an owner for the Entra client secret, track its expiry, and rotate it using your approved secret-management process. Update the configured Speakeasy client and verify fresh authorization and existing sessions during rotation. Never distribute the secret to employees. For offboarding, remove the employee's access in Entra and Speakeasy, and revoke relevant sessions through your administrators' established process; do not assume a group change immediately invalidates an already issued token. Review billing and catalog audiences separately. When retiring the integration, 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. [cost-api]: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/api/admin-settings/cost-management/overview This guide covers setup only. For anything beyond it — billing, tool behavior, limits — see [Microsoft's Work IQ MCP documentation](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/mcp/quickstart/foundry). --- 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`.