Work IQ MCP

Work IQ MCP, in one paragraph and then in three

One paragraph. Work IQ is the intelligence layer underneath Microsoft 365 Copilot. It builds a continuous, contextual understanding of how work happens across your tenant by unifying signals from files, emails, meetings, chats, and business systems. Work IQ MCP is the tool surface on top of that intelligence layer — a set of Model Context Protocol servers, hosted by Microsoft, that any MCP-aware agent can call to take real action against that work context.

Three paragraphs. The first thing to understand is that Work IQ MCP is not a single server. It is a curated catalog of nine workload-specific servers, each with a stable identifier (mcp_MailTools, mcp_CalendarTools, mcp_TeamsServer, and so on). Each server exposes a set of granular tools backed by Microsoft Graph endpoints, and each tool maps onto a specific OAuth scope (McpServers.Mail.All, McpServers.Teams.All, etc.). When your agent invokes a tool, the request flows through the Agent 365 tooling gateway, which is what gives Microsoft a consistent place to enforce policy, scan payloads, throttle usage, and emit telemetry.

The second thing to understand is the developer surface. Microsoft offers three ways in: Copilot Studio for low-code conversational agents, Azure AI Foundry for pro-code agents in the Foundry portal, and the Microsoft Agent 365 SDK (Python, .NET, JavaScript) for everything else — including agents you have already built on Agent Framework, OpenAI Agents SDK, Semantic Kernel, or LangChain. There is also a fourth path: Work IQ MCP servers can be added directly to coding tools like Claude Code, GitHub Copilot CLI, and VS Code via a standard MCP client config, which is how Microsoft is positioning it for individual developer productivity.

The third thing to understand is governance. Every Work IQ MCP server corresponds to a permission on the Agent 365 application object in Microsoft Entra. An agent only gets access to a server after an admin explicitly grants the corresponding permission. Admins can also block any server tenant-wide from the Microsoft 365 admin center, and every tool call — agent, tool, parameters, outcome — is queryable in Microsoft Defender Advanced Hunting. Block actions take precedence over configuration. This is the part that will matter most to your security team.

Three layers, one gateway

Microsoft describes Work IQ as a stack of three tightly integrated layers: Data, Context, and Skills & Tools. The visualization below maps these layers and shows where Work IQ MCP plugs in.

For a developer, the practically relevant box is the tooling gateway. It is the single chokepoint through which every MCP call passes, which is why Microsoft can promise things like centralized governance, real-time threat protection, and consistent observability without you having to wire any of it up.

The gateway also resolves a question that comes up the moment you start composing tools: how does the agent know who the user is? Two flows are supported. Agentic identity uses the agent's own Entra agent ID and acts as itself — ideal for autonomous, scheduled, or background work. On-Behalf-Of (OBO) exchanges a delegated user token so the agent acts as the signed-in user, with that user's permissions and audit trail. You will use both, often in the same agent. OBO is what makes "summarize my unread emails from this morning" work correctly when ten different employees say it.

What is actually in the box

This is the table to bookmark. It is a synthesis of the nine Work IQ MCP server reference pages on Microsoft Learn. Each row gives you the server ID you will use in your tooling manifest, the OAuth scope your admin needs to grant, and a working summary of capabilities.

The patterns that repeat across servers

Three patterns show up enough that they are worth internalizing before you start writing code against any individual server.

OData query parameters are everywhere. If you have used Microsoft Graph, you already know the dialect: $select to pick fields, $filter to constrain, $top to paginate, $expand for related entities, $orderby for sorting. Every server that lists or retrieves things accepts these — use them aggressively. $select in particular has a real impact on token cost in long-running agents, because what comes back is what gets shoved into your model context.

ETags for concurrency control. Update and delete operations across SharePoint, OneDrive, and Mail accept an optional etag (or If-Match) parameter. If your agent reads then modifies, you should round-trip the ETag — without it, you can race an interactive user editing the same item. The cost of doing this right is one parameter; the cost of not doing it is a stale-write data corruption bug that will be hard to reproduce.

Async operations return tokens. The SharePoint and OneDrive servers handle copy/move asynchronously. They return an operation token; you call checkOperationStatus to poll. Build your agent prompts to handle the "I started it, let me check on it" pattern, or wrap the polling in a helper. The 5MB file ceiling on these servers is also worth designing around — for anything larger, you are building a Graph passthrough, not using Work IQ.

