Work IQ MCP (Model Context Protocol) servers provide a secure, standardized way to integrate Microsoft 365 data—like emails, calendar events, Teams chats, and SharePoint files—directly into your AI agents. While you can use these servers easily within Microsoft Copilot Studio and Microsoft Foundry, you might want to connect an entirely custom, 3rd-party agent or web service to these endpoints to ground your own LLMs with enterprise data.

This article details the step-by-step process of registering the Work IQ MCP app in your tenant, configuring an Entra ID application, requesting delegated permissions, and connecting your custom application to Work IQ MCP endpoints.

Prerequisites

• Global Administrator or Privileged Role Administrator access to your Microsoft Entra ID tenant to run enablement scripts and grant admin consent.
• A Microsoft 365 Copilot license for the user accounts that will be authenticating and using the tools.
• A custom agent or web service architecture capable of handling OAuth 2.0 Authorization Code or Device Code flows.

Step 1: Register Work IQ MCP tools in your tenant

Before any applications can query the Work IQ MCP servers, the tools must be enabled in your Microsoft 365 tenant. The Microsoft Work IQ GitHub repository provides PowerShell scripts to automate this setup.

1. Download the scripts from the Work IQ GitHub Repository.
2. Open PowerShell as an administrator.
3. Run the Enable-WorkIQToolsForTenant.ps1 script to register the necessary service principals in your tenant.
   Code

   Copy

   .\Enable-WorkIQToolsForTenant.ps1

4. Follow the prompts to authenticate as a tenant administrator.
5. Once complete, run Verify-WorkIQTenant.ps1 to ensure the tools were provisioned correctly.
   Code

   Copy

   .\Verify-WorkIQTenant.ps1

Step 2: Register an app in Microsoft Entra ID

Your custom agent needs its own identity in Entra ID to request tokens for the Work IQ MCP servers.

1. Go to the Microsoft Entra admin center.
2. Navigate to Identity > Applications > App registrations and select New registration.
3. Provide a name for your custom agent (e.g., My Custom WorkIQ Agent).
4. Under Supported account types, choose Accounts in this organizational directory only (Single tenant) or multi-tenant depending on your architecture.
5. Provide a Redirect URI (e.g., Web or Single-page application (SPA) pointing to http://localhost:3000/auth/callback for local development).
6. Click Register.

Add API Permissions: V1 vs V2 Architecture

When searching for APIs to add to your app registration, you will likely encounter different Work IQ variants. Microsoft is currently transitioning between two distinct permission models:

1. In your new App Registration, go to API permissions > Add a permission.
2. Select APIs my organization uses.
3. Search for Work IQ or Agent 365.
4. Choose the V2 specific server (e.g., Work IQ Teams MCP) and select the Tools.ListInvoke.All permission.
5. Provide Admin consent for the tenant to ensure users aren’t blocked by consent prompts.

Step 3: Authenticate the user (Delegated Permissions)

Your application must acquire an access token on behalf of the user. The user must have a Microsoft 365 Copilot license. This is typically done using MSAL (Microsoft Authentication Library).

Here is a simplified example using msal-node in an Express.js application:

import { ConfidentialClientApplication } from "@azure/msal-node";

const msalConfig = {
  auth: {
    clientId: process.env.AZURE_CLIENT_ID,
    clientSecret: process.env.AZURE_CLIENT_SECRET,
    authority: `https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}`,
  },
};
const pca = new ConfidentialClientApplication(msalConfig);

// During authentication, request the scopes mapped to your Work IQ MCP servers
// e.g., ["api://<WorkIQ-Mail-App-ID>/User.Read", "api://<WorkIQ-Calendar-App-ID>/User.Read"]
const result = await pca.acquireTokenByCode({
  code: req.query.code,
  scopes: process.env.WORKIQ_SCOPES.split(","),
  redirectUri: "http://localhost:3000/auth/callback",
});

const accessToken = result.accessToken;

Step 4: Connect to Work IQ MCP endpoints

The MCP servers operate over standard HTTP using JSON-RPC 2.0 payloads. They are tenant-scoped endpoints hosted at a specific URL pattern. You can target different workloads by replacing the {server_name} in the following base URL:

https://agent365.svc.cloud.microsoft/agents/tenants/{TENANT_ID}/servers/{server_name}

Commonly available Work IQ MCP server names include:

• Mail: mcp_MailTools
• Calendar: mcp_CalendarTools
• Teams: mcp_TeamsTools
• OneDrive: mcp_OneDriveTools
• SharePoint: mcp_SharePointTools
• Word: mcp_WordTools
• User/Profile: mcp_MeTools
• Universal Search: mcp_M365Copilot (Preview)

4.1. Initialize the MCP Session

You must first initialize a session with the MCP server to negotiate capabilities and obtain an mcp-session-id.

const serverUrl = `https://agent365.svc.cloud.microsoft/agents/tenants/{TENANT_ID}/servers/mcp_MailTools`;

const initializeRes = await fetch(serverUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json, text/event-stream",
    Authorization: `Bearer ${accessToken}`, // The user's delegated token
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: "2024-11-05",
      capabilities: {},
      clientInfo: { name: "my-custom-agent", version: "1.0.0" },
    },
  }),
});

