How to connect Claude to Notion with MCP: setup, permissions and tests

Point Claude at Notion's hosted MCP server, https://mcp.notion.com/mcp, and approve access with OAuth. In Claude.ai or Claude Desktop, add Notion from the Connectors section or as a custom connector. In Claude Code, run one claude mcp add command, then type /mcp to sign in. Claude then works with whatever your Notion account can see.

This tutorial is one step in the path laid out in AI engineering for GTM operators: once Claude can read and write your workspace, Notion becomes the context your workflows run on.

Key points

• Notion runs the MCP server for you: "a remote MCP server hosted by Notion," per its docs.

• Claude.ai, Claude Desktop and Claude Code all connect to the same server URL. Only the setup screen differs.

• Claude acts with your permissions. Notion's help center says MCP tools "can access everything you can access."

• Test reads first, then writes on a scratch page, before touching real databases.

• Only connect trusted servers, and leave "Allow always" off for write tools until you trust the workflow.

What is Notion MCP, and how does it differ from a Claude connector?

Notion MCP is the server; a Claude connector is how Claude plugs into it. They are two halves of one connection, not two competing options.

The Model Context Protocol site defines MCP as "an open-source standard for connecting AI applications to external systems," and compares it to "a USB-C port for AI applications."

The Notion MCP overview explains the Notion side: "After you authorize a connection with OAuth, the MCP client can use Notion MCP tools to read and update content that you can access." Claude is the MCP client.

Four terms get mixed up:

For almost everyone, the answer is the hosted server. Notion's connection guide says of the hosted option: "For most users, we recommend Notion MCP."

How do you connect Notion in Claude.ai or Claude Desktop?

Add Notion as a connector, sign in to Notion when prompted, then switch it on in the chat where you want to use it.

Notion's help center page on Notion MCP says "Some tools list Notion in a directory for one-click setup, and others support a custom MCP connector." Claude supports both routes.

Route A: the connectors directory

Anthropic describes the connectors directory as "a curated collection of recommended tools that you enable to extend Claude's capabilities."

1. In a chat, click the + button in the lower left, hover over Connectors, and choose Manage connectors.

2. Click the + button next to Connectors and find Notion in the list.

3. Review its capabilities, click Connect, then approve the Notion OAuth screen for your workspace.

4. Back in a chat, open + then Connectors and toggle Notion on for that conversation.

On Team and Enterprise plans, an owner first adds it from Organization settings > Connectors with Add to your team. Anthropic notes this "doesn't automatically grant anyone access," so each person still signs in.

Route B: a custom connector

If Notion is not listed for your account, add the server URL yourself. Anthropic's custom connector guide gives these steps for Pro and Max plans:

1. Go to Customize > Connectors, click + Add, then Add custom connector.

2. Name it Notion and paste https://mcp.notion.com/mcp as the remote MCP server URL.

3. Review the authentication settings Claude detected, choose a sign-in option, and click Add.

4. Complete the Notion OAuth flow.

On Team and Enterprise plans, an owner adds it under Organization settings > Connectors, then each member clicks Connect to sign in.

How do you connect Notion in Claude Code?

Run one command, then sign in from inside Claude Code. Notion's guide and Anthropic's Claude Code MCP docs both use Notion as the worked example.

1. Add the server. In your terminal, run claude mcp add --transport http notion https://mcp.notion.com/mcp.

2. Sign in. Start Claude Code and type /mcp. Anthropic's docs say to "follow the steps in your browser to log in," and that "Authentication tokens are stored securely and refreshed automatically."

3. Check the connection. Run claude mcp get notion. The status should read Connected, not Needs authentication.

4. Watch context use. Notion suggests the /context command to see how many tokens each enabled MCP server uses.

Pick a scope when you add it:

Use user scope if Notion is your second brain across every repo. Use project scope when a team repo should ship with Notion wired in; Claude Code "prompts for approval in interactive sessions before using project-scoped servers from .mcp.json files."

Notion's guide also points to an official Notion plugin for Claude Code that adds Skills and slash commands. To write your own, the guide on how to create a Claude skill walks through the SKILL.md format.

What can Claude read and write in Notion?

Anything your Notion account can reach, through a fixed set of tools. Notion's help center is direct about it: "MCP tools act with your full Notion permissions," and "MCP does not bypass Notion permissions."

The supported tools reference lists what Claude can call. The main groups:

• Search and read. notion-search "Searches Notion pages and databases," and notion-fetch "Retrieves content from a Notion page, database, data source, or saved database view by its URL or ID."

• Create and edit. notion-create-pages, notion-update-page and notion-create-database write pages and databases.

• Query data. notion-query-data-sources can "Query Notion data sources with SQL, read rows from one data source, or run a saved view."

• Delete. notion-delete-pages moves "up to 20 Notion pages to Trash." The call must set user_confirmed: true, and Notion marks it destructive so clients that honor that flag ask first.

Some tools depend on your Notion plan. Notion's connection guide says "Notion MCP works on every plan," but connected-source search with notion-connector-search needs Business or Enterprise with Notion AI, and MCP tokens for connections without a browser sign-in are Business and Enterprise only.

One more limit: "Only workspace members can connect Notion MCP." Notion refuses guests.

How do you test that the connection works?

Run three prompts in order: one that reads, one that writes to a scratch page, and one that queries a database. If all three pass, the connection is ready for real work.

Create an empty page called "MCP test" first. Then try these:

Swap "Tasks" for any database you own. If the read works but the write fails, the issue is usually page permissions, not the connection.