The three (and a half) ways in

Microsoft has converged on a consistent integration story across surfaces, but the experience is meaningfully different depending on which one you pick. Choose based on where your agent already lives, not where Microsoft's marketing wants it to live.

For your two prioritized stacks — Python with the Agent 365 SDK targeting Foundry-style agents, and Copilot Studio for the broader org — the next two sections walk through what the actual integration looks like.

Wiring Work IQ into a Python agent

The Agent 365 SDK is built around a manifest-driven flow. You use the CLI to add servers; the CLI generates a ToolingManifest.json; an admin grants the corresponding permissions to the agent blueprint; at runtime your code reads the manifest and registers all the tools with whatever orchestrator you are using. The whole point is that you do not have to know per-server scopes, audiences, or endpoints — the CLI populates them for you.

Step 1 — Add servers via the CLI

From your project directory, list available servers and add the ones you want. This only updates the local manifest — it does not grant permissions yet.

# See everything available
a365 develop list-available

# Add the servers your agent needs
a365 develop add-mcp-servers mcp_MailTools
a365 develop add-mcp-servers mcp_CalendarTools
a365 develop add-mcp-servers mcp_MeServer
a365 develop add-mcp-servers mcp_M365Copilot

# Confirm what is configured
a365 develop list-configured

The generated ToolingManifest.json looks like this. Note that scope and audience are auto-populated from the MCP server catalog — you do not maintain these by hand.

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

Step 2 — Grant permissions to the agent blueprint

This is the step that always trips first-time setups. Adding to the manifest does not grant anything — a Global Administrator has to consent. Either run a365 setup all (first-time blueprint creation) or, if your blueprint already exists, a365 setup permissions mcp separately. Until this completes, the new server permissions will not be visible in the blueprint and your agent will get permission-denied errors at runtime.

Step 3 — Register the tools with your orchestrator

The Python SDK exposes a registration service per orchestration framework. The pattern is identical: import, instantiate, call add_tool_servers_to_agent. Pick the package that matches your orchestrator.

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import (
    mcp_tool_registration_service,
)

class MyAgent:
    def __init__(self):
        self.config_service = McpToolServerConfigurationService()
        self.tool_service = (
            mcp_tool_registration_service.McpToolRegistrationService()
        )

    async def setup_mcp_servers(self, auth, context):
        """Register every server in ToolingManifest.json with the agent."""
        use_agentic_auth = (
            os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        )

        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            # On-Behalf-Of: agent acts as the signed-in user
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

For Microsoft Agent Framework, swap the import to microsoft.agents.a365.tooling.extensions.agentframework. For Azure AI Foundry, use ...extensions.azureaifoundry. For Semantic Kernel, ...extensions.semantickernel. The signature is consistent across all of them, so you can switch orchestrators without rewriting your tool-registration code.

The Python package map

Worth pinning these in requirements.txt early. The Agent 365 SDK is split into a core tooling package plus per-framework extensions plus per-framework observability extensions.

Foundry, in case you want the portal-driven path

Foundry covers the same servers from the other direction. Create an agent at ai.azure.com, configure a model (GPT-4o is the default suggestion), then in the Tools section browse the catalog filtered by Provider > Microsoft. The Microsoft 365 Frontier tools (User Profile, Outlook Calendar, Copilot Search) appear as connectable resources. Connect with default endpoint and auth, test in the Chat Playground — you will be prompted to approve each tool call interactively.

The low-code path, in nine clicks

For agents that live in Copilot Studio — especially the ones owned by business teams — adding a Work IQ MCP server is a Tools-tab operation. Sign in to Copilot Studio, open or create your agent, then:

1. Tools tab → Add Tool.
2. On the Add tool page, choose Model Context Protocol.
3. Search for the server you want (e.g. type mail).
4. Pick Work IQ Mail, expand the connection dropdown, choose Create New Connection.
5. Sign in with your credentials.
6. Select Add and Configure.
7. In Test Copilot, type a prompt that needs the tool: "Send an email to alex@contoso.com asking how the lab is going."
8. Approve the connection request when prompted.
9. Repeat for every additional Work IQ server you want.