const sessionId = initializeRes.headers.get("mcp-session-id");

4.2. Invoke tools

Once initialized, you can invoke tools natively supported by the server.

const toolRes = await fetch(serverUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/json, text/event-stream",
    "mcp-session-id": sessionId, // Include the session ID returned during initialization
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 2,
    method: "tools/call",
    params: {
      name: "SearchMessagesQueryParameters",
      arguments: { queryParameters: "?$top=10" },
    },
  }),
});

const responseJson = await toolRes.json();
console.log(responseJson.result.content);

Your custom agent can now interpret the JSON-RPC tool response and synthesize it back to the user.

example.com

Deep Dive: Work IQ Copilot (mcp_M365Copilot)

While there are many dedicated MCP servers for specific workloads (like Mail or Calendar), the Work IQ Copilot server (mcp_M365Copilot) stands out as the primary mechanism for broad discovery and context retrieval.

This server is designed to search across your entire Microsoft 365 ecosystem—including SharePoint sites, OneDrive files, email messages, Teams chats, and other connected M365 content.

When to use Work IQ Copilot

You should invoke this tool for any user request that requires locating information contained within Microsoft 365 content when no workload-specific tool is available. It serves two main purposes:

1. Universal Search: If the user’s request could plausibly be answered using organizational content (e.g., “Find the project report from last week”), use this tool.
2. Fallback Mechanism: If a user requests information from a specific workload but that specific tool is unavailable, you should use Work IQ Copilot as a fallback to attempt retrieval. Tip: If the search tool can’t retrieve the information, your agent should clearly state that the information isn’t accessible rather than hallucinating from general knowledge.

The Copilot Chat Tool

The primary tool exposed by this server is Copilot Chat. It provides direct chat integration with M365 Copilot, supporting persistent multi-turn conversations and file grounding.

Required Parameters:

• message: The chat message text from the user to send to Copilot.

Optional Parameters:

• conversationId: The ID of an existing Microsoft 365 Copilot conversation. If provided, the tool continues the same thread (retaining multi-turn context). If missing, a new conversation is automatically created.
• agentId: The Agent ID for the Microsoft 365 Copilot conversation.
• fileUris: An array of file references (with URI properties from SharePoint, OneDrive, etc.) used to ground the response. This allows you to explicitly attach files as contextual resources.

Available Work IQ MCP Servers Reference

The following table summarizes the available Work IQ MCP servers and their typical use cases.

Note: Depending on your tenant region and release configuration (Targeted vs. Standard Release), some endpoints might be labelled as preview.