Set up ChatGPT

You connect StoryFolder to ChatGPT through Codex, OpenAI's own assistant tool. You sign in to Codex with the ChatGPT account you already have.

StoryFolder connects it for you. You don't need to find Node, find the connector, or type a command.

Where you'll find StoryFolder

Once this is set up, StoryFolder shows up in the two places Codex lives:

• the Codex app or command line on your computer
• the Codex sidebar in an editor like VS Code or Cursor

It doesn't appear in the ChatGPT desktop app's chat window yet. That's on our list. For now, open Codex and ask it there.

StoryFolder sets up three clients in all — Claude Desktop, Claude Code and ChatGPT Codex — and no others.

We've tested Claude further

Claude Desktop is the path we've run end to end. For Codex we've confirmed it reads the setup below and starts StoryFolder, but we haven't signed off on a full working conversation yet. If something misbehaves, tell us — that feedback is genuinely useful right now.

What you'll need

• Codex, signed in. Install the CLI or the editor extension from OpenAI, then run codex login and sign in with your ChatGPT account.
• StoryFolder installed and open.
• Node 18 or newer. Codex runs the connector with Node and doesn't bring its own copy. StoryFolder finds it for you — including a version-manager Node under your home folder, which Codex usually can't find on its own.
• The connector folder — one download, kept somewhere permanent. Next section.

Get the connector

Download Codex Extension

Version 0.3.0 · For Codex on macOS, Windows and Linux

1. Download the file above and unzip it.
2. Move the folder somewhere you'll keep — ~/StoryFolder-connector, say. Not Downloads, which you'll empty one day.

Everything StoryFolder needs is already in the folder. There's nothing to install into it, and no path for you to note down — StoryFolder looks for it in your home folder, Downloads, Desktop, Documents and Applications.

Using Claude Code too?

It's the same folder. One download serves both. Claude Desktop's extension is a different file — grab that from the Claude Desktop page.

Connect it

1. Open StoryFolder and go to Preferences → MCP Server, or click Connect an AI assistant in the header.
2. Choose ChatGPT Codex.
3. StoryFolder shows what it found on this computer — Node, the connector, and where Codex keeps its settings. Anything it couldn't find is named, not guessed.
4. Decide whether you want Read-only. It's a checkbox, off by default. More below.
5. Click Install StoryFolder MCP.
6. Restart Codex. It won't pick up a new connection until you do.

StoryFolder runs codex mcp add for you with the real locations filled in, then checks Codex's own settings to confirm it took. "Connected" means it looked.

If the connector isn't found, use Locate connector folder… in the panel and pick the folder yourself. StoryFolder only accepts a folder that actually holds the connector — one containing src/index.js and our manifest.json — so a wrong pick is refused rather than silently registered.

Check it worked

With StoryFolder open, start a Codex session and ask:

What projects are in my StoryFolder library?

You should get your real project names back. Then try something more interesting.

If nothing comes back, it's almost always that StoryFolder is closed or you didn't restart Codex.

Let it read, but not edit

Tick Read-only before you connect and the assistant can look at everything and change nothing. Renaming, tagging, adding note fields, importing and exporting stop being available to it.

To change your mind, tick or untick the box and connect again — it replaces the earlier setup. Restart Codex afterwards.

There's more on what read-only costs you on the overview.

If you'd rather run the command yourself

The panel never hides it. Click Or run the command yourself… and it shows the exact command, already filled in with this computer's paths:

codex mcp add storyfolder -- /absolute/path/to/node /Users/you/StoryFolder-connector/src/index.js

With read-only:

codex mcp add storyfolder \
  --env STORYFOLDER_MCP_READ_ONLY=1 \
  -- /absolute/path/to/node /Users/you/StoryFolder-connector/src/index.js

Confirm it registered:

codex mcp list

storyfolder should be in the list. Restart Codex afterwards.

When Codex cannot find Node

If you ran the command by hand and Codex never starts StoryFolder at all, this is nearly always why. The in-app button avoids it entirely — it writes the absolute path — but here's the whole thing.

node --version working in your terminal doesn't mean Codex can find Node. An app you launch from the Dock or Start menu doesn't read your shell's settings, so it looks in a different set of places. If you manage Node with nvm, fnm, asdf or volta, your Node lives in your home folder and won't be one of them.

The fix is to spell out where Node is. Find it:

# macOS / Linux
which node

# Windows (PowerShell)
where.exe node

That prints something like /Users/you/.nvm/versions/node/v22.22.0/bin/node. Use that whole thing in place of node.

That path changes when you upgrade Node

An nvm path has the version number in it, so .../v22.22.0/bin/node stops existing the day you move to v22.23. If StoryFolder disappears from Codex after a Node upgrade, reopen Preferences → MCP Server and connect again — the panel will show it pointing somewhere that no longer exists, and one click repairs it.

Editing the config file by hand

codex mcp add writes to ~/.codex/config.toml. You can edit that file directly instead — the panel shows this block too, filled in for your machine:

[mcp_servers.storyfolder]
enabled = true
command = "/Users/you/.nvm/versions/node/v22.22.0/bin/node"
args = ["/Users/you/StoryFolder-connector/src/index.js"]

On Windows, note the doubled backslashes — TOML requires them:

[mcp_servers.storyfolder]
enabled = true
command = "C:\\Program Files\\nodejs\\node.exe"
args = ["C:\\Users\\you\\StoryFolder-connector\\src\\index.js"]

Read-only mode goes in its own sub-table:

[mcp_servers.storyfolder.env]
STORYFOLDER_MCP_READ_ONLY = "1"

1, true and yes all turn it on. Anything else, including an empty value, leaves editing available. Restart Codex after any change.

The Codex CLI and the editor extension read the same file, so you set this up once and both see it.

Next step

→ Things to try