# Notion MCP: Connect Notion to Claude Code and Cursor URL: https://getunblocked.com/blog/notion-mcp/ Published: 2026-07-20T15:00:00Z Author: Dennis Pilarinos Categories: Context Engine, Engineering Insights Connect Notion to Claude Code and Cursor in 5 minutes via MCP. Setup for 3 clients, all 18 hosted tools, token costs, and when one connector isn't enough. --- You can connect Notion to Claude Code and Cursor in about five minutes: add the hosted server at `mcp.notion.com`, approve a browser OAuth prompt, and your agent can search your workspace, read design docs and PRDs, and create pages on its own. The Notion MCP setup is one of the smoothest in the connector space, which is exactly why most guides stop at the config snippet and call it done. This one keeps going. You get the verified config for Claude Code, Cursor, and VS Code, the hosted-versus-self-hosted call spelled out, and the two costs the search results skip: what full-page fetches do to your context window, and the difference between an agent that can read your PRD and an agent that knows the PRD is three decisions out of date. ## What is the Notion MCP server, and what can your agent do with it? Nine in ten developers, 90%, regularly use at least one AI tool at work for coding, per JetBrains' [January 2026 AI Pulse survey](https://blog.jetbrains.com/research/2026/04/which-ai-coding-tools-do-developers-actually-use-at-work/) of more than 10,000 professionals (JetBrains, 2026), and the Model Context Protocol is how those tools reach the systems around them, running in production at companies large and small per the protocol's own [2026 roadmap](https://blog.modelcontextprotocol.io/posts/2026-mcp-roadmap/) (Model Context Protocol, 2026). Notion's entry exposes your workspace as a set of those tools. The hosted server ships [18 tools](https://developers.notion.com/guides/mcp/mcp-supported-tools) (Notion, 2026): search and fetch for reading, create-pages and update-page for writing, plus database creation, views, queries, comments, and user lookups. Your agent can find the design doc for the feature it is building, pull a PRD mid-task, draft meeting notes into a new page, or query a roadmap database, all through tool calls instead of you copy-pasting page content into chat. The agent acts under your own permissions, so its reach matches yours. Two options exist for getting there, and that choice comes first. ## Which Notion MCP option should you use: hosted or self-hosted? The open-source [makenotion/notion-mcp-server](https://github.com/makenotion/notion-mcp-server) project has more than 4,000 GitHub stars and 22 tools, but the repo itself now warns that issues are not actively monitored and that Notion "may sunset this local MCP server repository in the future" (GitHub, 2026). That warning settles most of the decision. The hosted server is the default. Notion runs it, OAuth handles auth in the browser, and its tools return [Notion-flavored Markdown built for agentic systems](https://developers.notion.com/guides/data-apis/working-with-markdown-content) rather than raw block JSON (Notion, 2026). Setup is a URL, not a deployment. The self-hosted route still has a niche. It runs locally via npx or Docker, authenticates with an internal integration token instead of OAuth, and only sees pages you explicitly share with the integration, which some security teams prefer as a hard scope boundary. Pick it if you need that control or an environment where browser OAuth is impossible. Everyone else should take the hosted endpoint and move on to setup. ## How do you connect Notion to Claude Code, Cursor, and VS Code? Anthropic's own [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) uses Notion as its worked example for adding a remote server (Anthropic, 2026), so the pieces here are as standard as this ecosystem gets. The current endpoint is `https://mcp.notion.com/mcp` over streamable HTTP; a legacy `/sse` endpoint exists but the [official guide](https://developers.notion.com/guides/mcp/get-started-with-mcp) recommends the HTTP one (Notion, 2026). ### Claude Code Run one command, then authorize: ```bash claude mcp add --transport http notion https://mcp.notion.com/mcp ``` Then run `/mcp` inside Claude Code and follow the browser OAuth flow. Use `--scope user` if you want the server available in every project instead of just the current one. ### Cursor Add this to `~/.cursor/mcp.json` (or via Settings, then MCP, then Add new global MCP server): ```json {"mcpServers":{"notion":{"url":"https://mcp.notion.com/mcp"}}} ``` Restart Cursor and complete OAuth on first use. That is the entire Notion Cursor integration. ### VS Code Create `.vscode/mcp.json`: ```json {"servers":{"notion":{"type":"http","url":"https://mcp.notion.com/mcp"}}} ``` Run MCP: List Servers from the Command Palette, start the Notion server, and approve the OAuth prompt. ### Verify it works Before you build a workflow on top, run a smoke test. Ask the agent to fetch a specific page by URL and summarize it, then ask it to search for a doc you know exists by topic rather than title. If the fetch works but the search comes back thin, check whether your workspace has Notion AI enabled, since semantic search depends on it. Thirty seconds of verification here saves a confused debugging session later. In every client, the first connection opens a consent screen, and after that the agent works under your Notion account. Notion's help center is explicit about what that means: "MCP tools act with your full Notion permissions—they can access everything you can access" ([Notion Help Center](https://www.notion.com/help/notion-mcp), 2026). There is no separate service account or ACL to maintain, and nothing your agent can read that you cannot. ## What should you ask it first? The `notion-search` tool does more than title matching: with Notion AI enabled it runs semantic search across your workspace plus connected tools like Slack, Google Drive, and Jira (Notion, 2026). That makes retrieval questions the right first test. Try these, in roughly this order: - "Find the design doc for the billing migration and summarize the open questions." - "Search our PRDs for anything that mentions the export API and list what each one commits us to." - "Pull last week's platform sync meeting notes and turn the action items into a checklist page." - "Query the roadmap database for everything shipping this quarter that touches auth." The first two exercise search and fetch, the third exercises page creation, and the fourth exercises database queries. Start with reads before you let it write; you will learn its retrieval quirks with zero risk to your workspace. If you run other [MCP connectors](/blog/best-mcp-servers-for-engineering-teams-compared/) like [Jira](/blog/jira-mcp/) or [Linear](/blog/linear-mcp/) alongside it, a good compound test is asking the agent to reconcile a ticket against the PRD it came from. That is also where the cracks start to show, which we will get to. ## Hosted vs self-hosted: how the options compare The hosted server exposes 18 agent-shaped tools while the open-source local server exposes 22 API-shaped ones (GitHub, 2026), and that difference in shape matters more than the count. The table lines up the decision. | | Hosted server (official) | Open-source local server | | Hosting | Remote, run by Notion | Local, run by you via npx or Docker | | Auth | Browser OAuth, no token handling | Internal integration token in env config | | Tools | 18, designed for agent workflows | 22, mirroring the public API | | Content format | Notion-flavored Markdown | Closer to raw block JSON | | Search reach | Workspace plus connected apps with Notion AI | Only pages shared with the integration | | Maintenance | Actively developed by Notion | Repo may be sunset, issues not actively monitored | | Best for | Most teams, fastest setup | Hard scope boundaries, no-browser environments | The read-out: hosted for nearly everyone, local only when you need integration-token scoping or cannot run OAuth. Efficiency points the same way: the hosted server's Markdown format tends to mean fewer tool interactions and leaner payloads for common use cases than the API-shaped JSON of the local tools. Which brings us to cost, because there still is one. ## Why does a Notion MCP cost more tokens than you expect? Claude Code warns you the moment a single MCP tool result tops 10,000 tokens and caps output at 25,000 by default, per [Anthropic's MCP documentation](https://code.claude.com/docs/en/mcp) (Anthropic, 2026); those guardrails exist because tool definitions and intermediate results pile into context fast. A Notion connector hits both halves of that problem. First, the schema tax: in clients that load definitions upfront, 18 tool definitions ride along on every turn whether the agent calls them or not, and they stack with every other server you have loaded. Second, the page-dump tax: a fetch returns the whole page, and Notion pages are long. A 3,000-word PRD lands in context in full so the agent can use one paragraph of it. Notion's Markdown format softens this relative to raw block JSON, where a single bullet arrives wrapped in nested object structure, but the page still arrives whole. And the costs compound. If Notion sits alongside GitHub, Jira, and Slack servers in the same session, each one brings its schema and its own verbose payloads, and the agent pays the sum on every turn. The practical fix is the same one that applies to [every server in your stack](/blog/mcp-token-budget-autopsy/): run few connectors, keep them lean, and ask targeted questions so fetches stay narrow. Your context window should fund reasoning, not schemas. ## Does the connector give your agent the page, or the decision? Almost a fifth of the AI-generated code developers accept gets deleted later, and about 7% is heavily rewritten, per research cited in JetBrains' [study of AI's impact on developer workflows](https://blog.jetbrains.com/research/2026/04/ai-impact-developer-workflows/) (JetBrains, 2026). Almost right but not quite is the standing failure mode, and a Notion connector is a reliable way to manufacture that exact failure, because it hands your agent the page as written with no signal about whether the page is still true. Picture a PRD that specs three retry attempts on a flaky endpoint. The agent reads it and implements three. What the page cannot tell it: a reviewer flagged thundering-herd risk on the pull request, the team switched to exponential backoff in a Slack thread the next morning, and nobody circled back to edit the PRD. The connector did its job perfectly. The agent still shipped the superseded design, because [reading a page is not understanding it](/blog/code-isnt-context-mcp-isnt-enough/). Closing that gap is what Unblocked does: it provides institutional context for coding agents. Rather than returning one page from one silo, it unifies PRs, Slack, Jira, Notion, Confluence, and code repos, reconciles them, and serves the agent the current decision instead of the last-edited document. Ask about the retry behavior and it returns the backoff decision with the PRD, the review comment, and the thread behind it, so the agent starts from what the team actually concluded. | Approach | Conflict resolution across sources | Freshness signal | Token cost | Cross-source synthesis | | Hosted server (official) | No, returns the page as written | Last-edited date only | High, full pages per fetch | Searches connected apps but does not reconcile them | | Open-source local server | No | Last-edited date only | Higher, raw block JSON | No, Notion only | | Unblocked (context engine) | Yes, reconciled before the agent reads | Decision-aware, knows what superseded what | Lower, a curated slice instead of page dumps | Yes, Notion weighed against PRs, Slack, Jira, and code | > "You cannot make coding agents work without domain and functional context. We connected and trained Unblocked on our Code repos, Atlassian tools, Internal docs, Product Documentation, KB from Support and Slack history. When an agent asks a question, it gets the full picture — not just the code analysis, but also why decisions were made and what the constraints are. Other tools like Copilot know only the code. That's limited value. Unblocked is a game changer for Coding Agents." > > — Raphael Bres, CTO, Tradeshift ## Frequently asked questions about the Notion MCP server The questions teams ask most, answered against the current docs: the hosted endpoint is `mcp.notion.com/mcp`, OAuth is required, and the agent inherits your permissions in full (Notion, 2026). ### Is the Notion MCP server free? Notion's docs list no separate price for the hosted server, but several capabilities are plan-gated: semantic search across connected apps requires Notion AI, and cross-source queries sit behind Enterprise (Notion, 2026). Your AI client may add its own requirements; Notion's setup guide notes that remote servers in Claude Desktop are available on Pro, Max, Team, and Enterprise plans. ### Can my agent write to Notion, or only read? It can write. The hosted server includes create-pages, update-page, create-database, move-pages, duplicate-page, and comment tools, so an agent can draft docs, file meeting notes, and reorganize content, not just retrieve it. Most clients ask for confirmation before write-capable tool calls, and keeping that prompt enabled is wise until you trust the workflow. File and image uploads are not currently supported, though Notion lists them as on the roadmap. ### Can the agent see private pages and permissions-restricted content? It sees exactly what you see. Notion states that MCP tools "act with your full Notion permissions" (Notion Help Center, 2026), so private pages you can open are readable by your agent, and spaces you cannot open stay invisible. There is no separate service account to audit; access reviews for you cover the agent too. ### Should I use the hosted server or call the Notion API directly? For agent workflows, the hosted server: OAuth replaces token management, and its Markdown output costs fewer tokens than raw API JSON. Call the API directly when you are building deterministic automation, like a nightly sync script, where you control every call and an agent deciding when to invoke tools adds risk instead of value. The self-hosted server splits the difference for scoped, local setups. ## What to Connect First Wire up the hosted endpoint today; it is a five-minute job in any of the three clients above, and retrieval alone pays for the setup time. Then be deliberate about the rest of your stack: add [Slack](/blog/slack-mcp/) or [Confluence](/blog/confluence-mcp/) only when a real workflow demands it, prune tools you never call, and watch what full-page fetches do to your context budget. Then remember what you wired up. The connector gives your agent your workspace, and that is genuinely useful. But the decisions that make those pages right or wrong live in pull requests, threads, and tickets the page never mentions. When you want your agent working from what is true instead of what is written, that is a job for Unblocked, the context engine for engineering.