From your AI assistant
From Notion
Manual setup
Connect from your AI assistant
Open your AI assistant’s connector or plugin library and search for Notion. Select it and follow the prompts to authorize access to your Notion workspace. After you authorize the connection, your AI assistant can read and update content that you can access in the selected workspace. If Notion isn’t listed, check whether your assistant supports adding a custom MCP server and follow manual setup.Connect from Notion
In Notion, open Settings → Notion MCP and browse the directory. Select your AI assistant and follow its connection instructions.Manual setup
Use these instructions if you’re adding Notion as a custom MCP server or configuring a client directly. The remote server URL ishttps://mcp.notion.com/mcp.
Codex
Claude Code
Cursor
fx
Hermes
Devin
Pi
VS Code
Antigravity
Other MCP clients
Codex (ChatGPT)
Codex is OpenAI’s coding agent. See the Codex MCP documentation for more details.command not found, make sure codex is on your PATH.~/.codex/config.toml:Project-level configuration
Project-level configuration
.codex/config.toml file in your project root with the same server configuration.Claude Code
Claude Code is Anthropic’s agentic coding tool for the terminal. See the Claude Code MCP documentation for more details.command not found, make sure claude is on your PATH./mcp in Claude Code and following the OAuth flow.
Using --scope flag for different installation scopes
Using --scope flag for different installation scopes
--scope local(default): Available only to you in the current project--scope project: Shared with your team via.mcp.jsonfile--scope user: Available to you across all projects
/mcp command to list and manage the MCP servers you have installed, and use the /context command to understand the context token usage of your current session, including the number of tokens used by each MCP server that’s enabled.
Cursor
Cursor is an AI code editor that can connect to MCP servers. See the Cursor MCP documentation for more details..cursor/mcp.json file in your project root:Global configuration
Global configuration
~/.cursor/mcp.json:fx
fx is a CLI coding agent from Vercel Labs. See the fx MCP documentation for more details./mcp login notion.
JSON configuration
JSON configuration
~/.fx/mcp.json:/mcp command. Then run /mcp login notion.Hermes
Hermes is a coding agent from Nous Research that can be extended with MCP servers. See the Hermes MCP documentation for more details.~/.hermes/config.yaml:Global configuration
Global configuration
~/.hermes/config.yaml configuration above applies to all projects for the current Hermes profile. See the Hermes configuration documentation for more details.Devin
Devin is an AI software engineering agent that can connect to custom MCP servers. See the Devin MCP documentation for more details.Pi
Pi is an open-source, terminal-based coding agent. It uses the third-party Pi MCP Adapter to connect to MCP servers./mcp setup, then choose Notion to add the server./mcp-auth notion and completing the OAuth flow to connect your Notion workspace.Global and team configuration
Global and team configuration
~/.config/mcp/mcp.json. To share it with a team, commit the same configuration in a project-root .mcp.json; each teammate then completes the OAuth flow locally.VS Code (GitHub Copilot)
Visual Studio Code supports MCP servers in its agent customization experience. See the VS Code MCP documentation for more details..vscode/mcp.json file in your workspace:Cmd+Shift+P / Ctrl+Shift+P) and run MCP: List ServersUser-level configuration
User-level configuration
Antigravity
Antigravity supports MCP servers across its products. See the Antigravity MCP documentation for more details. We recommend connecting to Notion MCP as a custom server rather than using the pre-configured “Notion” connector in the Antigravity MCP gallery, which uses the deprecatednotion-mcp-server package.
mcp_config.json:Other MCP clients
Add Notion as a remote MCP server with the Streamable HTTP transport and the URLhttps://mcp.notion.com/mcp.
Migrate from the legacy SSE endpoint
Notion will retire the legacy HTTP with Server-Sent Events (SSE) endpoint,https://mcp.notion.com/sse, on February 23, 2027. Update your client before that date.
In your client’s Notion server settings, change the transport from SSE to Streamable HTTP and replace the URL with https://mcp.notion.com/mcp. Save the settings, sign in again if prompted, and check that the client lists Notion tools. If your client only offers SSE, update it to a version that supports Streamable HTTP.
JSON configuration
If your client accepts a JSON configuration, start with Streamable HTTP:Troubleshooting
An enterprise policy blocks the connection
An enterprise policy blocks the connection
My MCP client doesn't support remote MCP servers
My MCP client doesn't support remote MCP servers
Authentication issues
Authentication issues
- Complete the OAuth flow when prompted.
- Disconnect and reconnect the client. Look for Clear authentication or Disconnect in its MCP settings.
- Check your permissions in the Notion workspace that you’re trying to access.
My MCP client isn't listed here
My MCP client isn't listed here
FAQs
Which Notion plans can use Notion MCP?
Which Notion plans can use Notion MCP?
- MCP tokens: Business and Enterprise. Only workspace owners can create them.
- Enterprise-managed authorization: Enterprise, with SAML SSO.
- Connected-source search with
notion-connector-search: Business or Enterprise with Notion AI.notion-searchsearches Notion on every plan. - Database queries with
notion-query-data-sources: querying a saved view works on every plan. SQL queries are unlimited on Business or Enterprise with Notion AI. Other plans get a limited number of SQL queries on one data source at a time. - Some search filters, such as last edited by and last edited date: Business and Enterprise. On other plans these filters are dropped, and the result says so.
- Request limits: higher on Business and Enterprise. See rate limits.
Can workspace guests use Notion MCP?
Can workspace guests use Notion MCP?
Does Notion MCP support file uploads?
Does Notion MCP support file uploads?
notion-create-file-upload tool to upload images and other files up to 20 MiB. Workspace file-size limits still apply.The tool returns a short-lived upload URL and the headers and form field that the MCP client must use to send the file. After the upload succeeds, pass the response’s suggested_markdown directly to notion-create-pages or notion-update-page, or include it on a separate line in notion-create-comment markdown to attach the file. For larger files, use the file upload API.What's the difference between Notion MCP and the open-source server?
What's the difference between Notion MCP and the open-source server?
https://mcp.notion.com/mcp) is our hosted, actively maintained server. It supports OAuth authorization and MCP tokens, and requires no infrastructure setup.The open-source server (notion-mcp-server) is no longer actively maintained. It authenticates with an integration token and requires you to manage your own connection and deployment.For most users, we recommend Notion MCP.I'm building my own MCP client
I'm building my own MCP client