Connect Codex to Notion

What you get

Once it’s connected, Codex can call all 18 of Notion’s tools: search, page and database CRUD, comments, views, and workspace lookups. Notion’s supported tools page lists them as notion-search, notion-fetch, notion-create-pages, notion-update-page, notion-move-pages, notion-duplicate-page, notion-create-database, notion-update-data-source, notion-create-view, notion-update-view, notion-query-data-sources, notion-query-database-view, notion-query-meeting-notes, notion-create-comment, notion-get-comments, notion-get-teams, notion-get-users, and notion-get-async-task.

Three of those need a paid tier. Notion lists notion-query-data-sources, notion-query-database-view, and notion-query-meeting-notes as available on all plans, but says using one requires a Business plan or higher with Notion AI. On other plans, per that same page, “the tool returns an upgrade prompt.” notion-search drops off in a smaller way. Notion describes it as searching across “your Notion workspace and connected tools like Slack, Google Drive, and Jira,” but their docs say that without a Notion AI plan, search is limited to your Notion workspace only.

notion-create-pages and notion-update-page take an optional allow_async: true flag for long-running page create and update work. Set it and the call returns an async_task handle instead of blocking. You poll notion-get-async-task with that handle’s id passed as task_id until the task reports succeeded or failed.

Setup

Notion publishes a working Codex block directly in its own docs, so there’s no Claude Desktop JSON to translate this time.

1. Add this to ~/.codex/config.toml:

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

That’s the full entry. It’s a remote streamable HTTP server, so there’s no command and no args to add. Notion also publishes an SSE endpoint at https://mcp.notion.com/sse, which their docs mark as legacy, so point at /mcp. For the general block shape and the JSON-to-TOML translation table, see Connect an MCP server.

2. Authenticate:

codex mcp login notion

This opens a browser to Notion’s OAuth screen. Approve it, and Codex stores the resulting token locally for you.

3. Check it took:

codex mcp list

4. Team setup: you can commit a .codex/config.toml in the project root carrying the same [mcp_servers.notion] block. That’s a Codex config feature and Notion’s docs don’t cover it, so read the Codex side before you lean on it. Codex’s configuration reference says project-scoped config files load “only when you trust the project,” which means an untrusted checkout ignores your block and the server never shows up. The file also authenticates nobody by itself. Every teammate who pulls that config still runs codex mcp login notion on their own machine before the server does anything for them. There’s no secret sitting in the file, since the whole block is one URL.

Gotchas

Bearer tokens don’t work here, and that’s a Notion decision rather than a Codex gap. Their docs say the hosted server “requires user-based OAuth authentication and does not support bearer token authentication.” Codex’s bearer_token_env_var key works fine against other remote servers, but Notion has no token-auth path to receive it, so setting it won’t get you in. auth = "oauth" is already Codex’s default for remote servers, so you don’t need that line either. Run the login command yourself.

That’s also why this can’t live in CI or on a headless box. codex mcp login needs a browser and a person to approve the screen, and the token it hands back is stored on that machine instead of in the config file. Notion says the same thing in their own words: a user must complete the OAuth flow to authorize access, “which may not be suitable for fully automated workflows or cloud-based coding agents that run without human interaction.”

Skip the mcp-remote shim Notion’s docs mention for clients that can’t speak streamable HTTP directly (npx -y mcp-remote https://mcp.notion.com/mcp). Codex already speaks streamable HTTP natively through url =, so wrapping the connection in npx buys nothing and adds a cold start on top of a server that already answers directly. That cold-npx wait is the same handshake timeout covered on the general MCP page.

The open-source notion-mcp-server package is a separate project from the hosted server, and Notion’s docs describe it as no longer actively maintained. It does support bearer token authentication and the original v1 APIs, and it’s what Notion points at for automated workflows where OAuth isn’t feasible. You’d be self-hosting that yourself, not adding a URL to config.toml.

Two open Codex issues are worth knowing about if Notion MCP looks connected but isn’t doing anything. openai/codex#13956, “Notion MCP stuck after refresh token invalid_grant; Codex Desktop doesn’t prompt re-auth,” was opened 2026-03-08 and is still open. It describes MCP init failing with invalid_grant: Invalid refresh token while Codex Desktop neither re-runs the auth flow nor prompts you to reconnect, so a quietly expired OAuth session sits there looking configured while doing nothing. openai/codex#26760, “MCP startup suggests codex mcp login for bearer-token auth failures,” was opened 2026-06-06 against 0.137.0 and is also open. It’s the reverse mixup: a bearer-token server whose token is expired or missing gets told to run codex mcp login, which is the wrong fix for that server and confusing if you’re staring at a bearer-token server and Notion in the same config file.

Related

• Connect an MCP server: the general TOML shape and JSON translation table
• mcp_servers.<id>.url: the remote endpoint and its auth keys
• startup_timeout_sec: what governs a slow handshake
• mcp_servers.<id>.env: how secrets normally work, though Notion’s hosted server needs none
• Install Codex CLI: use this if codex mcp commands aren’t available yet