Last updated July 2026
Setup Guide

Connect Codex to Notion

A friendly setup guide for Shoutout Digital account managers, client operations managers, and social media strategists on Mac and Windows. No technical experience required.

Role-based access Read, update & comment ~15 minutes

Here's how it works: Codex can read the Notion pages your role is allowed to see and, when your connection has write access, it can update cards, add comments, and create tasks for you. Account managers and client operations managers use one personal connection. Social media strategists use two connections: one for reading shared reference information and one limited to Social Media Board updates. Codex uses the permissions assigned to your connection, so always review a proposed change before approving it.

What you need before you start

  • Codex installed and working on your computer
  • Your Mac or Windows computer with permission to install an application
  • Codex installed and signed in
  • Your private setup file or token for your role
  • For strategists only: the shared read-only reference token and your personal Social Media Board token

Use the setup file and token provided for your role.

Be very specific before asking Codex to make a change. Always write the full client name (for example, Absolute Dental West Perth), the exact task board or database (for example, Action Items Board), the exact task-card name, the assignee’s full name, and the exact status or update you want. Ask Codex to show the cards it will change first, check that list yourself, then confirm. Otherwise it may update more records than you intended.

Choose your role

Account manager

Use one personal connection with write access. You can ask Codex to update the Video Shoot Tracker, add links to asset folders, create client task cards, and assign work.

Follow the one-connection setup ↓

Client operations manager

Use one personal connection with write access. You can ask Codex what needs follow-up, add comments, update task details, and create or assign operational tasks.

Follow the one-connection setup ↓

Social media strategist

Use two connections: the shared read-only connection for reference boards, plus your personal write connection for the Social Media Board only.

Follow the two-connection setup ↓

Install Node.js

  • Open nodejs.org/en/download.
  • Download the version marked LTS for your computer.
  • Mac: open the downloaded .pkg file and continue through the installer.
  • Windows: open the downloaded .msi file, choose the default options, and complete the installer.
  • Close and reopen Codex after installation.
What is Node.js? It is a widely used helper program that lets Codex run the small Notion connection. Downloading the LTS version from the official nodejs.org website is not a virus and is not intended to harm your computer.
You have nothing to worry about
Already have Node.js? You can skip the download. If unsure, installing the current LTS version is fine.

Open your Codex configuration file

Choose your computer below. You will paste one short command. It automatically opens the correct file—no searching through hidden folders or creating files manually.
⌘
I use a Mac
Open the file with Terminal
  1. 1
    Press Command ⌘ + Space to open Spotlight.
  2. 2
    Type Terminal, then press Return.
  3. 3
    Copy the command shown below, paste it into Terminal, and press Return.
  Terminal
yourname@Mac ~ %
mkdir -p ~/.codex; touch ~/.codex/config.toml; open -e ~/.codex/config.toml
TextEdit opens the correct config.toml file automatically.
⊞
I use Windows
Open the file with PowerShell
  1. 1
    Click Start or press the Windows key.
  2. 2
    Type PowerShell, then open Windows PowerShell.
  3. 3
    Copy the command shown below, paste it into PowerShell, and press Enter.
Windows PowerShell
PS C:\Users\YourName>
New-Item -ItemType Directory -Force "$HOME/.codex"; notepad "$HOME/.codex/config.toml"
Notepad opens. If asked to create the file, click Yes.
If the file already contains writing, leave it there. Click at the very bottom and press Enter once to add a blank line. Then follow the section immediately below that matches your role.

If you are an account manager or client operations manager

Stop here if this is your role. You need one connection only. Do not continue to the strategist two-connection step below.

You have just opened your config.toml file. Now copy the block below, paste it at the bottom of that open file, and replace the green words with your personal token. Keep the quotation marks.

