Notion MCP vs Notion API for AI Agents

TL;DR

• Notion's hosted MCP server ships 18 tools covering search, page CRUD, database creation, comments, and user management. Block-level editing, file access, webhooks, and advanced data source querying are absent from the MCP surface.
• MCP auth is OAuth-only. The Notion API supports three bearer token types: internal integration tokens, OAuth access tokens from public connections, and personal access tokens (PATs). Which one your agent can use depends on whether it runs interactively or headlessly.
• The hosted MCP is not designed for headless agents. It requires a browser-based OAuth flow to authenticate. Background agents running without a user present cannot complete that flow.
• For multi-tenant B2B agents, both paths give you one credential per user. Neither path manages storage, refresh, or revocation for you. That remains an infrastructure problem regardless of which path you choose.
• Scalekit's Notion connector handles OAuth, token storage, and rotation for both paths, so the MCP vs API decision doesn't change your auth infrastructure.

Your agent needs to read and write Notion. Notion ships both a hosted MCP server at ^{mcp.notion.com} and a full REST API at ^{api.notion.com}. They're not the same thing: different capability coverage, different auth paths, different operational surface area in production. The choice also isn't permanent: what your agent needs determines which path fits. Here's the decision framework.

What Notion MCP and Notion API actually are

Notion MCP

Notion's hosted MCP server launched in 2025 and reached general availability at ^{mcp.notion.com/mcp}. It is built and maintained by Notion directly and is where Notion is investing its MCP development effort. Authentication is OAuth-only; agents connect via a browser-based OAuth consent flow, after which the MCP server holds the session and routes tool calls against the Notion API on the agent's behalf.

A local open-source server (^{github.com/makenotion/notion-mcp-server}) also exists, shipping 22 tools and supporting integration token auth instead of OAuth. Notion has soft-deprecated this server and is directing developers to the hosted version. For new agent builds, the hosted server is the relevant object.

Official docs: ^{developers.notion.com/guides/mcp/overview}

Notion API

The Notion REST API is versioned by date (^{api.notion.com/v1/...}), with the current version being ^2026-03-11. It exposes the full surface of a Notion workspace: pages, blocks, databases (now called data sources as of the ^2025-09-03 version), users, comments, search, and webhooks. Authentication accepts any bearer token: internal integration tokens, OAuth access tokens, or PATs, passed in the ^{Authorization} header.

Official docs: ^{developers.notion.com/reference/intro}

Comparing them where it matters for agents

What your agent can actually do

The hosted MCP covers most of what an agent needs for knowledge management: searching across the workspace, reading and creating pages, managing database schemas and views, handling comments, and resolving users. It is well-suited to the tasks that make up 80% of practical Notion agent workflows.

The gaps become visible when an agent needs more surgical control over content or needs to react to changes:

The most consequential gap for agent builders is block-level editing. The hosted MCP's ^{notion-update-page} tool replaces content at the page level; it loads the entire page, modifies it, and writes the whole thing back. The Notion API lets you retrieve specific block children and update individual blocks. For agents making targeted edits to long documents, the MCP approach loads substantially more content into context per operation and carries the risk of overwriting concurrent changes elsewhere in the document.

The second gap worth naming: webhooks. If your agent needs to react to changes in Notion, whether a page updated, a database property changed, or a comment added, that requires the API. The MCP server has no event subscription surface.

The auth path each one puts you on

The hosted MCP server requires OAuth. There is no alternative. When a user first connects, they complete a browser-based consent flow that authorizes the MCP server to act on their behalf. The MCP server holds the session; the agent calls tools through it.

This is a meaningful constraint: the hosted MCP is built for interactive, user-present workflows. The consent flow requires a browser. It does not support integration tokens or PATs. A background agent, whether a nightly sync, a scheduled pipeline, or a headless automation running without a user in the loop, cannot complete that flow autonomously.

The Notion API has no such constraint. It accepts three bearer token types:

• Internal integration tokens: created once per workspace, used by the agent directly. No user consent flow, no OAuth redirect. Best for single-workspace internal tooling and background automation.
• OAuth access tokens: issued per user via a public connection OAuth flow. The agent acts as the user who authorized it. Required for multi-user B2B products where each user's agent should see only their own workspace content.
• Personal access tokens (PATs): tied to the creator's identity and permissions. Practical for personal automation, not for multi-tenant products.

