Notion MCP server: URL, setup, tools and the open-source version

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

Notion's setup guide has steps for more clients. Notion explains why it moved to a hosted server in 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.

Cursor. Add Notion to .cursor/mcp.json in a project, or ~/.cursor/mcp.json for all of them, then click Connect:

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

Codex. Add this to ~/.codex/config.toml, then run codex mcp login notion:

[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.

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). 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:

• 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), 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

The open-source local server

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). 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 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, ChatGPT).
• Grok and Muse: paste the setup prompt Upsy shows into a chat and approve the sign-in (Grok, Muse).

Server details, such as OAuth endpoints and token lifetimes, are in the Gmail MCP server guide; 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). 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). 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.