Notion MCP vs the Notion API for AI Assistants

Use Notion MCP when a person is working with an assistant in a conversation: search the wiki, draft a page from these notes, update the rows in this database. Use the Notion REST API when a program should do the same thing every time, or when it should run with nobody there: a nightly export, a sync from another system, a webhook that files a page when a form arrives. The deeper difference is not the tools but the identity. Notion MCP signs the assistant in as you, with everything you can reach. The API runs as a bot that can open only the pages someone has shared with it, with only the capabilities you ticked for it. For an AI assistant, that difference decides more than anything on either tool list.

This is the Notion version of a question we have answered for other tools: Jira MCP vs the Jira API and Linear MCP vs CLI vs API. What the MCP server’s tools do one by one is in what Notion MCP can do; Notion’s built-in assistant is compared in Notion MCP vs Notion AI.

The two routes side by side

• Address: Notion MCP is one hosted endpoint, https://mcp.notion.com/mcp. The REST API is https://api.notion.com/v1/..., and every request must carry a Notion-Version header.
• Who calls it: an MCP client such as Claude, ChatGPT, Cursor or Codex, choosing tools mid-conversation. The API is called by code someone wrote and can review.
• Identity: MCP acts as the person who signed in. The API acts as a connection’s bot user, which is a separate identity in the workspace.
• Sign-in: MCP requires an OAuth sign-in in a browser. The API takes a static token for an internal connection, or OAuth for a public one that other workspaces install.
• Reach: MCP offers a curated set of tools, including Notion AI features. The API offers the documented endpoints, including trashing pages, large file uploads and webhooks.
• Limits: both draw on the same request budget. MCP adds a tighter limit on search.

Whose access it uses: yours or a bot’s

Notion MCP works as you. Notion’s help page on MCP↗ (opens in a new tab) puts it plainly: MCP tools act with your full Notion permissions and can access everything you can access. If you can open your private pages, the HR space and the company handbook, so can the assistant, in the one workspace you chose at sign-in. There is no setting inside Notion MCP that gives it less than you have; the controls are your client’s approval prompts and, on Enterprise, which AI apps an admin allows to connect.

The API starts from nothing. Notion’s authorisation guide↗ (opens in a new tab) says a page must be shared with a connection by hand, from the page’s menu under Add connections, before the connection can touch it. Share one teamspace’s project pages and that is all the bot sees, whatever the person who created it can reach. Each authorisation also has a bot_id, so edits made through the API are made by the connection rather than by you.

On top of sharing, a connection has capabilities you choose when you create it: read content, update content and insert content; read comments and insert comments; and no user information, names without emails, or names with emails. Notion’s advice is to request the minimum. A bot that may read and comment on one teamspace is a much smaller thing to hand an assistant than your own account.

How each one signs in

Notion MCP is interactive only. Notion’s getting-started guide↗ (opens in a new tab) says it currently requires the OAuth flow and that non-interactive authorisation for automated workflows is being worked on. It also says the older open-source notion-mcp-server, which accepted a bearer token and used the API underneath, is no longer actively maintained. So there is no supported way today to run the hosted server from a scheduled job.

The API has two routes. An internal connection is created in Notion’s developer portal by a workspace owner and gives you an installation access token for that one workspace. A public connection uses OAuth 2.0: the person installing it picks which pages to grant, and your code receives access and refresh tokens. Either way the token lives in your code’s environment, not in a chat.

# API: a script reads one page as the connection's bot
curl https://api.notion.com/v1/pages/PAGE_ID \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-11"

# MCP: add the hosted server, then sign in with /mcp
claude mcp add --transport http notion https://mcp.notion.com/mcp

What each one can reach

The MCP server is a selection built for assistants. Notion’s supported-tools list↗ (opens in a new tab) covers search, fetching pages and databases, creating and updating pages, querying data sources, building databases and views, moving and duplicating pages, comments and file uploads up to 20 MiB. It also reaches things the plain API does not offer as tools: AI search across connected apps where Notion AI is on, meeting notes, Skills, and starting Custom Agents. What it leaves out is as telling. There is no tool to delete or trash a page and none to change who a page is shared with.

• Trashing. The API trashes a page with an update request that sets in_trash to true. MCP has no equivalent, which is a safety property if you want an assistant that cannot remove anything.
• Large files. MCP uploads stop at 20 MiB; Notion points larger files at the API’s file upload endpoints.
• Big queries. Querying a data source through the API pages through up to 10,000 results with start_cursor and has_more, which a loop handles better than a conversation.
• Events. The API can push changes to you through webhooks↗ (opens in a new tab) such as page.content_updated and comment.created, delivered to a public HTTPS endpoint. MCP only answers when an assistant asks.

Rate limits: one budget, two doors

Both routes spend from the same allowance. Notion’s request limits↗ (opens in a new tab) give each connection 180 requests a minute on most plans and 600 on Business and Enterprise, with a separate limit shared across the workspace. Going over returns HTTP 429 with a rate_limited code, a Retry-After header in seconds, and a rate_limit_reason naming which limit you hit. The same page caps a request at 1,000 blocks and 500 KB, and a rich text field at 2,000 characters.

Notion says the standard limits apply per user to MCP, totalled across all tool calls, and that notion-search has a stricter limit of 30 requests a minute. The server retries a rate limit once when the wait is two seconds or less and otherwise returns it as a tool error. In practice the limit an assistant meets first is often not Notion’s at all. Every result it reads takes room in the model’s context, so an assistant asked to touch five hundred rows slows down and starts summarising where you wanted exactness. A script does the same five hundred updates in a loop and logs each one.

Which to use for which job

• Finding, reading and drafting in a conversation: MCP. The browser sign-in means no token on disk, and your client asks before each write.
• Anything that must run with nobody there: the API with an internal connection. The hosted MCP server has no non-interactive sign-in yet.
• An assistant that should see only part of the workspace: the API’s bot, shared with just those pages and given only the capabilities it needs. Notion MCP cannot be narrower than you.
• An assistant that must never delete: MCP, whose published tools cannot trash a page.
• Hundreds of rows, exact output or a migration: the API from a reviewed script, with a retry that honours Retry-After.
• Reacting to changes: the API’s webhooks.
• Notion AI features such as connected-app search, meeting notes and Custom Agents: MCP, where your plan includes them.

Using both well

The two routes combine better than they compete. Ask the assistant, over MCP, to find the right data source and try a filter on real rows. When the answer is right and you need it every week, ask it to write the API script, then review it, give it an internal connection shared with only that database, and schedule it. The bot’s edits then carry the connection’s name, not yours, which also makes them easy to tell apart later.

The one thing the MCP route does not give you is a separate name for the assistant. Its edits are made with your account. If your team needs to know which changes an assistant made, agree a habit, such as a comment line, or route that work through a connection instead.

The same question on fenbs

fenbs is a task board, not a document tool, and it answers the question the other way round: MCP is the main door, and the assistant gets a narrower seat than you. When a person connects an assistant with a browser sign-in, it receives an access token that lasts an hour and refreshes itself, and it acts with your role on the board narrowed by the scopes you tick: read, write, comment. A script that cannot sign in uses a token issued by hand under Settings, with a name, scopes and an optional expiry, and calls the same MCP tools. Revoking either stops it at once, and every change shows in History under the assistant’s name. The REST API page lists the endpoints, but API keys are not available yet; MCP covers the same ground in the meantime.