OneDrive MCP vs OneDrive API - What’s best for building AI Agents

TL;DR

• The official OneDrive MCP server i.e., Microsoft's "Work IQ OneDrive" (OneDrive Remote MCP server) is in preview, ships roughly 17 file and folder tools, and caps every file operation at 5 MB. Large-file uploads, change notifications, delta sync, and version or permission enumeration are Graph-API-only.
• The MCP server is not a standalone developer endpoint. It lives inside Microsoft Agent 365 and Copilot Studio, requires a Microsoft 365 Copilot license, and is governed from the Microsoft 365 admin center. There is no simple per-app OAuth redirect, and no headless option.
• The Microsoft Graph API supports delegated OAuth (^{Authorization Code} with PKCE), app-only ^{Client Credentials} for OneDrive for Business, and on-behalf-of delegation. It is the only path that runs without a user present.
• For multi-tenant B2B agents, both paths produce one credential per user per tenant. Neither stores, refreshes, or revokes those credentials for you. That is infrastructure regardless of which path you pick.
• Scalekit's OneDrive connector vaults the per-user token, refreshes it, revokes it on disconnect, and logs every call, so the MCP vs API decision does not change your auth infrastructure.

Your document agent needs to read and write OneDrive. Microsoft ships both an official OneDrive MCP server and the full Microsoft Graph file API. They are not the same object: different capability coverage, different auth model, and different operational surface in production. The choice also depends on what your agent is: an assistant that a licensed user talks to, or a background job running without anyone present. Here is how to pick.

What's OneDrive MCP

The official OneDrive MCP server is Microsoft's Work IQ OneDrive server, also referenced as the OneDrive Remote MCP server in Microsoft's official MCP catalog. It is a remote, Microsoft-hosted server exposed through the Agent 365 tooling gateway. It went into public preview in 2026 and remains preview at the time of writing; Microsoft warns that tool names and parameters can change, so avoid hard-coded dependencies.

• Access is user-scoped and mediated by Agent 365.
• An administrator activates or blocks the server in the Microsoft 365 admin center, grants the agent the required permissions, and the agent gains access only after that consent.
• A Microsoft 365 Copilot license is required.
• Every file operation is limited to 5 MB.

What's OneDrive API

The OneDrive API is Microsoft Graph. Files surface as driveItem resources inside a drive, addressed either by item ID (/me/drive/items/{id}) or by path (/me/drive/root:/path). The same driveItem surface covers personal OneDrive, OneDrive for Business, and SharePoint document libraries.

Authentication runs on OAuth 2.0 through Microsoft Entra ID. Graph accepts delegated tokens for user-present flows and app-only tokens for service-to-service flows, with scopes such as Files.ReadWrite and Files.ReadWrite.All declared at app registration.

What your agent can actually do with OneDrive MCP Server vs API

The MCP server covers record-level file work well: browse, search, read, write, share, copy, move, and apply sensitivity labels, all on the authenticated user's personal OneDrive. The gaps appear the moment your agent needs scale, change tracking, or organizational breadth.

The most consequential gaps are the 5 MB cap and the lack of an event surface. A 5 MB ceiling rules out most real documents and media. For change-driven agents, the API supports change-notification subscriptions on the drive root; note that driveItem notifications return null resource data, so you pair the subscription with a delta query to learn what actually changed. The MCP server has no subscription surface at all.

The auth path each one puts you on: OneDrive MCP Server vs API

The MCP path is the constraint that decides most B2B builds.

• Access is user-scoped and governed by the Agent 365 control plane, not by an OAuth client you register and point an agent at.
• The agent runs inside Copilot Studio or Agent 365, the org needs Microsoft 365 Copilot licensing, and an administrator must grant the server's permissions.
• There is no app-only mode and no background path.

The Graph API has no such constraint. It accepts three identity patterns:

• Delegated OAuth (^{Authorization Code} with PKCE, RFC 6749): the agent acts as a specific user with that user's exact permissions. Required for multi-user B2B products where each user's agent sees only their own files.
• App-only (^{Client Credentials}, RFC 6749): the application authenticates with its own credential, no user in the loop. Available for OneDrive for Business and SharePoint in an Entra tenant; consumer personal OneDrive is delegated-only.
• On-behalf-of delegation for chained services that need a scoped downstream token.

For a multi-tenant agent serving many users across several customer tenants, the delegated path gives you the correct model: one token per user, scoped to that user's drive. What it does not give you is a place to store, rotate, and revoke those tokens. That is true on the MCP path too, where the per-user identity is real but the credential lifecycle is still yours to operate.

What you own in production

On the MCP path,

• Microsoft owns hosting, scaling, schema maintenance, and permission enforcement.
• You own the Microsoft 365 Copilot licensing dependency, the admin-governance workflow, and the preview risk: tool names and parameters may shift, so anything you hard-code can break on an upstream update.
• Observability is available through the Microsoft Defender portal's advanced hunting, where tool-call traces are queryable.

On the API path,

• You own the full stack: endpoint selection, throttling behavior, upload-session orchestration, and delta cursors.
• Graph throttles rather than exposing a single daily quota; expect HTTP 429 responses with a ^Retry-After header and build backoff accordingly.
• You also pin a Graph version (^v1.0 versus ^beta) and migrate on your own schedule, which matters for deterministic pipelines where an unplanned schema change is an incident.