Watch the approval prompts as the tools run; they show which tool Claude picked. Once the tests pass, the guide on how to test an AI workflow before trusting it covers turning these one-off checks into repeatable evals.

What should you build once it works?

Start with one workflow where Notion already holds the source of truth, and let Claude read from it before you let it write.

Good first workflows for operators:

1. Meeting notes to tasks. Claude reads a notes page and creates rows in a tasks database.

2. Weekly status. Claude queries a projects database and drafts a summary page.

3. SOP lookups. Claude answers questions from your process pages.

Results depend on how well your pages are written. Notion's help center says "AI apps rely on clear page titles to understand your content structure." That is context engineering in practice. Once a process page is clear enough for Claude to follow, the next step is turning that SOP into an AI workflow. For the bigger design, see building a company second brain in Notion for AI agents.

I build these systems for my own work, with Claude reading and writing a Notion workspace through MCP. I do the same for SaaS revenue teams, covering lead routing, CRM cleanup and pipeline reporting, in a 90-day AI RevOps Sprint for Series A and B SaaS. Contact me to get yours scoped.

Once Claude can read the workspace, the payoff comes from consolidating scattered docs into one canonical page per topic that every agent reads.

How do you fix common connection problems?

Most failures are sign-in issues, client support gaps or rate limits.

• Authentication fails or loops. Notion's fix: complete the OAuth flow, then "Disconnect and reconnect the client. Look for Clear authentication or Disconnect in its MCP settings." In Claude Code, that option sits in the /mcp menu.

• Your client does not support remote servers. Notion suggests the mcp-remote bridge, running npx -y mcp-remote https://mcp.notion.com/mcp as a local stdio server.

• Streamable HTTP is not supported. Use the SSE fallback, https://mcp.notion.com/sse, "only if the client doesn't support Streamable HTTP."

• Rate limit errors. Notion MCP "retries a rate limit once when the wait is 2 seconds or less" and otherwise returns an error. Notion's advice is to prompt the model "to reduce parallel operations, or try again later."

• Large pages get cut off. Claude Code warns when MCP tool output exceeds 10,000 tokens and caps it at 25,000 tokens by default, adjustable with the MAX_MCP_OUTPUT_TOKENS variable.

What security steps should you take?

Treat the connection like handing an assistant your Notion login. Five steps keep it safe:

1. Connect only to the official URL. Anthropic's custom connector guide says "Only connect Claude to servers built and hosted by organizations and applications you trust." Type the Notion URL yourself.

2. Read tool calls before approving. The same guide warns that "Malicious MCP servers may include hidden instructions that try to make Claude perform unintended actions," and says to click "Allow always" only for a server and tool "that you trust to run unsupervised."

3. Watch for prompt injection. The Claude Code docs warn: "Servers that fetch external content can expose you to prompt injection risk." A Notion page pasted from the web can carry instructions too.

4. Turn off tools you do not need. Anthropic suggests disabling tools a conversation does not need, and turning off write tools when you use Research.

5. Use admin controls on team workspaces. Notion's overview says owners can manage MCP client access in Settings, and "Limiting which clients members can connect needs the Enterprise plan."

If you are rolling Claude out to a whole team, the guide on rolling out Claude to your team securely covers policies and access beyond this one connector.

A simple protocol keeps any Notion source of truth current: one canonical document per domain, a version stamp on every edit, and agents that re-read the source each run instead of relying on memory.

What are the common mistakes?

Most come from skipping tests or giving Claude more reach than the task needs.

1. Installing the old open-source server. It needs an integration token and is no longer maintained. Use the hosted URL.

2. Connecting with a guest account. Guests cannot authorize Notion MCP. Ask to be added as a member.

3. Testing on real databases first. A bad write to a live pipeline database costs more than a scratch page.

4. Clicking "Allow always" on day one. Approve write tools one call at a time until you have seen how Claude uses them.

5. Forgetting scope in Claude Code. A local-scope server will not appear in other projects. Re-add it with user scope.

FAQ

Does Notion MCP work on a free Notion plan?
Notion's connection guide says "Notion MCP works on every plan." Some features, such as connected-source search and MCP tokens, need Business or Enterprise.

Do I need to install anything to connect Claude to Notion?
Not for Claude.ai or Claude Desktop. Claude Code needs one claude mcp add command.

Can Claude delete my Notion pages?
Claude can move pages to Trash with notion-delete-pages, but the call requires user_confirmed: true and items can be restored from Trash.

Can Claude see pages I have not shared with it?
No. Claude sees what your account can see. Notion's help center says MCP tools "can access everything you can access," and nothing more.

Which Claude plans support custom connectors?
Anthropic lists Free, Pro, Max, Team and Enterprise, and says "Free users are limited to one custom connector."

What is the difference between /mcp and claude mcp add?
claude mcp add registers the server in your config from the terminal. /mcp runs inside Claude Code to sign in, check status and clear authentication.

Want help wiring Claude into your workspace?

If you are connecting Claude to Notion for a team and want help with structure, permissions or the first workflow, see how I work. You can also book a short intro call and bring the Notion database you want Claude to work from first.

Running revenue at a Series A or B SaaS company? Ask about the 90-day AI RevOps Sprint. I take two clients at a time.

About the author: Kevin Payne is an AI engineer and GTM operator who installs AI workflows for B2B teams. He has 10+ years in B2B SaaS demand generation and RevOps across Techstars, a16z and YC portfolio companies, and his writing has appeared in HubSpot, GetResponse, Outbrain and more.