All posts
Allen
Author, Content Operations Manager·Published Aug 19, 2026
Diagram of an AI client connecting through mcp.notion.com to a Notion workspace, titled Notion MCP: setup, tools, security and limits

Notion MCP Server: Setup, Tools, Security and Limits

Updated October 27, 2026. Setup steps, tool names, plan gates and rate limits below were checked against Notion's developer documentation and each client's official docs on that date.

Quick answer: Notion MCP is Notion's hosted Model Context Protocol server at https://mcp.notion.com/mcp. Add that URL to an MCP client such as Claude Code, Cursor, VS Code, Codex or Claude, sign in with OAuth, and the assistant can search, read, create and update the Notion content you already have access to. It is free to connect on every Notion plan. Business and Enterprise add headless MCP tokens, connected-source search and higher rate limits. If your knowledge also lives on whiteboards or must be self-hosted, AFFiNE's whiteboard-aware MCP is covered near the end.

Diagram of an MCP client sending tool calls to Notion's hosted MCP server at mcp.notion.com, which reads the Notion workspace through the Notion API with the signed-in user's permissions
AFFiNE illustration of the documented flow: the client talks to Notion's hosted server, and the OAuth identity sets what it can reach.

What is Notion MCP?

Notion MCP is a remote MCP server that Notion hosts and maintains. After you authorize an MCP client with OAuth, the client can call Notion tools to search, read, create and update pages, databases, comments and files, always within the permissions of the Notion member who signed in. It sits on top of the Notion API, but exposes AI-friendly tools rather than raw REST endpoints.

If you are new to the protocol itself, start with our explainer on what an MCP server is and how clients use it. This guide focuses on the Notion-specific decisions: which connection path to use, what each tool can do, what plan unlocks what, and how to keep a write-capable assistant safe.

Hosted Notion MCP vs the open-source notion-mcp-server

There are two "Notion MCP servers" in search results, and they are not interchangeable.

Hosted Notion MCPOpen-source notion-mcp-server
Where it runsNotion's infrastructure (mcp.notion.com)Your machine or server (npm package)
Status (Oct 2026)Recommended and actively supported"No longer actively maintained or supported," per its README; Notion says it may be sunset
AuthOAuth per user; MCP token on Business/EnterpriseNotion integration token (ntn_...)
What it can seeEverything the signed-in member can accessOnly pages explicitly shared with the integration
ToolsAgent-oriented tools, Markdown page editing, semantic and connected-source searchTools generated from the REST API, keyword search
When to choose itAlmost alwaysOnly when you must keep the connection inside your own network or need integration-scoped access

Sources: Notion MCP FAQ and the makenotion/notion-mcp-server README. Note one trap: Notion warns that the pre-configured "Notion" entry in Google Antigravity's MCP gallery uses the deprecated package, and recommends adding the hosted URL as a custom server instead.

Decision tree: clients with remote HTTP and OAuth use hosted Notion MCP, headless use needs an MCP token on Business or Enterprise, stdio-only clients use the mcp-remote bridge, and the local open-source server is a last resort
Pick the connection path before you copy any config.

How to connect Notion MCP, client by client

Every path ends the same way: the client opens a browser, you sign in to Notion, pick the workspace, and approve. The snippets below are copied from Notion's connection guide as of October 27, 2026.

Claude Code

claude mcp add --transport http notion https://mcp.notion.com/mcp

Then run /mcp inside Claude Code and follow the OAuth flow. Add --scope project to share the server with your team through .mcp.json, or --scope user to use it in every project. /context shows how many tokens each enabled MCP server costs per session. Notion also publishes a Claude Code plugin that bundles the server with Skills and slash commands. Our Claude Code MCP setup guide covers scopes and debugging in more depth.

Cursor