Copy and paste into the open file
[mcp_servers.my_notion] command = "npx" args = ["-y", "@notionhq/notion-mcp-server"] [mcp_servers.my_notion.env] NOTION_TOKEN = "PASTE_YOUR_ROLE_TOKEN_HERE"
⌘
Mac
Finish this step
  1. 1
    Replace the green words with your personal token.
  2. 2
    Press Command ⌘ + S, close TextEdit, then fully quit and reopen Codex.
  3. 3
    Start a new Codex task and paste the test prompt below.
⊞
Windows
Finish this step
  1. 1
    Replace the green words with your personal token.
  2. 2
    Press Ctrl + S, close Notepad, then fully quit and reopen Codex.
  3. 3
    Start a new Codex task and paste the test prompt below.
Copy this test prompt
Use my Notion connection to find one task for [CLIENT NAME]. Show me the title, status, due date, assignee, and link. Do not make any changes.

The prompt is the same on Mac and Windows. Only the file-opening and save keys are different.

Add both Notion connections — strategists only

You do not need to understand the code below. Copy it exactly, replace the two placeholder tokens, and save the file.

Strategists use two tokens: the first is for looking things up; the second is your personal token for Social Media Board updates. If you are an account manager or client operations manager, use the one-connection setup above instead.

Copy into config.toml
# 1. Read-only reference access [mcp_servers.notion_reference] command = "npx" args = ["-y", "@notionhq/notion-mcp-server"] [mcp_servers.notion_reference.env] NOTION_TOKEN = "PASTE_SHARED_READ_ONLY_TOKEN_HERE" # 2. Your personal Social Media Board access [mcp_servers.social_board] command = "npx" args = ["-y", "@notionhq/notion-mcp-server"] [mcp_servers.social_board.env] NOTION_TOKEN = "PASTE_YOUR_INDIVIDUAL_WRITE_TOKEN_HERE"
  • Keep the quotation marks around both tokens.
  • notion_reference is for reading reference boards only.
  • social_board is your individual connection for Social Media Board updates and comments.
  • If you already have the old single-token setup, use the replacement instructions below instead of pasting duplicate blocks.
  • Save the file: Command + S on Mac or Ctrl + S on Windows.
  • Completely quit Codex, then open it again.
  • The first Notion request may take a minute while the helper downloads.

Test your connection

Start a new Codex task and paste the test that matches your setup. Account managers and client operations managers should use the one-connection test in the one-connection section. The tests below are for strategists:

First test
Use notion_reference to review the current social media content updates for [CLIENT NAME]. Start with the Social Media Task Board: https://app.notion.com/p/shoutoutdigital/33ef2a27ca798068805fc719f3d8f08e?v=35ff2a27ca798053a600000ca9f71a6a&source=copy_link. Give me a list of all content currently in progress, including the task-card link, status, due date, and assignee for each item. Then assess whether we are on time or falling behind, explain any risks or delays you notice, and recommend what needs follow-up. Base your assessment only on the available Notion information, clearly note anything missing, and do not make any changes.
Strategist second test — writable connection, no changes
Use social_board to find one Social Media Board task for [CLIENT NAME]. Show me the task title, status, due date, assignee, and link. Do not make any changes.
If Codex asks for permission to run npx or use the Notion tool, approve it. If it returns a result with a Notion link, setup is complete.

Already installed a token? Update the connection for your role

Strategists: if you installed the previous shared read-only token, keep it and add your personal social_board connection. Account managers and client operations managers: replace your old single token in its existing connection—do not add a second connection.
⌘
Mac
Update the existing line
  1. 1
    Open config.toml using the Mac instructions above.
  2. 2
    If the old heading says team_notion, change it to notion_reference in both headings. Leave the old shared token as it is.
  3. 3
    Scroll to the bottom and add only the social_board block shown below. Replace its green placeholder with your own writable token.
  4. 4
    Save with Command ⌘ + S, then fully quit and reopen Codex.
⊞
Windows
Update the existing line
  1. 1
    Open config.toml using the Windows instructions above.
  2. 2
    If the old heading says team_notion, change it to notion_reference in both headings. Leave the old shared token as it is.
  3. 3
    Scroll to the bottom and add only the social_board block shown below. Replace its green placeholder with your own writable token.
  4. 4
    Save with Ctrl + S, then fully quit and reopen Codex.
