Notion MCP: How to Connect, Configure, and Use It (2026 Guide)

Notion MCP is Notion's official, hosted server that gives AI tools secure, OAuth-authenticated access to your Notion workspace through the Model Context Protocol. Plainly put: it lets an AI assistant like Claude, Cursor, or ChatGPT read from and write to your Notion pages and databases in real time. Notion becomes a tool the assistant can use, so you're not copy-pasting content back and forth. This guide walks through what the server actually does, how the hosted and self-hosted options differ (and which one you want), setup for every major client, the tools it exposes, and the permission and security details that start to matter once an agent, not just a person, is on the other end.

What is Notion MCP?

Notion calls Notion MCP its hosted server that gives AI tools secure access to your workspace (developers.notion.com). Notion built it, and it solves one specific problem. Instead of wiring up bespoke REST integrations, any MCP-compatible AI app connects once and can then search, fetch, create, and update content through a standardized interface.

The Model Context Protocol itself is an open standard. The official MCP site describes it as "an open-source standard for connecting AI applications to external systems" and offers the analogy that MCP is "like a USB-C port for AI applications." Anthropic introduced MCP, and the industry has adopted it broadly since. Notion MCP is Notion's implementation of that protocol.

MCP vs the plain Notion API

The plain Notion REST API maps endpoints 1:1 and returns deeply nested block JSON. Fine for traditional software. But Notion found that "the 1:1 API mapping created suboptimal experiences for AI agents, like high-context token consumption" and that "the technical barrier was too high for widespread adoption" (Notion blog). The hosted MCP server takes a different tack. It exposes a small, curated set of tools designed for LLMs and uses a token-efficient "Notion-flavored" Markdown representation instead of raw block JSON. So an agent needs fewer tool calls and burns fewer tokens. Notion puts it this way: "Markdown provides efficient content density per LLM token, requiring fewer tool interactions and less cost" (Notion blog).

What you can do once connected

Once connected, an AI client can search across your workspace, fetch and summarize pages and databases, draft new pages, update existing ones, and read or add comments. Everything stays scoped to what the authorizing user can already see. Common patterns Notion documents include workspace search and knowledge retrieval, generating PRDs and tech specs, drafting release notes, task management, and report creation (Notion MCP overview).

Hosted (remote) vs self-hosted (local) server

There are two official "Notion MCP" servers. Mixing them up is the single most common mistake.

mcp.notion.com: the hosted server (recommended)

The hosted remote server is the actively supported, recommended option. No infrastructure needed, and it uses standard OAuth. The endpoints:

• Streamable HTTP (recommended): https://mcp.notion.com/mcp
• SSE (legacy): https://mcp.notion.com/sse

One thing to know up front. The hosted server "requires user-based OAuth authentication and does not support bearer token authentication" (Notion docs). A human has to complete the OAuth flow, which means fully headless automation isn't supported here. Notion announced this hosted server in July 2025.

makenotion/notion-mcp-server: the self-hosted server

Notion also maintains an open-source local server: makenotion/notion-mcp-server, published to npm as @notionhq/notion-mcp-server. The README describes it as "This project implements an MCP server for the Notion API." It runs via stdio or Streamable HTTP and authenticates with an integration token (NOTION_TOKEN), which makes it usable for token-based, automated workflows you deploy yourself.

A word on its status, though. The README states Notion is "prioritizing, and only providing active support for, Notion MCP (remote)" and may "sunset this local MCP server repository in the future," with issues and pull requests no longer actively monitored. Its v2.0.0 migrated to Notion API version 2025-09-03, which introduced "data sources" as the primary abstraction for databases (database operations now use data_source_id instead of database_id).

Which should you choose?

• Use the hosted server if you (or your teammates) interact with Notion through a chat or IDE client and want the least-friction, permission-scoped, actively-maintained path. This is the right default for nearly everyone.
• Use the self-hosted server only if you need token-based authentication for an automated workflow with no human to complete OAuth. And accept that it's in maintenance-only mode.

