Merge Unified's OneDrive integration Merge Agent Handler's OneDrive MCP server

Connect your AI Agents to OneDrive in minutes

Merge lets you securely connect your agents to OneDrive and thousands of tools instantly

Start building for free

Read docs

OneDrive

Learn more about Merge Agent Handler

Available tools

get_file_activity

Get activity history for files and folders. To page, pass the nextLink from the previous response back as nextlink; when nextlink is set, item_id/top are ignored (the scope and page size are fixed by the original request).

search_items_advanced

Search OneDrive with filters: file types, content category, modified/created, date ranges, size range, modified-by-me, and folder scoping.

get_my_drive

Get the user's default OneDrive

get_drive

Get information about a specific drive by ID

list_my_drives

List all drives available to the user

get_root_folder

Get the root folder of a drive

get_special_folder

Get a special folder (Documents, Photos, etc.)

get_drive_usage

Get storage usage information for a drive

get_drive_owner

Get owner information for a drive

get_item

Get a drive item by ID or path

list_items

List children of a folder. To page, pass the nextLink from the previous response back as nextlink; when nextlink is set, itemid/top/orderby/filterquery are ignored (page size, order, and filter are fixed by the original request).

create_folder

Create a new folder

upload_file

Upload a file to OneDrive. Provide the bytes as base64 in content, up to 4 MB, or a filereference from the file upload API (POST /api/v1/files/) for larger files, which stream into OneDrive without entering the model's context. Target the folder with parentid, or give path as the file's full destination path. Use conflict_behavior to rename, replace or fail on a name collision.

download_item

Download file content from OneDrive as base64. Set returndownloadurl=true for a short-lived download URL instead, which handles larger files.

update_item

Update item metadata

move_item

Move an item to a different folder

copy_item

Copy an item to a different location

delete_item

Delete an item from OneDrive

search_items

Simple free-text search for items in OneDrive by name/content. For filtering by file type, date, size, or folder, use searchitemsadvanced instead.

list_permissions

List permissions for an item

get_permission

Get a specific permission by ID

create_sharing_link

Create a sharing link for an item

grant_permission

Grant permissions to recipients for an item

update_permission

Update roles for a user/group permission

delete_permission

Remove a permission from an item

access_shared_item

Access a shared item using sharing URL

get_sharing_link

Get sharing link information for an item

check_item_sharing_status

Check sharing status of an item

get_thumbnails

Get all available thumbnails for an item

get_thumbnail

Get a specific thumbnail size for an item

get_preview

Generate a preview link for an item

check_thumbnail_availability

Check if thumbnails are available for an item

get_thumbnail_urls

Get thumbnail URLs for an item

validate_credential

Validate OneDrive credentials. Verifies credentials during setup.

list_item_versions

List all versions of a file

get_item_version

Get details of a specific version

restore_item_version

Restore a previous version of a file

compare_item_versions

Compare two versions of a file

list_deleted_items

List items in the recycle bin. NOTE: Microsoft Graph has no documented v1.0 endpoint for this, so this tool always returns success=False with an error explaining the limitation rather than data.

restore_deleted_item

Restore an item from the recycle bin

get_version_download_url

Get download URL for a specific version of a file

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's OneDrive MCP server

How can I use the OneDrive MCP server?

Here are just a few popular use cases:

External sharing governance: Your agent can monitor files shared via external links, automatically enforce expiration dates on sensitive documents, revoke access after project completion, and alert security teams when confidential files are shared with non-approved domains

Meeting preparation automation: Your agent can scan upcoming calendar events, identify relevant OneDrive files based on meeting topics and attendees, compile them into a briefing folder, and share pre-read materials with participants 24 hours before meetings

Collaborative conflict prevention: Your agent can detect when multiple users are editing the same file simultaneously, notify editors of potential conflicts, suggest lock mechanisms for critical sections, and automatically merge non-conflicting changes while flagging areas needing manual review

License optimization: Your agent can analyze storage usage and file access patterns across your organization, identify users with large storage footprints but minimal activity, recommend appropriate license tier adjustments, and generate cost-saving reports for IT administrators

Cross-platform documentation sync: Your agent can monitor OneDrive files that are referenced in project management tools or wikis, automatically update linked documents when source files change, and maintain a changelog of cross-platform dependencies to prevent broken references

What are popular tools for OneDrive’s MCP server?

Here are some popular tools across resource types:

Drives

<code class="blog_inline-code">list_my_drives</code>
<code class="blog_inline-code">get_my_drive</code>
<code class="blog_inline-code">get_drive_usage</code>
<code class="blog_inline-code">get_drive_owner</code>

Items