For multi-tenant B2B agents, where every customer has their own Notion workspace and the agent must act on behalf of each one separately, both the MCP path and the API's OAuth path give you the right model: one OAuth token per user, scoped to that user's workspace. What neither path provides is the infrastructure to store, rotate, and revoke those tokens at scale. The rate limit on the hosted MCP is 180 requests per minute per user, with search capped at 30 per minute; these are per-user limits, which confirms that the platform expects per-user credential isolation, not a shared service account.

What you own in production

The hosted MCP manages tool schema definitions, endpoint normalization, and some response formatting on your behalf. When Notion updates its API, Notion updates the MCP server tools; your agent picks up capability changes without a redeploy, and without you maintaining a schema library. That is a genuine operational advantage for fast-moving products.

What the MCP path does not manage: token storage, token refresh, revocation on user disconnect, and tenant isolation. Those remain your responsibility, regardless of whether the tokens came from an MCP OAuth flow or a direct API OAuth flow.

The direct API path means you own the full stack: endpoint selection, request construction, error handling, rate limit retries, token lifecycle management, and schema updates when Notion versions the API. That's more surface area. It's also more control. If Notion ships a new API capability, you can use it immediately without waiting for the MCP server to expose a tool for it.

The maintenance trajectory differs too: MCP tool schemas are unversioned and can change when Notion updates the hosted server. The Notion REST API uses explicit date-based versioning; you opt into new behavior by changing the ^{Notion-Version} header. For deterministic production pipelines where schema stability matters, the versioned API is a more predictable dependency.

When to use MCP, when to use the API

Use Notion MCP when:

• You are building an interactive agent in Claude Code, Cursor, or a similar IDE-embedded context where the user is present for the OAuth flow
• The agent's primary job is search, retrieval, and content creation, not surgical document editing
• You want to validate a Notion agent concept quickly without writing API integration code
• Your agent orchestrates across multiple tools and you want standardized tool discovery behavior across all of them
• The agent is personal or single-user, not a multi-tenant B2B product

Use the Notion API directly when:

• The agent runs headlessly: scheduled jobs, background automations, event-driven pipelines, or any workflow without a user present at execution time
• The agent needs block-level editing: targeted updates to specific blocks without reloading and replacing entire pages
• The agent must react to Notion changes via webhooks
• You need query coverage on plans below Business tier (data source querying via MCP requires Enterprise + Notion AI)
• You need the full data source API surface, including Notion's ^2025-09-03 versioned endpoints for managing multiple data sources per database
• Schema stability matters more than automatic tool updates

The credential problem that exists on both paths

Whether you chose the MCP path or the API path, every user in your multi-tenant agent system has their own Notion credential. Fifty customers, fifty OAuth tokens, fifty credential lifecycles to manage.

The hosted MCP OAuth flow gives you a session-scoped token per user. The API's public connection OAuth flow gives you an access token per user. In both cases, the token needs to live somewhere: encrypted at rest, isolated per tenant, and revocable when a user disconnects. In both cases, the token can expire or be revoked, and your agent needs to detect that and either refresh or re-prompt the user, rather than silently failing.

Neither path solves this for you. Notion's API tokens from public connections don't expire on a fixed schedule, but they can be revoked at any time by the user inside Notion's settings. Your agent has no built-in way to know when that has happened unless you are watching for the 401 and handling it correctly.

Scalekit's Notion connector handles the OAuth flow, token storage, and credential lifecycle for both paths, so the MCP vs API decision doesn't change what you need to build for auth infrastructure.

Which one to build against

If your agent runs interactively and its core job is searching and authoring Notion content, the hosted MCP is the faster path to a working agent. The tool definitions are maintained by Notion, the auth flow is handled for you at connection time, and you're operational quickly.

If your agent runs without a user present, needs surgical block-level edits, must react to workspace changes via webhooks, or requires query coverage on plans below Enterprise, use the API directly. The MCP server's OAuth-only auth model and retrieval-focused tool surface are genuine constraints, not configuration options.

Most production B2B agents end up on the API path for background workflows and use the MCP path for interactive, user-facing functionality. Those two modes often coexist in the same product. Either way, the credential management problem is the same, and that's what needs a production-grade solution.

Browse the Scalekit Notion connector: scalekit.com/agent-connector/notion