When to use MCP, when to use the API

Use OneDrive MCP when:

• Your agent is user-facing and lives inside Copilot Studio or Agent 365, with a Microsoft 365 Copilot license in place.
• The work is record-level file interaction under 5 MB: browse, search, read, write, share.
• You want Microsoft's admin-center governance and Defender-based audit without building your own controls.
• You are prototyping a Copilot-licensed scenario and do not want to write Graph adapter code.

Use the OneDrive API directly when:

• Your agent runs headless: scheduled syncs, background processors, event-driven jobs with no user present.
• You handle large files, need ^{createUploadSession}, or move beyond the 5 MB cap.
• You react to changes through change notifications and ^delta, or reach SharePoint document libraries at scale.
• You are building a standalone agent (LangChain, a custom loop, your own framework) that is not bound to Agent 365 or Copilot licensing.

The credential problem that exists on both paths

Both paths hand you a credential per user. Neither hands you a vault, refresh logic, or a revocation flow.

In a multi-tenant B2B agent, which is the norm, every user has their own OneDrive credential: fifty customers means fifty token lifecycles to store encrypted, isolate per tenant, and revoke on disconnect.

The token type differs by path; the infrastructure required does not. A Microsoft Entra token can be revoked by the user or an admin at any time, and your agent has no built-in way to know until a call fails. Detecting that, then refreshing or re-prompting cleanly rather than failing silently, is work that sits underneath both the MCP server and the Graph API.

Scalekit's OneDrive connector handles the OAuth flow, per-user token storage, and refresh for both paths, so the MCP vs API decision does not change what you build for auth.

Building on OneDrive with Scalekit

The Token Vault and per-user identity

Scalekit's OneDrive connector resolves the authorizing user's credential on every call. The token lives in an AES-256 vault, namespaced per tenant, fetched server-side at request time, and never placed in your agent runtime or the LLM context.

Refresh is automatic; revocation is a single dashboard action. The principle the model enforces is simple: what the user can't do, the agent can't do.

Tools the connector exposes

The connector ships LLM-ready tools tested against Microsoft Graph, so the team builds the agent, not the tooling. The current OneDrive surface includes:

• ^{onedrive_files_list}: list files in a folder or the root.
• ^{onedrive_file_get}: retrieve file metadata, including name, size, author, and modified date.
• ^{onedrive_file_download}: download content, or export Office files to ^pdf, ^xlsx, or ^docx.
• ^{onedrive_files_search}: search files by name or content.
• ^{onedrive_file_share}: create a sharing link with a permission level.
• ^{onedrive_folder_create}: create a folder.

Resolve the live set at runtime with listScopedTools rather than hard-coding it; the call returns only the tools the current user's connected account is authorized to call, which is a scoped, deterministic surface rather than a full catalog.

Connect it from your framework

The example below wires the connector into a LangChain agent with the Node SDK. The connectionName passed to listScopedTools must match the connection name configured in your Scalekit dashboard exactly; a mismatch here is the most common integration error.

Scope the surface with a Virtual MCP Server

If you would rather hand any MCP-compatible agent a pre-authenticated endpoint than write a tool loop, Scalekit's Virtual MCP Server gives every agent a scoped, user-specific MCP endpoint with no server to deploy, host, or maintain. You create one config per agent role and whitelist exactly the tools it can see; the agent sees only what you allow, not everything the connector exposes.

One server definition serves all users. Before each run, a short-lived session token is minted, scoped to that user's connected account, so there is no credential sharing between users and no per-user server configuration. The endpoint is static; the identity is per-user. A generated server URL looks like:

https://yourcompany.scalekit.com/mcp/v3/servers/<server-id>

Recommended: Configure a virtual MCP server, and explore a full Claude managed agent walkthrough.

Observability for multi-tool, multi-tenant agents

Every OneDrive tool call is logged: who triggered it, which item was touched, and what came back, with history tied to the user who authorized it. For an agent that spans OneDrive plus several other connectors across many tenants, that per-user attribution is what makes audit and debugging tractable; a shared service account collapses every call into one identity and breaks attribution. Scalekit keeps the real user on every log line.

When a tool is missing

The connector covers the common document workflows, but it will not have every Graph operation you might want on day one. If a tool you need is missing, request it: join the Scalekit community on Slack, or talk to the team.

Which one to build against

• If your agent is user-facing, runs inside Copilot Studio or Agent 365, and your org carries Microsoft 365 Copilot licensing, the official OneDrive MCP server is a legitimate path for record-level file work under 5 MB, with Microsoft's governance built in.
• If your agent runs headless, handles large files, reacts to changes, reaches SharePoint at scale, or is a standalone build outside Agent 365, use the Microsoft Graph API directly; the preview status, the 5 MB cap, and the Copilot license requirement are genuine constraints, not configuration options.

Either way, every user still has their own credential, and that credential lifecycle is what needs production-grade infrastructure.

Browse the Scalekit OneDrive connector and the Scalekit OneDrive Connector docs.