New Universal Work IQ MCP Server Integration Guide

Work IQ is a workplace intelligence layer that combines Microsoft 365 data with contextual understanding so AI agents can reason over work and take action. With the new unified Work IQ API, Microsoft has moved away from separate workload-specific endpoints (like Mail, Calendar, or Teams servers) in favor of a single, universal Model Context Protocol (MCP) server.

This article details the new architecture, how to enable Work IQ in your tenant, and how to use the universal Work IQ MCP server to build custom, 3rd-party agents that securely integrate with Microsoft 365 data.

Prerequisites

• A usage-based billing plan set up in Copilot Studio with an Azure subscription and resource group assigned.
• Global Administrator role for the one-time Work IQ setup in your tenant.
• Node.js installed if you plan to use the Work IQ CLI locally.

Step 1: Enable Work IQ API in your organization

Before any applications or agents can query Work IQ, the Work IQ service principal must be provisioned in your tenant.

You can do this using the Graph Explorer or the Azure CLI.

Option A: Azure CLI (Fastest)

If you have the Azure CLI installed and are signed in as an administrator, you can run the following command to provision the Work IQ service principal:

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

Option B: Graph Explorer

1. Go to Graph Explorer and sign in with an admin account.
2. Set the method to POST and the URL to https://graph.microsoft.com/v1.0/servicePrincipals.
3. Select Modify permissions and consent to Application.ReadWrite.All.
4. Enter the following in the Request body:

{
  "appId": "fdcc1f02-fc51-4226-8753-f668596af7f7"
}

5. Select Run query. A 201 Created response confirms success. (A conflict error means the service principal already exists).

Step 2: Authentication & Scope Requirements

Work IQ relies on Microsoft Entra ID delegated authentication. Requests must run in the context of the signed-in user (On-behalf-of flows are supported), and application-only authentication is not supported.

While the API is governed by a unified endpoint, you must still grant the correct broad OAuth scopes to your application to access specific Microsoft 365 capabilities. Work IQ MCP clients automatically discover the required authentication configuration through the /.well-known/oauth-protected-resource endpoint, but if you need to manually configure your OAuth client, use the following configuration:

Step 3: The New Entity Model

In previous versions, you had to connect to specific MCP servers like mcp_MailTools or mcp_TeamsTools. The new Work IQ MCP uses a path-based entity model accessed via a single, unified endpoint:

Work IQ MCP exposes a small set of generic tools (just 10 in total) that operate on relative resource paths mapping to Microsoft Graph endpoints (e.g., /me/messages).

Tool Categories

Step 4: Using the Tools

Let’s look at how your custom agent can interact with these generic tools.

Fetching Data (fetch)

Instead of using a specialized mail tool, you use the generic fetch tool and provide the /me/messages path.

{
  "method": "tools/call",
  "params": {
    "name": "fetch",
    "arguments": {
      "entityUrls": ["/me/messages"]
    }
  }
}

Asking Copilot (ask)

You can directly prompt Microsoft 365 Copilot to reason over the user’s data using the ask tool. This is great when the user asks an open-ended question and you want Copilot to do the heavy lifting.

{
  "method": "tools/call",
  "params": {
    "name": "ask",
    "arguments": {
      "question": "Do I have any meetings today?"
    }
  }
}

Discovering Schemas (get_schema & search_paths)

To prevent your agent from being overwhelmed with massive Graph API schema definitions, Work IQ relies on runtime discovery. Your agent can use search_paths to find what’s available and get_schema to learn how to use it.

{
  "method": "tools/call",
  "params": {
    "name": "get_schema",
    "arguments": {
      "path": "/me/messages",
      "operationType": "fetch"
    }
  }
}

Step 5: The Work IQ CLI & Local MCP

If you are building an AI assistant in your IDE (like GitHub Copilot in VS Code) or CLI, you can run Work IQ as a Local MCP server.

You can install it globally via npm:

npm install -g @microsoft/workiq

Or run it directly without installation:

npx -y @microsoft/workiq mcp

VS Code MCP Configuration

Add the following to your VS Code MCP settings file to seamlessly connect your local AI coding assistant to your Microsoft 365 context:

{
  "workiq": {
    "command": "npx",
    "args": ["-y", "@microsoft/workiq", "mcp"],
    "tools": ["*"]
  }
}

Policy Governance & Security

Work IQ MCP doesn’t just rely on Entra ID delegated authentication; it introduces a robust Rego-based policy layer using Open Policy Agent (OPA).

While Entra ID confirms who the user is, and OAuth scopes define what the app can do, the tenant policy layer evaluates every single MCP request at runtime. It looks at the tool being used, the path being requested, and the specific operation.

By default, mutation operations (like create_entity or delete_entity) are typically restricted for safety. If an agent tries to send an email or delete a file without policy clearance, the Work IQ server will reject the request with a policy-denied error (usually a 403 Forbidden).

Tenant administrators can manage these policies in the Microsoft 365 admin center under Agents > Tools.

Enforcement Policies Overview

To provide more comprehensive information, here is the full list of enforcement policies available for the Work IQ MCP server.

Path Access

Governance for Microsoft 365 data entities accessible to MCP tools.

Query Limits

Query execution limits for MCP tools (read-only).

Collection Limits

Governance for retrieval limits allowed for MCP tools.

Mutations

Governance for Microsoft 365 data write actions allowed for MCP tools. (Note: All mutations are disabled by default; the status below reflects a configuration that allows sending emails and creating tasks).