Replace the matching token line
NOTION_TOKEN = "PASTE_YOUR_NEW_TOKEN_HERE"
If you only have the old single connection, add this below it
[mcp_servers.social_board] command = "npx" args = ["-y", "@notionhq/notion-mcp-server"] [mcp_servers.social_board.env] NOTION_TOKEN = "PASTE_YOUR_INDIVIDUAL_WRITE_TOKEN_HERE"

If you cannot find NOTION_TOKEN, or you are unsure which block is read-only, stop and ask the team admin. Do not delete or duplicate the whole configuration.

What to ask Codex

Always name the client, page, or database in your question. Codex can only access the pages and databases assigned to your role, so being specific helps it find exactly what you need.

You say: "Pull a status report for ABC Dental from Notion. What's been done, what's still pending, and is anything overdue? Include links to the pages you used."

Codex does: Reads the Notion pages for that client and returns a clear report. You can copy it straight into an email, Discord message, or client update. If you want changes made, ask Codex explicitly and review the proposed changes first.

You say: "Find the task card for [TASK NAME] in the [DATABASE NAME] database and give me the direct link."

Codex does: Finds the card and returns the Notion link so you can open it straight away. Handy when you know a task exists but can't track it down quickly.

You can also ask it to find all cards for a client: "Find all task cards for ABC Dental in [DATABASE NAME] and list them with their status and links."

You say: "I have a meeting with Bright Smiles Dental soon. Read their Notion pages and give me a quick 5-point brief covering what's done, what's coming up, and anything I should raise. Include the links."

Codex does: Reads the pages and puts together a brief you can glance at before the call. Open the links to double-check anything important before you jump on.

You say: "Look through the [DATABASE NAME] database and flag anything that looks overdue, blocked, or hasn't been updated recently. Group by team member."

Codex does: Scans the available information and returns a summary. You can then ask it to update selected statuses or add follow-up notes, but review the exact items first.

You say: "Read the Notion pages for Bright Smiles Dental and give me a breakdown of their content: what's published, what's in draft, and what hasn't been started yet."

Codex does: Reads the content information from the available pages and returns a clear breakdown. Great to have before a client call so you know exactly where things stand.

You say: "Find the Notion page for ABC Dental and send me the link."

Codex does: Finds the page and returns the direct Notion link. Quicker than searching through Notion yourself, especially if you're not sure exactly where the page lives.

Sample requests by role

These prompts work the same way on Mac and Windows. Copy one, replace the words in [square brackets], and review Codex’s list before approving any changes.
Account manager — update the Video Shoot Tracker
Copy prompt
Find the Video Shoot Tracker entry for [CLIENT NAME]. Show me the current details and the exact changes you recommend. After I confirm, update the shoot date to [DATE], add this asset-folder link [PASTE LINK], and assign the follow-up to [PERSON]. Do not change anything else.
Account manager — create a client task
Copy prompt
In the [DATABASE NAME] database, find the workspace for [CLIENT NAME]. First show me where you will create the task. After I confirm, create a task titled [TASK NAME], set the status to [STATUS], due date to [DATE], and assign it to [PERSON]. Include the new task link in your reply.
Client operations manager — follow-up list
Copy prompt
Review the tasks for [CLIENT NAME] and give me a follow-up list. Include each task link, owner, due date, current status, what is missing, and the next action. Group the list by assignee. Do not make any changes.
Client operations manager — add a comment
Copy prompt
Open this task: [PASTE NOTION TASK LINK]. Show me the task title and current status. After I confirm, add this comment exactly: "[COMMENT TEXT]". Do not edit the task or add comments anywhere else.
Strategist — social content update
Copy prompt
Use the Social Media Board connection to find the in-progress content for [CLIENT NAME]. List the cards with links, status, due date, assignee, and next action. After I confirm, batch update only the selected cards to [NEW STATUS] and add the note "[NOTE]".

