> ## Documentation Index > Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt > Use this file to discover all available pages before exploring further. # Set up Microsoft Work IQ MCP Server > Register Microsoft's hosted Work IQ MCP server in TrueFoundry so agents reach Microsoft 365 data through per-user Entra ID delegated auth. [Microsoft Work IQ](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/) is Microsoft's workplace intelligence layer over Microsoft 365. Its hosted MCP server exposes mail, calendar, Teams, SharePoint, OneDrive, and Microsoft 365 Copilot through a single remote endpoint, with every request running as the signed-in user and honoring that user's Microsoft 365 permissions. Register it on the [TrueFoundry MCP Gateway](/docs/ai-gateway/mcp/mcp-overview) and your agents reach all of Microsoft 365 through one governed endpoint, with per-user OAuth, tool-level access control, tracing, and guardrails applied by the Gateway. | Property | Value | | ----------------------- | --------------------------------------------------------- | | MCP endpoint | `https://workiq.svc.cloud.microsoft/mcp` | | Server type | Remote (`mcp-server/remote`) | | Auth model | OAuth 2.0 authorization code, delegated (per-user) | | Client type | Confidential client - bring your own Entra app and secret | | Application ID URI | `api://workiq.svc.cloud.microsoft` | | Required scope | `api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask` | | Work IQ resource app ID | `fdcc1f02-fc51-4226-8753-f668596af7f7` | ## Using Work IQ through the MCP Gateway When you use the Work IQ MCP server through the AI Gateway, TrueFoundry provides: * **Authentication** - Clients [authenticate inbound](/docs/ai-gateway/mcp/mcp-gateway-auth-security#inbound-authentication) to the AI Gateway with a Personal Access Token, Virtual Account, or IDE OAuth flow. For outbound access, the AI Gateway runs the [OAuth2 Authorization Code flow](/docs/ai-gateway/mcp/mcp-gateway-auth-security#outbound-authentication) against your Entra app, so each user authorizes with their own Microsoft identity; tokens are stored, refreshed, and injected per user on tool calls. * **Tool-level access control** - Enable or disable individual Work IQ tools from the server detail page. Because Work IQ's write tools (`create_entity`, `update_entity`, `delete_entity`, `do_action`) are generic, disabling them at the Gateway is an effective way to keep an agent read-only. * **Access control** - [Collaborators and role-based policies](/docs/ai-gateway/mcp/mcp-gateway-auth-security#access-control) define who can use the server and which tools they can invoke. * **Observability** - Tool calls are traced with caller identity, tool name, inputs, and latency. Monitor server- and tool-level usage in [MCP Metrics](/docs/ai-gateway/analytics-mcp-metrics) and export traces to your observability stack via OpenTelemetry. * **Guardrails** - Apply [pre-tool and post-tool guardrails](/docs/ai-gateway/guardrails-overview) on MCP tool calls - useful here because a single `fetch` call can return mailbox or SharePoint content. ## Prerequisites Work IQ is gated by tenant-level licensing and billing on top of authentication. All of the following must be in place before the connector passes an end-to-end test: * A TrueFoundry account with permission to add MCP servers, and your TrueFoundry control plane base URL. * A **usage-based billing plan** configured in Copilot Studio, backed by an Azure subscription and resource group, with each user assigned to it. Work IQ API calls meter against [Copilot Credits](https://learn.microsoft.com/en-us/microsoft-365/copilot/usage-based-billing-overview-copilot-credits), and metered tools stay blocked without it. * A **Microsoft 365 Copilot license** for every user who will use the `ask` tool. Newly assigned licenses can take up to 24 hours to activate. * The **Work IQ service principal provisioned** in your tenant (Step 1 below). * A **Global Administrator** to grant admin consent for `WorkIQAgent.Ask`. This is a one-time tenant operation - activate the role just in time through Microsoft Entra PIM and deactivate it afterwards. Day-to-day Work IQ users don't need it. ## Adding Work IQ MCP server to TrueFoundry A Global Administrator provisions the Work IQ service principal once per organization, using Graph Explorer or the Azure CLI. Follow Microsoft's [Enable your tenant for Work IQ](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/enable-work-iq). Until this is done, **Work IQ** won't appear when you search API permissions in Step 4. 1. In the [Microsoft Entra admin center](https://entra.microsoft.com/), go to **Entra ID → App registrations → New registration**. 2. Give it a recognizable name, such as `TrueFoundry Work IQ Connector`. 3. Set **Supported account types** to **Accounts in this organizational directory only** (single tenant). 4. Under **Redirect URI**, choose the **Web** platform - not mobile or desktop - and enter TrueFoundry's OAuth callback: ```txt theme={"dark"} https:///api/svc/v1/llm-gateway/mcp-servers/oauth2/callback ``` Replace `` with your TrueFoundry control plane URL. 5. Select **Register**, then copy the **Application (client) ID** and the **Directory (tenant) ID** from the overview page. Open **Certificates & secrets → New client secret**, set a description and expiry, and copy the secret **Value** immediately - it is shown only once, and it is the **Value**, not the Secret ID, that TrueFoundry needs. Storing a secret is what makes this a confidential client. Store the secret in the TrueFoundry secrets store and reference it by FQN in the server config rather than pasting it inline. Rotate it before it expires. 1. Go to **API permissions → Add a permission → APIs my organization uses** and search for **Work IQ** (application ID `fdcc1f02-fc51-4226-8753-f668596af7f7`). 2. Select **Delegated permissions**, check **WorkIQAgent.Ask**, and select **Add permissions**. 3. Select **Grant admin consent for \** and confirm. The status must turn green. `WorkIQAgent.Ask` requires admin consent and cannot be self-consented by individual users. In **MCP Servers**, click **Add new MCP Server**, select **Connect any Remote MCP Server**, and configure: | Field | Value | | --------------------- | ----------------------------------------------------------------------- | | **Name** | `work-iq` | | **URL** | `https://workiq.svc.cloud.microsoft/mcp` | | **Authentication** | `OAuth2` | | **Grant Type** | `Authorization Code` | | **Authorization URL** | `https://login.microsoftonline.com//oauth2/v2.0/authorize` | | **Token URL** | `https://login.microsoftonline.com//oauth2/v2.0/token` | | **Client ID** | Application (client) ID from Step 2 | | **Client Secret** | Client secret **Value** from Step 3 | | **Scopes** | `api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask` and `offline_access` | | **JWT Source** | `Access Token` | Add **Collaborators** - the users and teams that can use or manage this server - and assign each an **MCP Server Manager** or **MCP Server User** role. Then save. The equivalent YAML, applied with **Apply using YAML** in the UI or `tfy apply -f work-iq.yaml`: ```yaml work-iq.yaml theme={"dark"} name: work-iq type: mcp-server/remote description: Microsoft Work IQ - hosted MCP access to Microsoft 365 via Entra ID url: https://workiq.svc.cloud.microsoft/mcp collaborators: - subject: user:you@your-company.com role_id: mcp-server-manager auth_data: type: oauth2 grant_type: authorization_code authorization_url: https://login.microsoftonline.com//oauth2/v2.0/authorize token_url: https://login.microsoftonline.com//oauth2/v2.0/token client_id: "" client_secret: "" jwt_source: access_token scopes: - api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask - offline_access ``` `offline_access` is what lets the Gateway refresh tokens; without it users have to reauthorize when the access token expires. Because the app is registered **single-tenant**, both authority URLs must use your Directory (tenant) ID - not `organizations` and not `common`. A single-tenant app will not issue tokens through the multi-tenant endpoints. Open the server's **Tools** tab and click **Connect Now**. TrueFoundry runs the authorization-code flow: you sign in with your Microsoft account, consent, and land back on the server detail page. The Gateway stores the token and calls Work IQ on your behalf from then on. Each user connects once with their own identity. ## Path and policy limits Work IQ applies its own tenant policy layer on top of the signed-in user's Microsoft 365 permissions, so a tool call can be refused even when the token is valid. * **Mutations are blocked by default.** A tenant administrator has to enable supported create, update, delete, and action requests through Work IQ tenant policy. See [Policy governance for Work IQ MCP](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/mcp/policy-governance-mcp). * **Allowed path prefixes** are `/me/`, `/users/`, and `/sites/` by default. `/authentication/` and `/servicePrincipals/` are blocked. The exact list depends on your tenant policy. See [Allowed resource paths](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/mcp/tool-reference#allowed-resource-paths). * **Collection results are capped.** A default `$top` of 25 is injected with a maximum of 100, chat messages are capped at 10 per request, and `$skip` and `$skiptoken` are blocked. See [`fetch`](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/mcp/tool-reference#fetch). * **Blob size is capped** at 4 MB by default, configurable per path. A larger file returns a tool error, not partial content. See [`fetch_blob`](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/mcp/tool-reference#fetch_blob). * **No automatic retries.** Work IQ passes through Graph status codes and `Retry-After` headers and leaves retry decisions to the client. See [Error handling](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/mcp/tool-reference#error-handling). ## Connecting to an MCP Client Open the **How To Use** tab on the Work IQ server detail page for your tenant-specific Gateway URL and ready-to-paste client snippets - don't build the endpoint manually. The tab includes snippets for Claude Code, VS Code, Claude Web, Claude Desktop, Cursor, Windsurf, Codex, and the Python and TypeScript MCP SDKs. Use **Show API Key** if your client requires a Gateway token in a header. ## Tool Metrics The **Tool Metrics** tab tracks invocation count, latency, and error rates per tool. See [MCP Metrics](/docs/ai-gateway/analytics-mcp-metrics) for server- and tool-level dashboards across your Gateway. ## Disabling Individual Tools On the **Tools** tab, toggle off any Work IQ tools your agents don't need. Disabled tools are hidden from MCP clients and cannot be invoked. Turning off `create_entity`, `update_entity`, `delete_entity`, and `do_action` gives you a read-only Work IQ server at the Gateway, independent of Work IQ's own tenant policy. See [MCP Tool Management](/docs/ai-gateway/mcp/mcp-tool-management) for denylist and allowlist modes.