For agents using generative mode on top of M365 services, the agent must have an Exchange license — this is a common gotcha. The prebuilt Work IQ tools you see in Copilot Studio already have the necessary permissions consented for your org and role, which is why the experience feels frictionless. If you build a custom MCP server, expect to do the consent step explicitly.

When the catalog runs out

You will hit the edges of the prebuilt catalog. Maybe you need a tool that wraps your ticketing system, or your domain-specific Dataverse custom API, or an internal REST service. The MCP Management Server is Microsoft's API-first answer.

It is itself an MCP server — you talk to it from Visual Studio Code (or any MCP client) and use its tools to create new servers and tools programmatically. Five core tools are exposed:

To connect from VS Code, add an HTTP MCP server pointing at https://agent365.svc.cloud.microsoft/mcp/environments/{environmentId}/servers/MCPManagement, name it MCPManagement, choose Global scope, sign in. From there you compose new servers conversationally or via direct API calls.

The tradeoff to weigh: a custom server gives you exact-fit tools and brings them under the same gateway / Defender / admin-center governance umbrella as the prebuilt ones. The cost is the build, the publish ceremony, and the ongoing maintenance. For one or two domain-specific actions, OpenAPI plugins via Copilot actions may be the lighter path. For anything that resembles a stable, multi-tool surface (a CRM, a scheduling system, an internal knowledge base), the MCP Management Server is the right home.

What your security team will ask, and what to tell them

This is where Work IQ MCP earns its enterprise framing. The same things that make agent platforms hard to ship in regulated environments — opaque permissions, no audit trail, no kill switch, no tenant boundary — are all addressed by design.

Admin control via the M365 admin center

IT admins manage every Work IQ MCP server (and any custom server) from the Microsoft 365 admin center under Agents and Tools. They can view what is activated, allow or block specific servers, and apply scoped permissions per agent. Block actions take precedence over configuration — if a server is blocked, no agent in the tenant can use it, regardless of what manifest the agent ships with.

One thing to flag: the ability to allow or disallow servers in the admin center may not be available in your region yet during preview. Worth checking before you commit a roadmap to it.

Permission model

Each MCP server corresponds to a permission on the Agent 365 application object in Microsoft Entra. When an agent is onboarded, the admin grants the required permissions to the agent's blueprint. The agent only gains access to a server after consent. Permissions live at three levels: blueprint-wide defaults, agent-instance specifics, and per-agent-user overrides for OBO scenarios.

Observability via Microsoft Defender

Every tool call — agent identity, tool name, parameters, outcome — is queryable in Microsoft Defender's Advanced Hunting. This is the audit trail your compliance team wants. It is also the operational tool you will use to debug "why did my agent call delete-message at 3 a.m." production incidents. The fact that it is the same query surface security uses is a real advantage.

Runtime enforcement

The tooling gateway enforces rate limits, payload size and content scans, and security policies at every hop. You do not configure these per agent — they are part of the gateway. For agents handling user data at scale, this matters: it means a poorly written agent cannot accidentally exfiltrate a SharePoint library because the gateway will throttle and scan before any tool even runs.

Identity integration

Agents in Agent 365 have first-class identities — an agent blueprint, agent instance, and agent user (a specialized user subtype that can be licensed, mailbox-enabled, mentioned in Teams, and managed by conditional access). They appear in the org chart. They have UPNs. They cannot have passwords or MFA factors, which means you control them through conditional access policies and group membership rather than credential management. For the Defender / Purview / Entra story, this is what makes it coherent.

What you need before any of this works

The licensing and setup gates are real. Worth knowing them before you commit a sprint.

Licensing

You must have a Microsoft 365 Copilot license to use Work IQ MCP servers. This is non-negotiable per Microsoft's documentation, and it is per-user. Agents that need their own mailboxes, OneDrives, Teams presence, etc. need agent users with appropriate licenses (typically Microsoft 365 E5, Teams Enterprise, plus Copilot). Resource provisioning for an agent user (mailbox, OneDrive) usually completes in 10–15 minutes after license assignment but can take up to 24 hours.

Identity setup

Decide between agentic identity and OBO. Many real agents use both. For agentic identity, complete the agent registration process to create the Entra agent ID and agent user. For OBO, no agent user identity is required — the agent exchanges a delegated user token at runtime.

Service principal setup

One-time per tenant, requires Global Admin. Microsoft ships a PowerShell script: New-Agent365ToolsServicePrincipalProdPublic.ps1. Run it once, sign in with admin creds, you are done.

