How to connect an Outlook MCP to Cursor (4 steps)

Microsoft Graph's message and event API resources aren't simple.

A message splits body content across body and bodyPreview, attachments come back as a separate base64-encoded resource, and events represent time as separate start and end objects. Writing a parser, handling attachments, or building scheduling logic all mean checking the real response first, not guessing from the docs.

That means leaving the editor for Graph Explorer or a scratch script and carrying the answer back in a browser tab.

To help your developers query Outlook data without leaving Cursor, we'll show you how to connect Outlook with Merge Agent Handler's Outlook MCP server.

How it works

Merge Agent Handler connects Cursor to Microsoft Graph's Outlook API through the Merge CLI.

You install the CLI, authenticate once, and run a single setup command from your project root. That command writes a ## Merge CLI section to your project's .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach Outlook.

Merge will then manage your Microsoft Graph OAuth token storage and refresh on your behalf, so no credential state lives in your local environment.

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Microsoft 365 or Outlook.com account with access to the mailbox and calendar you want to connect

If you want to connect Merge Agent Handler's Outlook MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Add the Merge CLI to your environment with pipx: pipx install merge-api

Confirm the installation succeeded: merge --version

Related: How to use the Outlook MCP in Claude Code

2. Log in to Merge

Connect the CLI to your Merge Agent Handler account: merge login

This links the CLI to your account so Merge can make authorized requests against Outlook on your behalf.

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools:

merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent, so it's safe to re-run if you need to reset.

4. Authenticate Outlook

Open a Cursor chat in your project and try a prompt such as:

Fetch a real message from my inbox and show me the full response, including the body, bodyPreview, and attachment references, so I can write the parser correctly.

The first time you invoke an Outlook tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

Outlook MCP FAQ

In case you have more questions on setting up and using the Outlook MCP in Cursor, we've addressed several more commonly-asked questions below.

What can you do once the Outlook MCP is connected to Cursor?

With Outlook connected, Cursor can:

• Inspect the real message resource before writing a parser: fetch a message to see how body content splits across body and bodyPreview, and how attachments are referenced, so your deserialization matches the actual Graph response

• Resolve real folder IDs behind well-known names: pull the folder list to see the actual IDs behind names like Inbox or Sent Items, so you don't hardcode assumptions that break on a shared mailbox

• Check the event resource's time zone structure before writing scheduling logic: fetch a real calendar event to see how Graph represents start, end, and time zone fields before you write code that creates or compares events

• Inspect the attachment resource before writing download logic: fetch a message's attachments to see the content type and base64 encoding fields before you write the code that processes them

• Validate delta query behavior on a real mailbox: run a query that returns many messages or events to see how @odata.nextLink and delta tokens behave before implementing a sync loop

• Check a free/busy response before writing availability logic: pull a real schedule query to see how busy, free, and tentative blocks come back before you write the code that reads them

Why use Merge Agent Handler vs. a self-hosted Outlook MCP server?

You can self-host an MCP server that wraps Microsoft Graph's mail and calendar APIs directly. For a solo developer working against their own mailbox, that setup works: register an app in Azure AD, request the Graph scopes you need, and manage the token yourself.

The overhead compounds at the team level.

Microsoft Graph app registrations typically need tenant admin consent, and every developer who wants Outlook access through Cursor either shares that registration or goes through the same approval separately. There's no built-in way to scope which mailboxes, folders, or operations a given agent can reach, and token refresh across multiple developers becomes a manual coordination problem.

Merge Agent Handler centralizes the Microsoft Graph connection and adds a control layer on top.

You define which Outlook operations each agent is allowed to call, Merge enforces those boundaries, and every tool call is logged with a full audit trail that includes the input and output.

Why connect Outlook to Cursor?

Developers writing Outlook integrations have to understand Microsoft Graph's data model before the code will work: a message that splits body content across two fields, attachments that live behind a separate resource, and calendar events that represent time as structured objects rather than plain strings.

That structure is documented, but reading about it isn't the same as seeing a real message or event from the mailbox your integration will run against.

With the Outlook MCP connected, Cursor can pull real Outlook data directly in the chat panel.

You can fetch a message while writing the parser that will process it, check an event's time zone fields while writing the scheduling logic that depends on them, or resolve real folder IDs while writing the query that filters by folder.

Can I use Merge Agent Handler's Outlook MCP with my employees?

Yes, Agent Handler for Workforce is built to help organizations provision, secure, and govern how employees connect AI tools like Cursor to systems like Outlook.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which mailboxes and calendars an employee's agent can reach by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return sensitive email content or attachments before results reach the editor session

• User-level audit logging so security and IT teams can review which messages were read or sent, and which calendar events were viewed or created, by which employee identity, and when

Put together, employees can use the Outlook MCP to write integrations grounded in real message and event structures, build sync logic tied to actual delta query behavior, and validate scheduling code against real time zone data, while IT keeps centralized control over which mailboxes and calendars each agent can reach.