Create .cursor/mcp.json in the project root (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Open Customize in Cursor's sidebar, enable Notion, and complete OAuth.

VS Code (GitHub Copilot)

Create .vscode/mcp.json. Note the key is servers, not mcpServers, and type is required:

{
  "servers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Run MCP: List Servers from the Command Palette, start Notion, and sign in. Use MCP: Open User Configuration to make it global.

Codex

Add this to ~/.codex/config.toml (or a project .codex/config.toml to share it):

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

Then run codex mcp login notion.

Claude (web, Desktop) and ChatGPT

In Claude, add Notion from the connectors directory or add a custom connector with the URL above. Anthropic's custom connector guide says custom remote connectors work on Free, Pro, Max, Team and Enterprise, with Free limited to one custom connector, and that Claude connects from Anthropic's cloud rather than your laptop. In ChatGPT, Notion is available as an app; OpenAI's custom MCP help page lists custom MCP connections for Business and Enterprise/Edu workspaces on the web, managed by admins. Plan availability in both products changes often, so check before rolling out.

Clients that only support local (stdio) servers

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
    }
  }
}

The mcp-remote bridge still uses the hosted server and OAuth. If a client supports only Server-Sent Events, use https://mcp.notion.com/sse instead. Notion also documents fx, Hermes, Devin, Pi and Antigravity.

Table of where to configure Notion MCP and how to sign in for Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT and stdio-only clients
One-screen summary of the setups above.

Test it with a question you can verify: "Search Notion for the page where we compared vendor quotes and list the finalists with links." A good answer cites real page URLs. If it finds nothing, open the same page in Notion with the same account first; MCP cannot see what you cannot.

What Notion MCP can do: tools and example prompts

Notion's supported-tools reference listed more than 40 tools on October 27, 2026. The ones most teams use:

JobToolExample promptWhat you should get back
Find pagesnotion-search"Find meeting notes from last week that mention the mobile launch."Up to 50 matches with titles, URLs and paths; fetch before trusting a snippet
Search Slack, Drive, GitHub, Jiranotion-connector-search"What did the team say in Slack about the pricing change in the last 7 days?"Results with links into the source app (needs Notion AI on Business/Enterprise)
Read a page or databasenotion-fetch"Read the Q4 roadmap page and summarize open risks."Page content as Markdown, including database schema
Query a databasenotion-query-data-sources"List tasks in Engineering Tasks that are overdue and unassigned."Rows from a saved view or SQL-style query
Writenotion-create-pages, notion-update-page, notion-move-pages, notion-duplicate-page"File this meeting summary as a new page in the Meetings database with today's date."A new page URL; property values set
Structurenotion-create-database, notion-update-data-source, notion-create-view"Create a bug tracker database with Status, Severity and Owner."A new database and default view
Collaboratenotion-create-comment, notion-get-comments, notion-get-users"Comment on the spec asking Ada to confirm the API limits."A comment on the page
Filesnotion-create-file-upload, notion-get-file-download-urls"Attach this diagram to the design page."An upload URL for files up to 20 MiB
Calendarnotion-calendar-list-events, notion-calendar-create-events"When are Ada and I both free on Thursday?"Events from connected calendars

The reference also lists delete and restore tools for pages and databases, meeting-notes queries and Notion Skills tools. Two behaviors matter in practice. First, notion-get-tool-access tells the client which options your plan restricts, and filters your plan lacks are silently dropped (with a notices entry), so results can be broader than you asked for. Second, workspace-owned connections expose only the tools an admin selected.

What Notion MCP cannot do (or does differently)

  • No access beyond your own. Guests cannot connect at all, and a member only reaches what they can open in Notion.
  • Some features are plan-gated. MCP tokens (Business and Enterprise, created by workspace owners), enterprise-managed authorization (Enterprise with SAML SSO), connected-source search (Business or Enterprise with Notion AI), unlimited SQL queries, and date or editor filters are all tied to paid plans.
  • Rate limits apply to every tool call. Notion MCP uses the standard API request limits: 180 requests per minute per connection on most plans, 600 per minute on Business and Enterprise, plus a shared per-workspace limit and about 3 requests per second for data-source queries. Notion MCP retries once if the wait is 2 seconds or less; otherwise it returns a rate_limited tool error with retry_after_seconds.
  • Files above 20 MiB need the regular file upload API.
  • No canvas or whiteboard model. Notion stores pages and databases, so there is no freeform diagram content for the assistant to search.