How to connect Notion MCP (per client)

Below is client-specific setup for the hosted server. After you add it, your client prompts you to complete the Notion OAuth flow on first use. All snippets come from Notion's Connecting to Notion MCP guide.

Claude Code

claude mcp add --transport http notion https://mcp.notion.com/mcp

Then run /mcp inside Claude Code, see notion listed, and follow the OAuth flow. Notion also publishes an official plugin for Claude Code that bundles the MCP server with pre-built skills and slash commands.

Claude Desktop

Go to Settings → Connectors → Add Connector and enter https://mcp.notion.com/mcp. For the remote server, use Connectors, not the local claude_desktop_config.json file. Complete OAuth when prompted. Note that connector support requires a paid Claude plan.

Cursor

In Settings → MCP, add:

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

To share the config with a team, commit a .cursor/mcp.json in the project root. Restart Cursor and complete OAuth on first Notion-tool use.

VS Code (GitHub Copilot)

In .vscode/mcp.json:

{
  "servers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

ChatGPT

In ChatGPT settings, go to Connectors → Add Connector and enter https://mcp.notion.com/mcp. One caveat: ChatGPT's MCP support for Notion tends to be more retrieval-oriented, whereas Claude exercises the full read/write toolset. Your client choice is consequential.

Self-hosting with a Notion integration token

Need the token-based self-hosted server? First create an internal integration:

1. Create an internal integration at notion.so/profile/integrations.
2. Configure capabilities. Restrict to "Read content" only if you don't need writes.
3. Grant the integration access to specific pages via the Access tab (or a page's "Connect to integration" menu). An integration only sees pages explicitly shared with it.
4. Copy the integration secret (newly created tokens start with ntn_) from the Configuration tab.

Then add it to your client's config (example from the README):

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

To run it over HTTP instead of the default stdio transport:

npx @notionhq/notion-mcp-server --transport http --port 8080

A Docker Hub image (mcp/notion) is also published for containerized deployments.

The Notion MCP toolset

The hosted server exposes a small, curated set of tools rather than a full REST mirror. Core tools documented in Notion's supported-tools docs include:

| Tool | What it does | |---|---| | notion-search | Search across the workspace (and connected apps like Slack/Google Drive/Jira; full cross-tool search requires a Notion AI plan) | | notion-fetch | Retrieve page/database/data-source content and schema by URL or ID | | notion-create-pages | Create one or more new pages | | notion-update-page | Update an existing page | | notion-create-comment | Add a comment to a page or block | | notion-get-comments | Read comments on a page | | notion-get-self | Return bot/workspace info for the connection |

Reported tool counts vary by version and source. The open-source repo lists 22 tools; Notion's hosted supported-tools docs and third-party analyses describe roughly 18. So treat the exact number as version-dependent rather than fixed.

Limitations and gotchas

Be honest with yourself about the hosted server's constraints, documented in StackOne's deep dive and Notion's docs:

• OAuth only, no bearer tokens. A human has to be present to authorize, so headless/cloud agents can't use the hosted server directly.
• No file or image uploads/access via MCP. Neither official implementation exposes file access.
• Rate limits apply. Roughly 180 requests/minute on average (3 req/sec) general, with search capped at about 30/minute (Notion supported-tools docs).
• Read-heavy. Retrieval, search, and Q&A are handled well. Block-level surgical editing is out of scope, and for simple edits the server may load and replace an entire page, which can clobber concurrent edits.
• Some content is omitted. Per StackOne's analysis, certain content (such as meeting-notes transcripts) can come back omitted via notion-fetch, with only partial workarounds available.

Security and permissions

The MCP server honors the authorizing user's existing Notion permissions. It returns whatever that user can see, which may include PII, credentials, or source code in connected pages (Strac). Notion's own help docs say "MCP tools act with your full Notion permissions—they can access everything you can access" (Notion Help). The server adds no permission layer of its own. Security comes down to what the OAuth'd user can access and how the client behaves.

Notion's guardrails include OAuth that respects (doesn't bypass) existing permissions, plus Enterprise-gated MCP governance that lets admins allow-list which AI apps and MCP clients may connect. Notion says it "blocks every call from any AI app or MCP client that is not on the approved list" (Notion Help). Many clients also surface a confirmation step before non-read-only tool calls, though the exact behavior depends on the client.

These guardrails exist for a real reason. In September 2025, security researcher Abi Raghuram (CodeIntegrity) demonstrated a "lethal trifecta" prompt-injection attack: a PDF with hidden white-on-white text injected instructions into Notion's AI agent, causing it to extract sensitive client data (such as names, companies, and ARR) and exfiltrate it via a crafted URL through the search tool (Simon Willison, Bruce Schneier). The lesson is blunt. Untrusted content plus tool access plus outbound communication is a dangerous mix. Practice least privilege: scope integration tokens to "Read content" when writes aren't needed, share only the specific pages an agent requires, never run --unsafe-disable-auth outside an isolated network, and keep ntn_ secrets out of version control.

Troubleshooting

Common issues and fixes:

• Invalid token / auth errors: regenerate or re-validate the integration token.
• Server won't start: check the JSON config syntax and restart the client.
• Page not found / access denied: share the page with the integration and allow time for propagation.
• 429 rate-limit errors: add a small delay between requests and use retry with backoff.

Notion MCP for autonomous agents: beyond chat

Almost every guide above quietly assumes a human typing prompts into Claude or Cursor. But MCP was designed for an agent, not a person, to be the caller. That changes the engineering problem.

When an event-triggered agent is the client, the hosted server's OAuth-only, no-bearer-token model is the first wall you hit. There's no human to click "Authorize," so you either self-host the token-based server or broker auth some other way. Notion's ~180/30-per-minute limits, comfortable for one person, become a budget you have to ration across many concurrent agent runs. And because writes can execute without a confirmation step in some clients, autonomous agents need idempotent operations and explicit guardrails so a retried tool call doesn't duplicate pages or overwrite a teammate's edits.

This is the operating reality behind gamut.so and Datawizz, an AI agent knowledge workforce where agents use MCP servers like Notion's as tools to act on external systems, triggered by events and acting through APIs. Mapping a new CRM record or a merged pull request to a Notion MCP tool call is easy in a demo. Doing it reliably across an agent fleet is where the auth model, rate budgeting, and write-safety details above stop being footnotes and become the whole job.

FAQ

What is the Notion MCP server? It's Notion's Model Context Protocol implementation, a bridge that lets AI assistants read from and write to a Notion workspace in real time. The hosted version lives at https://mcp.notion.com/mcp.

How do I connect Notion MCP to Claude? In Claude Desktop, use Settings → Connectors and enter the URL. In Claude Code, run claude mcp add --transport http notion https://mcp.notion.com/mcp, then /mcp, then complete OAuth.

What's the difference between the hosted and self-hosted server? The hosted server (mcp.notion.com/mcp) is actively maintained, OAuth-based, and needs no infrastructure. The open-source local server supports bearer-token auth and self-deployment but is in maintenance-only mode and may be sunset.

Does Notion MCP require OAuth or an integration token? The hosted server requires user-based OAuth and doesn't support bearer tokens. The self-hosted server uses an integration token (NOTION_TOKEN).

Can an AI write to my Notion pages? Yes. Once connected, the AI can create and update pages within the authorizing user's permissions. With some clients, writes may execute without a separate confirmation step, which matters for automation safety.

Is Notion MCP free? The MCP server itself is free. Some clients require paid plans to use connectors, full cross-tool search requires a Notion AI plan, and admin governance of MCP is an Enterprise feature.

Is the open-source Notion MCP server still maintained? No. Notion states it's only actively supporting the remote hosted server and may sunset the local repository.