Notion MCP Server Setup for Content Teams

Content teams working in AI tools today face a structural problem: brand and content context lives in Notion, but every AI session starts from scratch, dependent on whatever someone remembers to paste in. Guidelines, messaging frameworks, content calendars, and approved copy sit in a Notion workspace, but none of it is reachable by an AI agent without someone manually copying it into the prompt window each time.

AI tools work without the information they need, which produces off-brand output even though a well-documented Notion workspace already contains everything an agent would need to stay on-brand. The gap is the connection, not the content. That distinction matters because it points to a fix that doesn't involve rewriting style guides or retraining anyone on prompt technique. Model Context Protocol (MCP) closes that gap: it lets AI agents query live workspace data directly, so they don't depend on whatever fragment happened to get pasted in before the draft started.

What Notion's hosted MCP server does

Notion's hosted MCP server is a different product from the company's first attempt at this problem, and the distinction shapes how a content team should configure and trust it. The original open-source notion-mcp-server, released in April 2025, demanded real technical setup: creating a Notion API integration, copying an API key into MCP headers, or building a Docker image just to get a connection running, a barrier that kept adoption mostly within developer teams. That version parsed Notion's public OpenAPI spec under the hood, and it turned tool calls into ordinary HTTP API calls. It functioned as a pass-through layer rather than an interface built for how an AI agent actually reasons.

The hosted server works differently. It exposes AI-first tools instead of wrappers bolted onto REST endpoints, built in coordination with the team behind Notion's in-app Notion Agent, so the tool design reflects how an agent plans and reasons through a task, not how an HTTP request happens to be structured. Notion can update these tools centrally, so improvements reach every connected client without anyone updating a local package. The server supports both streamable HTTP and SSE (server-sent events) transport protocols, so between them they cover the range of MCP clients a content team is likely to already have installed.

Notion MCP server read and write capabilities

Before configuring anything, a content team needs a clear picture of what the server can actually do, because that picture determines what gets exposed and what stays out of reach. The server organizes its capabilities into four categories of operations that AI clients can invoke: search and retrieval across pages, databases, and connected sources; content and file operations, including creating and modifying pages and handling attachments; database operations, covering database creation, data source queries, view management, and property updates on database pages; and workspace operations, which include comments, users, teams, and meeting notes.

What separates this from a traditional API integration is bidirectionality paired with real-time access. An AI client connected through MCP doesn't just pull a snapshot of a page as it existed at export time. It reasons over live workspace data and can modify content directly, which is what makes a handful of content workflows possible. An agent can process a meeting transcript and create a structured page in a meeting notes database immediately after the call ends. It can take an unstructured brief or a rough draft and populate a content calendar entry with the correct fields already filled in. It can answer a question like "what does our tone guide say about using contractions?" by reading the live tone guide page, rather than reciting something stale that was pasted into a prompt three weeks earlier.

That write access is also where the risk sits. The same connection that lets an agent create a page can update or delete content it has been authorized to touch, with no separate confirmation step beyond whatever the client itself provides. Scope decisions, meaning which capabilities an integration holds and which pages it can see, need to be settled before any client is configured.

Permissions and access scope decisions to make before running a single command

The most consequential choices in this entire setup happen before a single client is configured: which capabilities the integration is granted, and which pages it is allowed to see. Treat every capability grant as a minimum-viable-access decision, because it isn't a convenience setting.

Read content is the baseline capability, required for search, page reads, database retrieval, and any query-based use case, and it's the only capability a research or lookup workflow actually needs. Insert content is required separately, for creating new pages or database items and appending blocks to existing ones. Update content is a further separate grant, needed for editing existing pages, blocks, and database schemas. Read comments and insert comments only matter if the workflow actually involves comment threads, and user information access is only relevant when the agent needs to look up workspace members. A read-only integration built purely for research and retrieval needs nothing more than read content enabled. Write capabilities belong in a separate integration with a narrower page scope, not bundled into the same connection by default.

Page-level access works the same way: it is explicit, and an integration cannot see a page unless that page has been shared with it directly. That sharing cascades, though, which deserves attention. Because sharing cascades from parent to children, a connection added to a parent page automatically grants access to that page's children, so sharing something as broad as a top-level "Brand Guidelines" section opens everything nested underneath it, including pages the team may not have intended to expose. There is no operational reason to expose HR documents, financial records, or personnel files to an integration whose entire job is drafting marketing copy, and the cascading nature of page-level sharing makes it easy to do so by accident if the scoping isn't deliberate.