Tooling

Agent 365 CLI installed and configured. .NET 8.0 SDK or higher (even for Python projects — the CLI requires it). Global Administrator privileges for the consent steps.

For coding-tool integration (Claude Code, Copilot CLI, VS Code)

Register an enterprise application in Microsoft Entra. Add API permissions corresponding to each Work IQ server you want to use (e.g. WorkIQ-MailServer). Add a redirect URI: http://localhost:8080/callback works, as do several other localhost variants. Then use a .mcp.json (or mcp.json for VS Code) pointing at https://agent365.svc.cloud.microsoft/agents/tenants/{tenantId}/servers/{serverName} with your client ID.

{
  "mcpServers": {
    "WorkIQ-MailServer": {
      "type": "http",
      "url": "https://agent365.svc.cloud.microsoft/agents/tenants/{tenantId}/servers/mcp_MailTools",
      "oauth": {
        "clientId": "{your-app-client-id}",
        "callbackPort": 8080
      }
    }
  }
}

Should we adopt this

The honest answer depends on three things: your existing Microsoft 365 footprint, whether you have already invested in a competing agent stack, and how much value you place on having governance solved.

Strong signal to adopt: you are already on M365 + Copilot, you have agents on Foundry / Copilot Studio / Agent Framework / Semantic Kernel, and your security team blocks projects that lack tenant-scoped audit logging. Work IQ MCP gives you 90% of what you would otherwise build over a quarter, and the governance story is the closest thing to "ready out of the box" that exists in the agent space right now.

Weak signal to adopt: your agents do not need Microsoft 365 context (no Mail, Calendar, Teams, SharePoint surfaces in their workflows), or you have a strong investment in a non-Microsoft agent platform that already has its own connectors. The Copilot license requirement makes the entry cost real; if you are not getting Copilot benefit, paying for a Copilot license to unlock Work IQ MCP is hard to justify.

Wait-and-see signal: you are early in agent adoption and your priority is one or two narrow workflows. Microsoft's MCP-server-as-a-tool-shape is a useful idea regardless of whether you adopt the Work IQ catalog — building your own MCP servers, exposing them to Copilot Studio or to a generic MCP client like Claude Code, is a reasonable middle path. You do not have to be all-in on Agent 365 to benefit from MCP as a pattern.

Suggested first project

If you do adopt it, start with a low-stakes, high-volume internal workflow that touches three Work IQ servers: User, Calendar, and Mail. A meeting-prep agent (looks up the next meeting, fetches the attendees' profiles, summarizes recent email threads with each, drops the brief into your inbox) exercises the gateway, the OBO flow, multi-server composition, and gives a tangible deliverable everyone can feel. From there, expand into SharePoint and Word for document workflows, then Teams for routing.

What to watch

The unified remote Work IQ MCP server. Microsoft has flagged that the current per-workload catalog will eventually be consolidated into a single server with a curated tool set, simplifying configuration. When that ships, expect to refactor your manifest. The promise of stable scenarios but unstable schemas is real — build your tool wrappers, do not hard-code tool IDs in prompts.

Also watch the regional rollout of admin-center governance, the per-developer publish flow for custom MCP servers (currently tenant-admin only), and pricing / licensing as the preview moves toward GA. None of these are blockers; all of them affect timing.

Where this came from

Every claim above is grounded in Microsoft Learn documentation. The pages below are the working set — the overview, every Work IQ MCP server reference, the developer integration docs, and the Agent 365 SDK package list.

• Work IQ MCP overview (preview) — Microsoft Agent 365
• Work IQ overview — Microsoft 365 Copilot extensibility
• Use Work IQ MCP in Copilot Studio
• Work IQ Copilot reference
• Work IQ Calendar reference
• Work IQ Mail reference
• Work IQ Teams reference
• Work IQ SharePoint reference
• Work IQ OneDrive reference
• Work IQ User reference
• Work IQ Word reference
• Dataverse MCP Server reference
• Add and manage tools — Agent 365 Developer Guide
• Agent 365 Identity — authentication flows
• Microsoft Agent 365 SDK Overview
• Connect existing agents to Microsoft Agent 365
• Work IQ API overview (preview)
• Microsoft Agent 365 Samples (GitHub)