Good habit: for changes, ask Codex to show the cards and proposed values first, then reply “I confirm—make exactly those changes.”

Safe updates you can ask Codex to make

Before any batch change, ask Codex to show the records it will change and the exact new values. Confirm the list, then tell it to proceed. Afterward, spot-check the Notion cards.
Batch update statuses
Copy prompt
Show me the social media cards for [CLIENT NAME] that are currently in progress. List each card, its current status, due date and assignee. After I confirm the list, update only the named cards to [NEW STATUS]. Do not change any other fields.
Add a follow-up note or comment
Copy prompt
Find the task cards for [CLIENT NAME] that need follow-up. First show me the cards and links. After I confirm, add this comment to the selected cards: "[COMMENT TEXT]". Do not add comments anywhere else.

Tips

  • 1 Name the client or page. The more specific you are, the better Codex can find what you need.
  • 2 Paste a Notion link if you have it. Copy the URL from your browser and drop it into your message. Codex will go straight to that page.
  • 3 Ask for source links. Add "include the Notion links you used" to any question so you can open and verify the original pages easily.
  • 4 Check before you share. Glance over what Codex returns before forwarding it to a client. Open the Notion links to confirm the info is current.
  • 5 Review before writing. Before asking Codex to batch update statuses, add notes, or insert comments, confirm the client, records, fields, and exact wording.
  • 6 Keep the setup file private. Never paste the Notion token into a Codex message, Discord channel, email, or shared document.

Troubleshooting

Your token can only access pages and databases assigned to your role. If Codex can't find a page, it might not be included in your role's access. Share the Notion link with your team admin so they can check.

Completely quit and reopen Codex. Check that the configuration was saved in ~/.codex/config.toml on Mac or %USERPROFILE%\.codex\config.toml on Windows. Make sure the file is not named config.toml.txt and that the copied block still contains all quotation marks.

You can fix this yourself. This message means one Notion connection block is incomplete. Follow the steps below; you do not need to understand the code.
  1. Close Codex completely.
  2. Open your config.toml file using Step 2 above.
  3. Find the heading [mcp_servers.team_notion]. Select from that heading down to the line just before the next [mcp_servers...] heading, then replace it with the read-only block below. Keep your existing token in the yellow spot.
  4. Check the two headings match. If the connection is called notion_reference, its token heading must be [mcp_servers.notion_reference.env] too. Do not leave a mismatched heading such as [mcp_servers.team_notion.env].
  5. If you already have a social_board block, leave it alone. If not, add the second block from Step 3 and put your personal write token in the green spot.
  6. Save the file, then fully quit and reopen Codex. Run the test in Step 4.
Copy this read-only repair block
[mcp_servers.notion_reference] command = "npx" args = ["-y", "@notionhq/notion-mcp-server"] [mcp_servers.notion_reference.env] NOTION_TOKEN = "KEEP_YOUR_EXISTING_READ_ONLY_TOKEN_HERE"
Never paste a real token into Codex chat, Discord, email, or a screenshot. Only place it in the NOTION_TOKEN line in the private file.

Node.js is missing or Codex was open while it was installed. Install the LTS version from nodejs.org/en/download, restart your computer, and try again.

Codex can only access what your role's token has been granted. If something is missing, open the Notion link it gives you and check the page directly. Ask the admin to review your role access if needed.

Yes, if your personal connection was issued with write and comment access. Account managers and client operations managers can use their one connection for approved boards. Strategists should use the social_board connection for writes; their read-only connection cannot make changes. Ask Codex to show the exact records and new values first, then confirm before it writes.

The connection label (for example, Your Name | Codex) lets the team identify which personal token was used in the setup and logs. Notion’s own page history may show the connected integration rather than the person’s name, so always use only your own token and follow the team’s review process.

Setup checklist

Tick these off as you go 0 / 4
Tick each step as you complete it