MCP Server Guide

Notion MCP Server: Give Your AI Agent Workspace Access

Notion runs an official hosted MCP server at mcp.notion.com. It uses OAuth rather than bearer tokens, which shapes how you deploy it and what automation is possible.

The short answer

Notion maintains an official hosted remote MCP server at https://mcp.notion.com/mcp. It is the actively supported option and requires user-based OAuth. A separate open-source local server exists, but Notion has said it is prioritising the remote server and may sunset the local repository.

What is the Notion MCP server?

The hosted Notion MCP server lets an AI agent search your workspace, read and write pages, create and query databases, handle comments, and look up users — roughly 18 tools in total. Because Notion hosts it, there is no infrastructure to run and no version to keep patched on your side.

The important architectural detail is authentication. The hosted server requires user-based OAuth and does not accept bearer tokens, so a human has to complete an authorisation flow before an agent can act. Each person connects through the same public integration with a one-click grant, and the agent then operates with that person's permissions.

There are two official servers with the same name. The remote one at mcp.notion.com is what Notion recommends and supports. The local one, published to npm as @notionhq/notion-mcp-server, still exists but Notion has signalled it may be retired, so treat it as a fallback rather than a foundation.

What you should know before connecting it

Hosted endpoint

The remote server lives at https://mcp.notion.com/mcp. Notion runs and updates it, so you connect a client rather than deploying anything.

OAuth only, no bearer tokens

The hosted server requires an interactive OAuth grant. Fully headless setup is not supported — a human completes the flow once, and the agent inherits that user's access.

About 18 tools

Coverage spans search, page create and update, database creation and querying, comments, and user lookup. Each is a discrete tool the agent can choose.

Permissions follow the person

The agent sees exactly what the authorising user can see. Scoping access is done by choosing which pages that account can reach, not by configuring the server.

Local server is deprioritised

makenotion/notion-mcp-server on npm is the older local option. It works, but Notion has stated it is prioritising the remote server and may sunset the repository.

Setup plan

Decide which Notion account authorises it — The agent inherits that account's permissions. For a shared bot, create a dedicated Notion user with access only to the pages it should touch rather than authorising a workspace admin.
Limit page access before connecting — Share only the specific pages or databases the agent needs with that account. This is your real permission boundary — the MCP server has no separate scoping layer.
Add the server to your client — Most MCP clients accept a JSON entry pointing at the remote server through mcp-remote: {"mcpServers":{"notion":{"command":"npx","args":["-y","mcp-remote","https://mcp.notion.com/mcp"]}}}. Claude Desktop is the exception — add remote servers under Settings, Connectors.
Complete the OAuth grant — The first connection opens a browser for one-click authorisation. Expect to redo this if tokens are revoked or the integration changes.
Test reads before enabling writes — Start with search and page reads. Confirm the agent finds the right content and respects boundaries before letting it create or edit pages.

Useful agent workflows

Workspace question answering

Let the agent search Notion and answer from your actual documentation instead of guessing, with a link back to the source page.

Meeting and task capture

Turn a chat conversation into a structured Notion page or database row, with fields filled from what was discussed.

Database triage

Query a database, summarise what changed, and post the digest to your team channel on a schedule.

Draft and review loops

Have the agent draft into a staging page a human reviews, rather than writing directly into published documentation.

Security checklist

Authorise with a purpose-made Notion account, never a workspace admin.
Share only the pages and databases the agent genuinely needs — page access is the permission boundary.
Prefer read-only workflows until you have watched the agent behave correctly for a while.
Treat page content as untrusted input: text inside a Notion page can attempt prompt injection against an agent that reads it.
Route writes into a staging area a human reviews before anything reaches published docs.
Revoke the OAuth grant in Notion when the agent is retired — deleting the bot does not revoke access.
Remember that headless automation is limited by design, because the hosted server requires an interactive grant.

Treat every MCP tool as an API capability, not as a harmless chat feature. Start read-only, test in a non-production account, and require human approval for changes.

Frequently asked questions

Does Notion have an official MCP server?

Yes. Notion maintains a hosted remote MCP server at https://mcp.notion.com/mcp, and it is the option Notion actively supports. A separate open-source local server exists on npm as @notionhq/notion-mcp-server, but Notion has said it may be sunset.

Can I use an API token instead of OAuth?

Not with the hosted server. It requires user-based OAuth and does not support bearer token authentication, so a person must complete the authorisation flow before an agent can act.

What can the Notion MCP server actually do?

It ships roughly 18 tools covering search, page create and update, database creation and querying, comments, and user lookup.

How do I stop an agent reading sensitive pages?

Control it at the Notion permission layer. The agent sees whatever the authorising account can see, so authorise a dedicated account and share only the pages it should reach.

Primary documentation

Verify current endpoints, permissions, and preview limitations in the official Notion MCP documentation before production rollout. Vendor capabilities can change faster than third-party guides.

Run an MCP-ready AI agent without server maintenance

OpenClaw Launch handles the agent host, updates, and uptime so you can focus on safe tool design.

Configure your agent