If your team uses Devin or similar organization-level agent connections, the choice between Personal access and Organization access has real consequences. With Organization access, every member shares a single authenticated connection, so you should run it through a dedicated Notion service account rather than any individual's personal login, and someone holding Manage MCP Servers permission has to complete the OAuth flow. With Personal access, each team member authenticates their own Notion account separately, so access stays tied to individual identity.

Build at least two integrations, one read-only for lookup and research, one read-write for content creation, rather than a single integration carrying full permissions across the entire workspace. Splitting access this way means a research-only session can never accidentally overwrite a database, and a drafting session never has more reach into the workspace than the task in front of it requires.

Step-by-step setup for the clients content teams use

Once the permissions decisions above are settled, setup itself takes only a few minutes in any major MCP client. The differences between clients are mostly structural, concerning where the configuration file lives and how the OAuth flow gets triggered, rather than anything conceptually different from one tool to the next.

Claude Code

Claude Code is Anthropic's agentic coding tool for the terminal. Add the server by running this in a terminal:

claude mcp add --transport http notion

Then authenticate by running /mcp in Claude Code and following the OAuth flow. The --scope flag controls how widely the connection applies: --scope local (the default) keeps it available only to the current project on the current machine, --scope project shares it with the whole team through a .mcp.json file, and --scope user makes it available across all of a single person's projects. You can also add a Notion plugin for Claude Code, and it adds the MCP server alongside Skills and slash commands built for common Notion workflows.

Cursor

Cursor is an AI code editor with native MCP support. Create .cursor/mcp.json in the project root:

{ "mcpServers": { "notion": { "url": "<notion-mcp-url>" } } }

Open Customize in Cursor's sidebar, enable Notion, and complete the OAuth flow. For a configuration that applies across every project rather than just one, add the same block to ~/.cursor/mcp.json instead.

VS Code (GitHub Copilot)

Create .vscode/mcp.json in the workspace:

{ "servers": { "notion": { "type": "http", "url": "<notion-mcp-url>" } } }

Open the Command Palette (using your platform's standard keyboard shortcut), run MCP: List Servers, start the Notion server, and complete the OAuth flow. For a setup that spans every workspace rather than just one, run MCP: Open User Configuration from the Command Palette instead.

Codex

Codex is OpenAI's coding agent. Add the server to ~/.codex/config.toml:

[mcp_servers.notion]
url = "<notion-mcp-url>"

Authenticate by running codex mcp login notion and completing the OAuth flow. If you want team sharing, create a .codex/config.toml file in the project root carrying the same configuration.

Devin

Devin is an AI software engineering agent. Enter "Notion" as the server name, select HTTP as the transport, set the URL to the standard Notion MCP address, and select OAuth as the authentication method. From there, choose between Personal access, where each member authenticates individually, and Organization access, where the whole team shares one connection through a service account.

Antigravity

Notion recommends connecting as a custom server rather than relying on the pre-configured "Notion" connector listed in the Antigravity MCP gallery, since that gallery connector still points to the deprecated notion-mcp-server package. Add the server manually through mcp_config.json, and use the same standard URL you use across every other client.

A Notion MCP connection configured on a single laptop is still functionally the same prompt-pasting workflow at team scale, just with one fewer person doing the pasting. The real value of this setup compounds only once the configuration itself is shared, so every team member is working against the same server, the same scoping, and the same permissions, rather than each person building their own slightly different connection.

Most MCP clients let you commit a configuration file directly to the project repository, so every team member can pick up an identical server setup the moment they clone the project. In Claude Code, this means committing .mcp.json to the project root using --scope project, after which each teammate still completes their own individual OAuth flow locally. Codex works the same way: commit .codex/config.toml to the project root with the server configuration already written in, and each teammate runs codex mcp login notion to authenticate on their own machine. Pi follows the identical pattern, with .mcp.json committed at the project root and each teammate completing the OAuth flow locally.

The shared file handles the configuration; the individual OAuth flow handles identity and access control. That split is what makes the setup both consistent across a team and accountable to each person using it: the connection itself is standardized, but the permissions tied to each person's Notion account remain their own.