Troubleshooting

Find the thing that's happening to you. Most of these are a one-line fix.

The assistant says it can't find StoryFolder

Work down this list — it's in order of how often each one is the answer.

1. Is StoryFolder open? The assistant reads the running app. If StoryFolder is closed, there's nothing to read.
2. Did you restart the assistant? Neither Claude nor Codex notices a new connection until it restarts. Quit it properly — on a Mac, closing the window isn't quitting — and reopen.
3. Are you in the right app? For ChatGPT you ask in Codex, not the ChatGPT chat window. More below.
4. Is it actually listed? In Claude, look under Settings → Extensions. In Codex, run codex mcp list and check storyfolder is there. If it isn't, the setup didn't save.
5. Codex only: can it find Node? This is the big one, and it has its own section.

That last one catches most ChatGPT setups that never worked at all — see when Codex cannot find Node.

It says StoryFolder isn't running, but it is

The full message:

StoryFolder is not running. These tools work by talking to the StoryFolder desktop app on this computer, so the app has to be open. Open StoryFolder, wait for your library to appear, and try again.

If StoryFolder is still starting up, give it a few seconds and ask again. You don't need to restart the assistant — it re-checks every time.

If StoryFolder is definitely up and running, quit it completely and reopen it. The assistant finds the app through a small file StoryFolder writes when it launches, and a hard crash can leave that file pointing somewhere stale. Relaunching rewrites it.

ChatGPT has no StoryFolder tools

Ask in Codex rather than the ChatGPT chat window. Codex is where the connection lives — the Codex app, the command line, or the Codex sidebar in your editor. It signs in with the same ChatGPT account, so nothing extra is needed.

StoryFolder doesn't appear in the ChatGPT desktop app's chat window yet. That's on our list.

If you'd rather have this in an ordinary chat window today, Claude is the shorter route.

It can read my projects but won't change anything

Read-only mode is on. That's the switch that lets the assistant look but not touch, and it's doing its job.

If it tries anyway, it gets told plainly that the tool isn't available because read-only mode is on — so you'll usually see the assistant explain that rather than fail silently.

To turn editing back on:

• Claude — untick Read-only under Settings → Extensions → StoryFolder, then restart Claude.
• ChatGPT / Codex — remove STORYFOLDER_MCP_READ_ONLY from your Codex setup, or set it to 0, then restart Codex.

The opposite problem — it's editing and you wanted it not to — is the same switch the other way. See let it read, but not edit.

Claude says the extension is unverified

That's expected, and it's about our paperwork rather than the file. Click through and continue. The longer answer.

It's quoting the wrong shot numbers

It's off by one — behind the scenes, shots are counted from zero as well as from one, and it's mixed them up.

Tell it to use the shot numbers StoryFolder shows you. It can, and it will. Background in a note on shot numbers.

It says a project doesn't exist

Ask for the project by name rather than by number, or ask it to list your projects first and pick from that. Asking for a project that isn't in your library currently comes back as a raw error message rather than a plain sentence. It's harmless.

It worked, then stopped after I updated something

If you set up ChatGPT / Codex and then upgraded Node, the path you gave Codex probably no longer exists — version managers put the version number in the path. Re-run which node and update it. Full detail.

If you moved or deleted the connector folder, put it back or point Codex at its new home.

Claude users shouldn't hit either of these — the extension carries everything it needs.

Where the diagnostic output is

The connector writes diagnostics to standard error, which both clients capture in their log view. On a healthy start the first line is:

storyfolder-mcp: ready on stdio

In Claude, look for the StoryFolder entry under Settings → Extensions. For Codex, codex mcp list shows what's configured, and the client's own log output is where a failed launch shows up.

If you're sending us a bug report, that output plus your StoryFolder logs is what we need.

Still stuck

Contact support. Tell us which assistant you're using, which operating system, and what you asked it. A real person answers within one business day.