Set up Microsoft Work IQ MCP Server

Microsoft 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 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 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 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 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 and export traces to your observability stack via OpenTelemetry.
Guardrails - Apply pre-tool and post-tool guardrails 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, 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

Enable Work IQ in your tenant

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.Until this is done, Work IQ won’t appear when you search API permissions in Step 4.

In the Microsoft Entra admin center, go to Entra ID → App registrations → New registration.
Give it a recognizable name, such as TrueFoundry Work IQ Connector.
Set Supported account types to Accounts in this organizational directory only (single tenant).
Under Redirect URI, choose the Web platform - not mobile or desktop - and enter TrueFoundry’s OAuth callback:
https://<tfy-control-plane-base-url>/api/svc/v1/llm-gateway/mcp-servers/oauth2/callback
Replace <tfy-control-plane-base-url> with your TrueFoundry control plane URL.
Select Register, then copy the Application (client) ID and the Directory (tenant) ID from the overview page.

Add a client secret

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.

Add the Work IQ permission and grant admin consent

Go to API permissions → Add a permission → APIs my organization uses and search for Work IQ (application ID fdcc1f02-fc51-4226-8753-f668596af7f7).
Select Delegated permissions, check WorkIQAgent.Ask, and select Add permissions.
Select Grant admin consent for <your tenant> 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/<tenant-id>/oauth2/v2.0/authorize`
Token URL	`https://login.microsoftonline.com/<tenant-id>/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:

work-iq.yaml

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/<tenant-id>/oauth2/v2.0/authorize
  token_url: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
  client_id: "<application-client-id>"
  client_secret: "<client-secret-value>"
  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.

Connect and authorize

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.
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.
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.
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.
No automatic retries. Work IQ passes through Graph status codes and Retry-After headers and leaves retry decisions to the client. See 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 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 for denylist and allowlist modes.

​Using Work IQ through the MCP Gateway

​Prerequisites

​Adding Work IQ MCP server to TrueFoundry

​Path and policy limits

​Connecting to an MCP Client

​Tool Metrics

​Disabling Individual Tools

Using Work IQ through the MCP Gateway

Prerequisites

Adding Work IQ MCP server to TrueFoundry

Path and policy limits

Connecting to an MCP Client

Tool Metrics

Disabling Individual Tools