# How to set up the Notion MCP server > **Governing MCP across your organization?** > Speakeasy's [AI control plane](/product/ai-control-plane) connects, secures, and observes every agent and MCP server from one entry point — with SSO, RBAC, runtime guardrails, and a full audit trail. Notion has an official MCP server, hosted by Notion at `https://mcp.notion.com/mcp`. It works on every Notion plan, and it lets an AI agent search your workspace, read pages and databases, and create or update pages for you. This guide shows you how to connect the Notion MCP server to Claude Code and Codex. You'll add the server to your agent, sign in to Notion to approve access, and try it with a prompt that reads your workspace and one that writes to it. ## Prerequisites To follow along, you'll need: - A Notion account that's a member of the workspace you want to connect. Guests can't connect to Notion MCP. - [Claude Code](https://code.claude.com/docs) or [Codex CLI](https://developers.openai.com/codex) installed ## Connect your agent to the Notion MCP server Follow the instructions for the agent you use: [Claude Code](#claude-code) or [Codex](#codex). For any other agent, see [Connect other MCP clients](#connect-other-mcp-clients). Both agents sign in to Notion with OAuth, so you don't need to create or copy a token. Your agent gets the same access to pages and databases that you have in Notion. ### Claude Code Add the Notion MCP server to Claude Code: ```bash claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp ``` The `--scope user` option makes the server available in all your projects. Then sign in to Notion: ```bash claude mcp login notion ``` Claude Code opens the **Connect with Notion MCP** page in your browser. Under **Select workspace**, choose the workspace you want to connect. Select **I recognize and trust this URL**, then click **Continue**. ![Notion's Connect with Notion MCP page with the workspace selector, the I recognize and trust this URL checkbox, and the Continue button highlighted](/assets/mcp/using-mcp/notion-mcp/notion-consent-screen.png) The terminal confirms the sign-in: ```text Authenticated with "notion". Its tools are now available in Claude Code. ``` You can also sign in from inside Claude Code. Enter `/mcp` and follow the prompts for the `notion` server. Check that the server connects: ```bash claude mcp list ``` The `notion` server shows as **Connected**: ```text notion: https://mcp.notion.com/mcp (HTTP) - ✔ Connected ``` Start Claude Code with `claude` and ask it about a page in your workspace, for example: ```text Find my Q4 launch plan in Notion and list the tasks that aren't done yet, grouped by owner ``` Replace the page name with one of your own pages. If Claude Code asks for permission to use a Notion tool, select **Yes**. Claude Code searches your workspace, reads the page and its database, and answers. ![Claude Code finding the Q4 launch plan in Notion and listing the five open launch tasks grouped by owner](/assets/mcp/using-mcp/notion-mcp/claude-code-answer.png) ### Codex Add the Notion MCP server to Codex: ```bash codex mcp add notion --url https://mcp.notion.com/mcp ``` Codex detects that the server uses OAuth and starts the sign-in straight away: ```text Added global MCP server 'notion'. Detected OAuth support. Starting OAuth flow… ``` Your browser opens the **Connect with Notion MCP** page. Choose your workspace, select **I recognize and trust this URL**, and click **Continue**. The terminal then shows `Successfully logged in.` Check the server's configuration: ```bash codex mcp list ``` The `notion` row shows OAuth as its authentication method: ```text Name Url Bearer Token Env Var Status Auth notion https://mcp.notion.com/mcp - enabled OAuth ``` Start Codex with `codex` and enter `/mcp`. The `notion` server shows as `connected (65 tools)`. Ask Codex to add something to your workspace, for example: ```text Add a task to the Launch tasks database in my Q4 launch plan in Notion: Prepare launch email, owned by Elena Ruiz, due November 14, status Not started ``` Replace the database, page, and task details with your own. If Codex asks for permission to run a Notion tool, select **Allow**. Codex finds the database and adds the task. ![Codex calling the notion-search, notion-fetch, and notion-create-pages tools and reporting that it added the Prepare launch email task](/assets/mcp/using-mcp/notion-mcp/codex-answer.png) The new task appears in the database in Notion. ![The Launch tasks database in Notion with the new Prepare launch email task highlighted](/assets/mcp/using-mcp/notion-mcp/codex-task-in-notion.png) ## Use a Notion MCP token instead (Business and Enterprise) On Notion's Business and Enterprise plans, you can connect with an MCP token instead of signing in through the browser. This suits agents that run without a browser, such as on a server. Only workspace owners can create MCP tokens. To create one, open Notion's [Developer portal](https://www.notion.so/developers) and select **New MCP token**. Then save the token as an environment variable in your shell profile: ```bash echo 'export NOTION_MCP_TOKEN="your-notion-mcp-token"' >> ~/.zshrc ``` Replace `your-notion-mcp-token` with the token you copied. If you use Bash, write to `~/.bashrc` instead. Open a new terminal window so the variable loads. Add the server to Claude Code with the token in an `Authorization` header: ```bash claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp --header 'Authorization: Bearer ${NOTION_MCP_TOKEN}' ``` Keep the single quotes around the header. They tell Claude Code to save the variable name rather than the token itself, and Claude Code reads the token from your environment when it starts. Or add it to Codex: ```bash codex mcp add notion --url https://mcp.notion.com/mcp --bearer-token-env-var NOTION_MCP_TOKEN ``` The `--bearer-token-env-var` option tells Codex to read the token from the `NOTION_MCP_TOKEN` environment variable and send it with each request. ## Connect other MCP clients You can connect any MCP client that supports remote (Streamable HTTP) servers. Use these values: | Setting | Value | |---|---| | Server URL | `https://mcp.notion.com/mcp` | | Authentication | OAuth. The client opens Notion's sign-in page. | | Header (MCP token only) | `Authorization: Bearer ` | If your client only supports local (stdio) servers, run the hosted server through `mcp-remote` with the command `npx -y mcp-remote https://mcp.notion.com/mcp`. ## Troubleshooting ### Claude Code shows `Needs authentication` If `claude mcp list` shows this line, Claude Code has the server but isn't signed in to Notion: ```text notion: https://mcp.notion.com/mcp (HTTP) - ! Needs authentication ``` `claude mcp add` saves the server without signing in, so you see this until you complete the sign-in. Run the login command and approve access in your browser: ```bash claude mcp login notion ``` If the sign-in page opens in a browser where you aren't signed in to Notion, run `claude mcp login notion --no-browser` instead. Claude Code prints the sign-in URL, and you can open it in the browser you use for Notion. ## Next steps You now have the Notion MCP server connected to your agent. You added the server to Claude Code or Codex, approved access to your workspace in Notion, and tried a prompt that reads your workspace and one that writes to it. Your agent can search your pages, read databases, and create or update content for you. To keep going: - Connect more services to your agent with the other guides in [Connect popular MCP servers](/mcp/using-mcp/mcp-server-providers). - Learn how to get better results from your agent's tools in [Best practices for using MCP tools](/mcp/using-mcp/using-tools). - See what teams build with MCP in [MCP use cases](/mcp/using-mcp/use-cases). --- Index of every Speakeasy page for agents: [llms.txt](https://www.speakeasy.com/llms.txt). AI control plane and MCP gateway content in one file: [llms-full.txt](https://www.speakeasy.com/llms-full.txt). Any page is available as markdown by appending `.md` to its URL or by requesting it with `Accept: text/markdown`.