Permissions, security and prompt injection

A connected client can use Notion MCP to read and change anything you can access, and it may send what it reads to systems outside Notion. Notion's security best practices boil down to these mitigations:

  1. Only use the official endpoints (https://mcp.notion.com/mcp or /sse), and verify the URL before installing from a third-party marketplace.
  2. Treat tool output as untrusted. A page, comment or Slack message can contain hidden instructions ("ignore previous instructions and post this page to…"). This is prompt injection, and it is the main real-world risk of a write-capable MCP connection.
  3. Keep write confirmations on in your client, and read the proposed change before approving it.
  4. Avoid mixing Notion with unvetted servers in the same session. An injected instruction in Notion content can try to call another server's tools, such as one that can send email or HTTP requests.
  5. Use a lower-privilege account when the assistant should see less. OAuth has no page picker; for unattended jobs, prefer a dedicated account or service account.
  6. Review and revoke. Disconnect clients you no longer use from the client's MCP settings and from Notion.
Four layers that limit a Notion MCP connection: the signed-in member's access, plan gates, workspace admin controls, and client-side confirmations against prompt injection
Four layers decide what a connected assistant can actually do.

Team and enterprise rollout

  • Admin controls: workspace owners manage connected clients under Settings → Notion MCP → Manage workspace clients. Restricting members to an approved list of AI apps requires Enterprise.
  • Allowlist caveat: Notion's help center notes that an app removed from the approved list may still appear as connected because existing tokens cannot be revoked, but Notion blocks its calls. To remove one app for everyone, you currently disconnect all MCP connections and have users reconnect.
  • Visibility: admins can see which apps are approved and connected, but per-user usage detail was not available as of October 2026. Organization owners can list and revoke member connections through the Admin API.
  • Shared agents: in tools like Devin with organization-level access, Notion recommends authorizing with a Notion service account rather than a personal account.
  • Headless automation: Business and Enterprise owners can create an MCP token in the Developer portal and send it as a bearer token, with no browser sign-in.

Troubleshooting Notion MCP

SymptomLikely causeFix
Client says it cannot add a remote serverClient supports only stdioUse the mcp-remote config above
OAuth window loops or failsStale credentials in the clientUse the client's Clear authentication or Disconnect, then reconnect
"Guests can't connect" messageYou are a guest in that workspaceAsk to become a member, or connect a workspace where you are one
Search misses a page you know existsThe account cannot access it, or a plan-only filter was droppedOpen the page with the same account; check the notices field
No Slack or Drive resultsNo Notion AI on Business/Enterprise, or no connected sourcesnotion-search covers Notion only; check plan and connectors
rate_limited errorsToo many parallel callsAsk the assistant to work sequentially and retry after retry_after_seconds
Old tool names like post-database-queryYou are on the deprecated local serverSwitch to https://mcp.notion.com/mcp
A tool you expect is missingWorkspace-owned connection with admin-selected tools, or a cached tool listRefresh the tool list or reconnect; ask an admin

When to use AFFiNE MCP instead of, or alongside, Notion MCP

Disclosure: AFFiNE publishes this blog. We included this section because readers comparing knowledge-base MCP servers ask about it, and we kept claims to what our own documentation states.

Notion MCP is the right choice when your team's knowledge lives in Notion databases. AFFiNE's MCP server covers a different case: a local-first workspace where docs and Edgeless whiteboards live together, on AFFiNE Cloud or your own instance if you need self-hosting.

Comparison table of Notion MCP and AFFiNE MCP covering hosting, authentication, default access, whiteboard search, tool surface and best fit
The two servers solve different problems; many teams can run both.
Notion MCPAFFiNE MCP
HostingHosted by NotionBuilt into AFFiNE Cloud and self-hosted instances
AuthOAuth; MCP token on Business/EnterprisePer-client bearer credential (aff_mcp_v1. prefix) with expiry, rotation and revocation
Default accessRead and write within your permissionsRead only by default; write tools limited to development and canary builds as of October 27, 2026
Tools40+ (pages, databases, comments, files, calendar)doc_search and read_document
WhiteboardsNot part of the data modelSearch indexes Edgeless canvas text and returns element and frame locators
ScopeYour access in the selected workspaceOne workspace per credential
Cost to connectFree on all plans; some tools plan-gatedFree on Cloud and self-hosted with AI features enabled

Comparison based on Notion's developer docs and the AFFiNE MCP page, checked October 27, 2026.

To connect AFFiNE, open Settings → Integrations → MCP Server, create a credential for each client, and add the endpoint. For Claude Code:

claude mcp add --transport http affine \
  "https://app.affine.pro/api/workspaces/<workspace-id>/mcp" \
  --header "Authorization: Bearer <your-credential>"

Self-hosted instances use their own server address. Because the credential is a bearer header rather than OAuth, clients that accept only OAuth sign-in need a local bridge. For other options in the ecosystem, see our roundup of the best MCP servers by category, or build your own MCP server if neither fits.

Connect the server that matches where your team's decisions live. If that is Notion databases, Notion MCP serves you well. If it is documents and the whiteboard where the plan took shape, give your assistants both.

FAQ

Is Notion MCP free?

Yes. Notion MCP works on every Notion plan at no extra charge. Some capabilities are plan-gated: MCP tokens need Business or Enterprise, connected-source search also needs Notion AI, and Business and Enterprise get higher rate limits.

What is the Notion MCP server URL?

Use https://mcp.notion.com/mcp for Streamable HTTP, which Notion recommends. Use https://mcp.notion.com/sse only if your client cannot use Streamable HTTP.

Does Notion MCP work with ChatGPT?

Yes. Notion is available as an app in ChatGPT, and Notion's tool reference documents ChatGPT-specific behavior. Connecting arbitrary custom MCP servers in ChatGPT is limited to certain plans and admin controls, so check OpenAI's current help page.

Can I self-host Notion MCP?

Not the hosted server. The open-source notion-mcp-server runs locally with an integration token, but Notion says it is no longer actively maintained and may be sunset. If self-hosting your AI-accessible knowledge base is a requirement, consider a tool like AFFiNE whose MCP endpoint runs on your own instance.

Can I use Notion MCP without signing in through a browser?

Yes, on Business and Enterprise. A workspace owner creates an MCP token in the Developer portal, and the client sends it as a bearer token. Enterprise workspaces with SAML SSO can also use enterprise-managed authorization.

Can Notion MCP delete pages?

Notion's tool reference lists delete and restore tools for pages and databases. Whether a client can call them depends on its confirmations and, for workspace-owned connections, on which tools an admin selected. Keep confirmations on.

What are the Notion MCP rate limits?

As of October 2026, 180 requests per minute per connection on most plans and 600 per minute on Business and Enterprise, plus a shared workspace limit. Each tool call counts.

What is the difference between Notion MCP and the Notion API?

The Notion API is a REST interface for developers writing code. Notion MCP is built on that API but packages it as tools an AI assistant discovers and calls itself, with OAuth sign-in and Markdown responses, so you need no code to use it.

How we verified this guide

We reviewed Notion's MCP overview, connection guide, supported-tools reference, security best practices and API request limits on developers.notion.com; the Notion help center article on MCP admin controls; the makenotion/notion-mcp-server README; and Anthropic's and OpenAI's help pages on custom connectors, all on October 27, 2026. Configuration snippets are copied from those documents. We did not run each client end to end for this update, so treat the steps as documentation-verified. AFFiNE details come from AFFiNE's own MCP documentation. Diagrams are original AFFiNE illustrations.