# Notion MCP server: URL, setup, tools and the open-source version > Notion's hosted MCP server at mcp.notion.com: setup in Claude Code, Cursor, Codex and VS Code, its 68 tools, plan limits, the old local server, and Upsy. Updated 2026-11-02 · https://upsy.ai/guides/notion-mcp-server ## Short answer Notion MCP is Notion's hosted MCP server (a connector that lets an AI agent use your Notion) at `https://mcp.notion.com/mcp`. Add the address to your client, sign in to Notion in your browser, and the agent can search, read, create and update pages and databases, comment, and more. It works on every Notion plan, with no API key. In Claude Code: ``` claude mcp add --transport http notion https://mcp.notion.com/mcp ``` Then run `/mcp` to sign in. The older open-source server on GitHub, `@notionhq/notion-mcp-server`, is no longer maintained. Add Notion through Upsy instead if an agent should only read, or only take the actions you pick, or if you want several workspaces in one connection and a history of what each agent did. ## Notion's MCP server | | | |---|---| | Address | `https://mcp.notion.com/mcp` (Streamable HTTP) | | Fallback | `https://mcp.notion.com/sse`, only for clients without Streamable HTTP | | Sign-in | OAuth with dynamic client registration. Business and Enterprise owners can also create MCP tokens; Enterprise with SAML can use its identity provider | | Access | Everything your Notion account can open in the workspace you pick. There's no page picker | | Workspaces | One per connection. Guests can't connect | | Plans | "Notion MCP works on every plan." Some tools and higher limits need Business or Enterprise | | Limits | 180 requests a minute per connection, 600 on Business and Enterprise ([rate limits](https://developers.notion.com/guides/mcp/rate-limits)) | Notion's [setup guide](https://developers.notion.com/guides/mcp/get-started-with-mcp) has steps for more clients. Notion explains why it moved to a hosted server in [an inside look](https://www.notion.com/blog/notions-hosted-mcp-server-an-inside-look): pages come back as Notion-flavored Markdown, which uses far fewer tokens than the raw API. ### Connect it to your client **Claude Code.** Run the command above, then `/mcp` and sign in. Notion also has a Claude Code plugin with skills. See [Notion in Claude](/guides/claude/notion#claude-code). **Cursor.** Add Notion to `.cursor/mcp.json` in a project, or `~/.cursor/mcp.json` for all of them, then click **Connect**: ```json {"mcpServers":{"notion":{"url":"https://mcp.notion.com/mcp"}}} ``` **Codex.** Add this to `~/.codex/config.toml`, then run `codex mcp login notion`: ```toml [mcp_servers.notion] url = "https://mcp.notion.com/mcp" ``` **VS Code.** Add it to `.vscode/mcp.json`: `{"servers":{"notion":{"type":"http","url":"https://mcp.notion.com/mcp"}}}`. **Claude and ChatGPT.** Both have Notion in their app directories, running on Notion MCP. See [Notion in Claude](/guides/claude/notion). **Anything else.** Add a remote server with the address and OAuth. A client without remote MCP can run it through `mcp-remote`: `npx -y mcp-remote https://mcp.notion.com/mcp` as a command (stdio) server. ### Its tools Notion documents 70 tools ([tool list](https://developers.notion.com/guides/mcp/tools-faqs)). A connection lists 68: AI search isn't listed but can still be called, and search across connected apps appears only where you have it. 37 are read-only. Every name starts with `notion-`, such as `notion-search`: | Area | Read | Change | |---|---|---| | Search and pages | `search`, `fetch`, `list-recent-pages`, `list-favorite-pages`, `list-shared-pages`, `list-private-pages`, `list-page-backlinks`, `get-version-changes`, `view-version` | `create-pages`, `update-page`, `move-pages`, `duplicate-page`, `delete-pages`, `restore-pages` | | Databases | `query-data-sources`, `query-multiple-data-sources`, `query-meeting-notes` | `create-database`, `update-data-source`, `create-view`, `update-view`, `delete-databases`, `create-folder`, `update-folder` | | Comments and suggestions | `get-comments`, `get-suggested-edit` | `create-comment`, `update-comment`, `delete-comment`, `set-discussion-resolved`, `set-comment-reaction`, `create-suggested-edit`, `resolve-suggested-edit` | | Files | `download-attachment`, `get-file-download-urls` | `create-attachment`, `create-file-upload` | | Notion Calendar | `calendar-list-calendars`, `calendar-list-events`, `calendar-list-coworkers-events`, `calendar-list-calendar-resources`, `calendar-list-contacts` | `calendar-create-events`, `calendar-update-events`, `calendar-cancel-events` | | Skills | `get-enabled-skills`, `download-skill` | `convert-page-to-skill`, `upload-skill`, `update-enabled-skills` | | Custom Agents | `search-agents`, `search-sessions`, `query-sessions`, `get-session-status`, `wait-session`, `list-session-events`, `read-session-event` | `spawn-session`, `stop-session`, `send-message-to-session` | | Workspace | `get-self`, `get-users`, `get-teams`, `get-groups`, `memory-search`, `get-tool-access`, `get-async-task` | | - **Deleting moves to Trash.** `delete-pages` and `delete-databases` move up to 20 at a time to Trash, and `restore-pages` brings them back, except top-level workspace pages. - **Plans change what works.** SQL queries are unlimited only on Business or Enterprise with Notion AI; other plans get a few, on one database at a time. Meeting notes, search across connected apps and some search filters need Business or Enterprise, and Custom Agent tools need Custom Agents. `get-tool-access` tells the agent what your plan allows. - **Files** upload up to 20 MiB each. ### Where Notion's server stops - **No read-only mode.** A personal connection "acts with your full Notion permissions" ([Notion's help](https://www.notion.com/help/notion-mcp)), and you can't limit it to some pages. Only a workspace MCP token, on Business or Enterprise, can be limited to tools an admin picks. - **One workspace per connection.** For another one, disconnect and sign in again, or add a second server entry. - **No shared record for you.** What each agent did lives in each client. On Enterprise, Notion's audit log records MCP connections and allowlist changes. - **Plan gaps.** The SQL, meeting-notes and filter limits above apply on Free and Plus. For one workspace in one or two clients, with full access, Notion's server is enough. ## Notion MCP servers compared | | Notion MCP (hosted) | Upsy | notion-mcp-server (local) | |---|---|---|---| | Who runs it | Notion | Upsy, on top of Notion MCP | You, on your machine | | Sign-in | OAuth, or an MCP token on Business and Enterprise | OAuth to Upsy; Upsy signs in to Notion | An integration token | | Reach | Everything you can open in one workspace | The same, per workspace | Only pages shared with the integration | | Tools | 68 | Notion's 68, listed on request | 24, mapped to Notion's API | | Limits | Full access, or admin-picked tools with a token | Read-only, picked tools, or full access, per agent | The integration's capabilities | | Workspaces | One per connection | Up to 5 in one server | One per integration | | Maintained | Yes | Yes | No | ### The open-source local server [makenotion/notion-mcp-server](https://github.com/makenotion/notion-mcp-server), published on npm as `@notionhq/notion-mcp-server`, was Notion's first MCP server, and it still ranks high. Its README now says it's "no longer actively maintained or supported" and that Notion "may sunset this local MCP server repository in the future". Notion's own docs call the package deprecated. It runs locally with an internal integration token in `NOTION_TOKEN`, and reaches only the pages you share with that integration. That makes it the one way to keep an agent to a few pages. Its 24 tools map one to one to Notion's API, which returns raw block JSON and costs far more tokens than the hosted server's Markdown. People call the hosted server "Notion MCP" and this one "Notion MCP server", which causes much of the confusion. ### Notion as an MCP client Notion's Custom Agents can use other MCP servers, on Business and Enterprise plans ([Notion's help](https://www.notion.com/help/mcp-connections-for-custom-agents)). Notion offers ready-made ones such as Linear, Figma, Stripe and GitHub, and once an admin turns on **Enable custom MCP servers**, any server by address. ## Upsy's Notion MCP server Upsy connects to Notion MCP with your Notion sign-in, so the tools are the same 68. It's the same address as Upsy's other apps, `https://upsy.ai/connect`, so one server also holds your Gmail, Slack, Linear and more. What it adds: - **Read-only on any plan.** Set an agent to **Read-only**, or **Pick actions** to tick tools one by one. Upsy refuses the rest on its side, whatever the client does. - **A short tool list.** Notion comes through three Upsy tools, `app_tools`, `app_read` and `app_call`. Agents look up Notion's tools when they need them, instead of loading all 68 definitions up front. - **Up to five Notion workspaces** in one server, each with its own access. - **History and alerts:** every Notion tool an agent runs, refused attempts included, listed under that agent. - **Any client:** Claude, Claude Code, Cursor, Codex, ChatGPT, Grok, Muse, or anything with remote MCP and OAuth. On Notion Enterprise, a workspace owner who allows only approved AI apps has to approve Upsy too. ### Connect Notion to Upsy 1. Go to [upsy.ai](https://upsy.ai) and click **Set up Upsy**. 2. Open **Apps**, click **Connect an app** and pick **Notion**. Notion's sign-in opens: pick the workspace and allow access. For another workspace, click **Add account** next to Notion. 3. On the **Assistants** page, click **Add assistant** and choose your client under **Which assistant?** for its exact steps. ### Add the server to your client Signing in opens an Upsy page: tick Notion, keep full access or pick **Read-only**, and click **Allow**. To allow only some actions, use **Pick actions** on the agent's page afterwards. - **Claude Code:** `claude mcp add --transport http --scope user upsy https://upsy.ai/connect`, then `/mcp` to sign in. - **Cursor:** add `{"mcpServers":{"upsy":{"url":"https://upsy.ai/connect"}}}` to `~/.cursor/mcp.json`, then click **Connect** next to upsy. - **Codex:** `codex mcp add upsy --url https://upsy.ai/connect`, then `codex mcp login upsy`. - **Claude and ChatGPT:** add `https://upsy.ai/connect` as a custom connector ([Claude](/guides/claude/custom-connector), [ChatGPT](/guides/chatgpt/custom-connector)). - **Grok and Muse:** paste the setup prompt Upsy shows into a chat and approve the sign-in ([Grok](/guides/grok/notion), [Muse](/guides/muse/notion)). Server details, such as OAuth endpoints and token lifetimes, are in the [Gmail MCP server guide](/guides/gmail-mcp-server#server-details); they're the same for Notion. ### Check that it works > Using Upsy, search my Notion for "roadmap" and summarize the most recent page you find. The agent should list matching pages, open one and summarize it. The search and the page it opened show in Upsy's **History** under that agent. ### Picking Notion tools With **Pick actions**, a sensible start is every read tool plus `notion-create-comment` and `notion-create-suggested-edit`, so an agent can look things up and propose changes you accept in Notion, but not change pages itself. Add `notion-create-pages` to let it write new pages, and leave out `notion-delete-pages`, `notion-delete-databases` and `notion-move-pages` unless it should reorganize. A tool Notion adds later stays off until you tick it. **Read-only** allows only tools Notion marks read-only, and never one whose name says it changes something, such as create, update, move or delete. ## Troubleshooting ### "Invalid MCP state. Please enable browser cookies and try again." Notion's sign-in lost its session. Allow cookies for notion.com and notion.so, clear the client's saved sign-in for Notion, and connect again. ### Guests can't connect Only workspace members can use Notion MCP. Ask a workspace owner to make you a member, or connect a workspace where you are one. ### The sign-in is blocked by your workspace On Enterprise, owners can allow only approved AI apps under **Settings › Connections › Permissions** ([Notion's help](https://www.notion.com/help/notion-mcp)). Ask an owner to approve your client, or Upsy. ### A tool says it needs a different plan Some tools and options need Business or Enterprise, sometimes with Notion AI. Ask the agent to run `notion-get-tool-access` to see what your plan allows, and use a saved view instead of SQL on other plans. ### `rate_limited` The connection went over Notion's request limit. The error includes `retry_after_seconds`: wait that long, and ask the agent for fewer calls at once. ### Codex keeps asking you to sign in Open Codex reports describe "Reauthentication required" and repeated sign-in windows with Notion ([issue #24848](https://github.com/openai/codex/issues/24848)). Run `codex mcp login notion` again, and keep one Notion entry in `config.toml`. ### `object_not_found` with the local server The page isn't shared with your integration. In Notion, open the page's **•••** menu, go to **Connections**, and connect your integration. Or switch to Notion MCP, which reaches everything you can open. ### "The user hasn't allowed you to use Notion's …" That's Upsy refusing a tool outside the agent's level, such as `notion-update-page` on Read-only. Change Notion's level on the agent's page in Upsy. ## Security and privacy - **Every option acts as you,** or as the integration for the local server. The agent sees only what that account can open. - **For a hard limit,** use Upsy's Read-only, a workspace MCP token with only read tools on Business or Enterprise, or the local server with an integration that can only read the pages you share. - **Deletes are recoverable** from Notion's Trash, but changes inside a page are only in its version history. - **Through Upsy,** agents never get your Notion token: they call Upsy, and Upsy calls Notion. Upsy emails you when one agent reads 100 or more items in 10 minutes or deletes 50 or more, and when a new agent or app connects. - **Prompt injection.** A page or comment can carry instructions aimed at your agent. Keep changes confirmed in your client, or give agents that read shared pages Read-only. ## FAQ ### What is the Notion MCP server URL? `https://mcp.notion.com/mcp`, over Streamable HTTP with OAuth. `https://mcp.notion.com/sse` is a fallback for older clients. ### What is Notion MCP? Notion's hosted MCP server. It lets AI agents such as Claude, ChatGPT, Cursor and Codex search, read and change your Notion workspace, with your permissions, after you sign in. ### Is Notion MCP free? Notion says it "works on every plan", and lists no separate charge. Some tools, such as meeting notes and search across connected apps, need Business or Enterprise with Notion AI. ### Can I use a Notion API key with Notion MCP? Not an integration token: the hosted server doesn't accept them. On Business and Enterprise, a workspace owner can create an MCP token in Notion's developer portal and send it as a bearer token. The old local server uses integration tokens. ### Is notion-mcp-server on GitHub still maintained? No. Its README says it's no longer actively maintained and points to Notion MCP. The npm package still gets occasional updates. ### Can Notion MCP delete pages? It moves pages and databases to Trash, and can restore them from there. It doesn't delete them permanently. ### Can I make Notion MCP read-only? Not a personal connection. Use a workspace MCP token limited to read tools on Business or Enterprise, or add Notion through Upsy and set it to Read-only. ### How many tools does Notion MCP have? 68 in a connection on November 2, 2026, 37 of them read-only. Notion documents 70. The full list is in [its tools](#its-tools). --- Upsy connects personal AI assistants (Muse, Grok, ChatGPT, Claude, Cursor, Claude Code, Codex, Devin) to your Gmail, Google Calendar, Google Drive, Slack, Notion and other apps through one MCP server, with a shared memory, files and a cloud browser signed in to your sites. You choose what each assistant may do in each app, see everything it did, and turn it off in one click. Upsy is free. To add Upsy to an assistant, add a remote MCP server (Streamable HTTP) named Upsy at https://upsy.ai/connect. It signs in with OAuth; there is no API key.