<code class="blog_inline-code">search_items</code>
<code class="blog_inline-code">download_item</code>
<code class="blog_inline-code">move_item</code>
<code class="blog_inline-code">update_item</code>

Permissions

<code class="blog_inline-code">grant_permission</code>
<code class="blog_inline-code">update_permission</code>
<code class="blog_inline-code">get_permission</code>
<code class="blog_inline-code">delete_permission</code>

What makes Merge Agent Handler’s OneDrive MCP server better than alternative OneDrive MCP servers?

Merge Agent Handler provides platform-level capabilities that go beyond a standalone MCP server:

Enterprise-grade security and DLP: All OneDrive tool inputs and outputs pass through a security gateway that can block, redact, or mask sensitive data using default or custom rules. This helps prevent data leakage without requiring manual review

Authentication handled end-to-end: Merge supports guided authentication flows, credential management, and both individual and shared authentication models for MCP connectors like OneDrive. This removes the need to build and maintain auth logic yourself

Real-time observability and auditability: Every OneDrive tool call is logged with full context, enabling real-time monitoring, debugging, and a complete audit trail. Logs are also fully-searchable, making it easier to review and manage agent behavior over time

Tool Pack management at scale: OneDrive tools can be bundled with other connectors into Tool Packs and dynamically loaded per agent or use case, allowing fine-grained control over what your agents can access

Can I set custom security rules for OneDrive tool calls in Merge Agent Handler?

Yes, you can set a wide range of custom security rules. Here are just a few examples:

Passport and national ID numbers: Block any <code class="blog_inline-code">upload_file</code> or <code class="blog_inline-code">update_file_content</code> tool calls that contain passport numbers, driver's license IDs, or national identification numbers in OneDrive documents before they're synced to the cloud

Medical record numbers: Redact protected health information (PHI) including medical record numbers, diagnosis codes, and patient identifiers when agents retrieve documents via <code class="blog_inline-code">read_file_content</code> or <code class="blog_inline-code">download_file</code> from OneDrive health compliance folders

IP addresses and network credentials: Prevent agents from creating or updating OneDrive files that contain internal IP addresses, VPN credentials, firewall configurations, or network topology diagrams that could expose infrastructure vulnerabilities

Customer PII bundles: Mask combinations of customer data (street addresses, dates of birth, account numbers) when agents search or retrieve files via <code class="blog_inline-code">search_files</code> or <code class="blog_inline-code">list_folder_contents</code>, showing only tokenized references (e.g., CUST-***-4892)

Proprietary source code: Block <code class="blog_inline-code">move_file</code> or <code class="blog_inline-code">copy_file</code> tool calls that attempt to transfer files containing proprietary code, trade secrets, or confidential algorithms from secured team folders to personal OneDrive directories

Time-based access restrictions: Prevent <code class="blog_inline-code">download_file</code> or <code class="blog_inline-code">get_file_metadata</code> operations on files tagged as "highly confidential" during off-hours (e.g., 6 PM - 8 AM) or on weekends, ensuring sensitive document access only occurs during business hours

How can I start using Merge Agent Handler’s OneDrive MCP server?

Here are the steps to start using Merge Agent Handler's OneDrive MCP server:

1. Sign up for Agent Handler. You can create a free Merge Agent Handler account here.

2. Create a Tool Pack (a collection of connectors your agent can access). In the dashboard, go to Tool Packs, click "Create New Tool Pack," and select the OneDrive connector from the available connectors. You can also name your Tool Pack (e.g., "OneDrive Access Pack").

3. Create a Registered User (an identity that executes actions on behalf of your agent). Navigate to the Registered Users section in the dashboard and click "Create Registered User."

You'll need to provide:

Origin User ID: A unique identifier for this user in your system (e.g., a UUID)
Origin User Name: A human-readable name (e.g., "John Smith")
(Optional) Shared Credential Group: If multiple users should share the same credentials, you can group them together

Agent Handler will return a Registered User ID that you'll use in step 4.

4. Collect your configuration details. You'll need three pieces of information:

Tool Pack ID: Found in your Tool Pack's URL or settings
Registered User ID: Found in the Registered Users section
API Key: Generate this from your Agent Handler account settings (typically starts with a prefix like "cx-")

5. Configure your IDE or AI platform. Add the MCP server configuration to your development environment (Cursor, Claude Desktop, Windsurf, VS Code, etc.) using the Tool Pack ID, Registered User ID, and API Key

6. Verify the connection. Open your AI assistant or agent interface. You should see the OneDrive tools available in the tools/context menu

7. Start using OneDrive tools. Test with prompts like "List my recent OneDrive files" or "Create a new folder in OneDrive called Project Documents."