
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.

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.
There are two "Notion MCP servers" in search results, and they are not interchangeable.
| Hosted Notion MCP | Open-source notion-mcp-server | |
|---|---|---|
| Where it runs | Notion'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 |
| Auth | OAuth per user; MCP token on Business/Enterprise | Notion integration token (ntn_...) |
| What it can see | Everything the signed-in member can access | Only pages explicitly shared with the integration |
| Tools | Agent-oriented tools, Markdown page editing, semantic and connected-source search | Tools generated from the REST API, keyword search |
| When to choose it | Almost always | Only 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.

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 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.
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.
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.
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.
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.
{
"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.

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.
Notion's supported-tools reference listed more than 40 tools on October 27, 2026. The ones most teams use:
| Job | Tool | Example prompt | What you should get back |
|---|---|---|---|
| Find pages | notion-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, Jira | notion-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 database | notion-fetch | "Read the Q4 roadmap page and summarize open risks." | Page content as Markdown, including database schema |
| Query a database | notion-query-data-sources | "List tasks in Engineering Tasks that are overdue and unassigned." | Rows from a saved view or SQL-style query |
| Write | notion-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 |
| Structure | notion-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 |
| Collaborate | notion-create-comment, notion-get-comments, notion-get-users | "Comment on the spec asking Ada to confirm the API limits." | A comment on the page |
| Files | notion-create-file-upload, notion-get-file-download-urls | "Attach this diagram to the design page." | An upload URL for files up to 20 MiB |
| Calendar | notion-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.
rate_limited tool error with retry_after_seconds.
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:
https://mcp.notion.com/mcp or /sse), and verify the URL before installing from a third-party marketplace.
| Symptom | Likely cause | Fix |
|---|---|---|
| Client says it cannot add a remote server | Client supports only stdio | Use the mcp-remote config above |
| OAuth window loops or fails | Stale credentials in the client | Use the client's Clear authentication or Disconnect, then reconnect |
| "Guests can't connect" message | You are a guest in that workspace | Ask to become a member, or connect a workspace where you are one |
| Search misses a page you know exists | The account cannot access it, or a plan-only filter was dropped | Open the page with the same account; check the notices field |
| No Slack or Drive results | No Notion AI on Business/Enterprise, or no connected sources | notion-search covers Notion only; check plan and connectors |
rate_limited errors | Too many parallel calls | Ask the assistant to work sequentially and retry after retry_after_seconds |
Old tool names like post-database-query | You are on the deprecated local server | Switch to https://mcp.notion.com/mcp |
| A tool you expect is missing | Workspace-owned connection with admin-selected tools, or a cached tool list | Refresh the tool list or reconnect; ask an admin |
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.

| Notion MCP | AFFiNE MCP | |
|---|---|---|
| Hosting | Hosted by Notion | Built into AFFiNE Cloud and self-hosted instances |
| Auth | OAuth; MCP token on Business/Enterprise | Per-client bearer credential (aff_mcp_v1. prefix) with expiry, rotation and revocation |
| Default access | Read and write within your permissions | Read only by default; write tools limited to development and canary builds as of October 27, 2026 |
| Tools | 40+ (pages, databases, comments, files, calendar) | doc_search and read_document |
| Whiteboards | Not part of the data model | Search indexes Edgeless canvas text and returns element and frame locators |
| Scope | Your access in the selected workspace | One workspace per credential |
| Cost to connect | Free on all plans; some tools plan-gated | Free 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.