Notion's hosted MCP server. The endpoint, per-client OAuth setup, the tool list, the rate limits that actually bite, and how it differs from the open-source package it replaced, read from developers.notion.com on 2 September 2026.
Interactive examples · No account is connected on this page
Updated
Notion MCP is Notion's hosted Model Context Protocol server at https://mcp.notion.com/mcp. You authorise it with OAuth, after which an MCP client can search, read, create and update anything you can already access in the workspace. Its tools carry a notion- prefix, such as notion-search, notion-fetch, notion-create-pages and notion-update-page. The older self-hosted notion-mcp-server package still exists but is no longer actively maintained.
Pick an example to see which Notion MCP tools a task would call and what the result looks like. Examples are illustrative; nothing on this page connects to Notion.
Notion MCP is a hosted server at https://mcp.notion.com/mcp, so connecting means adding one URL to your client and completing OAuth. Claude Code takes one command, Cursor and VS Code take a short JSON entry, and stdio-only clients bridge through mcp-remote. Streamable HTTP is the recommended transport; SSE is only a fallback. Rate limits apply per user.
Claude Code registers the remote server over HTTP transport, then you authenticate with the /mcp command and complete the OAuth flow. The --scope flag decides where it lives: local for this project only, project to share it with a team through .mcp.json, or user to have it everywhere. Notion also publishes a Claude Code plugin that adds the server, skills and slash commands together.
claude mcp add --transport http notion https://mcp.notion.com/mcpIn Cursor the whole config is a name and a URL, because OAuth is handled interactively rather than through a header. Put it in .cursor/mcp.json for one project or ~/.cursor/mcp.json for all of them, then open Customize in Cursor's sidebar, enable Notion and complete the OAuth flow.
{
"mcpServers": {
"notion": {
"url": "https://mcp.notion.com/mcp"
}
}
}VS Code uses a servers object with an explicit type. Create .vscode/mcp.json in the workspace, then open the Command Palette and run MCP: List Servers, start the Notion server and complete the OAuth flow when prompted. MCP: Open User Configuration puts the same entry across all workspaces.
{
"servers": {
"notion": {
"type": "http",
"url": "https://mcp.notion.com/mcp"
}
}
}Streamable HTTP is the recommended endpoint. Notion publishes an SSE endpoint as well, but the docs say to use it only if the client cannot do Streamable HTTP. If your client supports local stdio servers alone, bridge to the remote endpoint with mcp-remote rather than reaching for the deprecated package.
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
}
}
}The authorisation is scoped to you: after you authorise, the client can read and update content that you can access in the selected workspace. Workspace owners manage MCP client access under Settings and Connections, and organisation owners can list and revoke members' connections through the Admin API. There is no non-interactive path yet — the docs say Notion MCP currently requires the OAuth flow, with support for automated workflows still in progress.
Settings → ConnectionsStandard API request limits apply per user across all tool calls, currently averaging 180 requests per minute. Search has its own stricter limit of 30 requests per minute. A separate workspace-wide limit is shared across all connections and scales with the plan, so you can be limited while under your personal ceiling. Notion's own advice when you hit it is to reduce parallel searches rather than retry harder.
180 requests/min per user · 30 searches/min · workspace limit sharedOfficial documentation: Read the Notion MCP docs.
Notion offers a hosted server and an older open-source package, and they are not interchangeable. The hosted server uses OAuth, is actively maintained and exposes notion- prefixed tools built for agents. The open-source notion-mcp-server runs locally with an integration token, wraps the JSON-based API, and is no longer actively maintained, so it is only a fallback.
| What differs | Notion MCP (hosted) | notion-mcp-server (open source) |
|---|---|---|
| What the client points at | https://mcp.notion.com/mcp | npx -y @notionhq/notion-mcp-server, run locally |
| Authentication | OAuth, completed interactively | A bearer token from an internal integration, passed as NOTION_TOKEN |
| Maintenance status | Notion's actively maintained server | No longer actively maintained; issues and pull requests are not monitored, and the repository may be sunset |
| Tool naming | notion- prefixed, e.g. notion-search, notion-create-pages | API-shaped, e.g. query-data-source, retrieve-page-markdown |
| What it wraps | Tools designed for agents, including markdown page editing | The JSON-based v1 APIs; v2.0.0 moved to Notion API version 2025-09-03 |
| Where it fits | The recommended path for most users; no infrastructure to run | A fallback where you must manage your own connection and deployment |
Endpoints, commands and tool names transcribed from developers.notion.com and the makenotion/notion-mcp-server README, both read 2026-09-02. Notion states it is prioritising the hosted server and may sunset the open-source repository.
The notion- tools cover search across Notion and connected apps, fetching pages, creating and editing pages, databases, data sources and views, comments, teams and people, and file uploads up to 20 MiB. A newer group handles Notion Skills and agent sessions. Everything a client can reach is limited to what the authorising user can already access.
notion-search searches Notion and connected apps such as Slack, Google Drive and Jira, narrowing by location, creator or editor, date, title or content status, and returning up to 50 results. notion-fetch retrieves the content once the model has picked a target.
notion-create-pages creates pages with properties and content, notion-update-page changes properties, content or icons, and notion-move-pages and notion-duplicate-page handle relocation and copying. notion-create-folder makes an empty folder.
notion-create-database and notion-update-data-source cover structure, notion-create-view and notion-update-view cover presentation, and notion-query-data-sources queries with SQL or runs an existing view.
notion-create-comment adds a page or block comment and notion-get-comments lists a page's discussions. notion-get-teams returns teamspaces and notion-get-users lists workspace members.
notion-create-file-upload returns a short-lived upload URL plus the headers and form field the client must use. After the upload, pass the response's suggested_markdown to notion-create-pages or notion-update-page to attach the file. Workspace file-size limits still apply, and larger files go through the file upload API instead.
notion-search-skills finds active Notion Skills and notion-convert-page-to-skill turns a page into one. A further group — notion-list-agents, notion-spawn-session, notion-get-session-status, notion-wait-session, notion-stop-session and the session event tools — drives Custom Agents. Notion notes that connected-app search and the Custom Agent tools require Notion AI, and some filters require Business or Enterprise plans.
Notion MCP is Notion’s hosted Model Context Protocol server. After you authorise it with OAuth, an MCP client such as Claude Code, Cursor or VS Code can search, read, create and update content you can already access in your workspace.
Its tools carry a notion- prefix — notion-search, notion-fetch, notion-create-pages, notion-update-page and more. The older self-hosted notion-mcp-server package still exists but is no longer actively maintained, so the hosted server is the default choice.
Notion MCP covers the knowledge base. The servers below usually sit next to it in the same client: team chat, code hosting, a browser and broad app connectors. Each guide lists the install or connection steps, how the server authenticates, rate limits where the vendor publishes them, and the tools it exposes.
Slack MCP ServerSlack's own server for channels, threads and search.
GitHub MCP ServerRepositories, issues, pull requests and CI logs.
Cursor MCPHow Cursor loads MCP servers from mcp.json.
Claude MCPAdding MCP servers to Claude clients.Zapier MCP ServerZapier actions exposed to an agent as tools.Playwright MCP ServerBrowser automation for sites with no API.n8n MCP Servern8n workflows exposed as MCP tools.Point your client at https://mcp.notion.com/mcp over HTTP, using SSE only as a fallback.
Approve access for the workspace; owners can review and revoke connections under Settings → Connections.
Run a notion-search for a page you know exists before letting the agent create or update content.
Search for the notes, fetch them, then create task pages in a database with notion-create-pages — keeping the source page linked.
notion-search covers Notion and, with Notion AI, connected apps such as Slack and Google Drive; fetch the page before quoting it.
Use notion-query-data-sources to read and notion-update-page to change properties, mindful of the 180 requests per minute average and 30 searches per minute limits.
notion-create-file-upload returns an upload URL for files up to 20 MiB; attach the result with notion-create-pages or notion-update-page.
These answers cover the questions people ask once Notion MCP is connected: whether an integration token is still needed, whether it works in unattended workflows, what the rate limits are, why ChatGPT shows search and fetch without the notion- prefix, how much of a workspace a client can see, and what to do if your client only supports stdio.
Not for the hosted server. Notion MCP at https://mcp.notion.com/mcp uses OAuth, so there is no token to create or paste and no infrastructure to run. Tokens belong to the open-source @notionhq/notion-mcp-server package, which uses bearer authentication with a NOTION_TOKEN from an internal integration — and which Notion says is no longer actively maintained.
Not yet. Notion's own FAQ says Notion MCP currently requires you to complete the OAuth authorisation flow, and that support for non-interactive authorisation for automated workflows is still being worked on. If a headless flow is a hard requirement today, the bearer-token open-source server is the documented workaround, with the maintenance caveat attached.
Standard API request limits apply per user across all tool calls, currently averaging 180 requests per minute, or three per second. Search is stricter at 30 requests per minute. A separate workspace limit is shared across all of that workspace's connections and scales with its plan, so you can be limited even when you are under the per-user ceiling. Notion's examples of what trips it: 35 searches a minute, or 185 fetches a minute.
search and fetch instead of notion-search and notion-fetch?That is deliberate and only happens with OpenAI MCP clients such as ChatGPT. Notion drops the notion- prefix from those two tools there, because the Deep Research specification for remote MCP servers requires those exact names. Every other tool keeps its prefix, and other clients see notion-search and notion-fetch unchanged.
Whatever you can see. Notion's documentation frames it as: after you authorise the connection, the client can read and update content that you can access in the selected workspace. Control is administrative rather than per-tool — workspace owners manage MCP client access under Settings and Connections, and organisation owners can list, revoke, deny or restore members' connections through the Admin API.
Bridge to the remote endpoint with mcp-remote: configure npx -y mcp-remote https://mcp.notion.com/mcp as a stdio command. Notion lists this ahead of running the open-source server locally, which it describes as a last resort.
Search and fetch get the context in. Deciding what gets written back, on what trigger, and which of those steps a person still has to see is the harder half. That means choosing which pages an agent may edit, how often it runs, and what it should do when a database property does not match what it expected.