Troubleshooting

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

Start in the app

Preferences → MCP Server reads your assistant's own settings and tells you what it finds. It's faster than guessing, and most of the sections below have a one-click fix there. The states it can show are covered in what the panel shows you.

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? Open Preferences → MCP Server in StoryFolder and pick your assistant — it checks that assistant's own settings and tells you. Or look yourself: codex mcp list, claude mcp list, or Claude Desktop's Settings → Extensions.
5. Did you set it up by hand? If so, the path to Node is the usual culprit, and it has its own section.

That last one catches most hand-written setups that never worked at all — see when Codex cannot find Node. Connecting from inside StoryFolder avoids it: the app writes the absolute path.

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.

The panel says my assistant isn't detected

StoryFolder looked for the assistant on this computer and didn't find it.

• Claude Code / Codex — it looks for the claude or codex command and actually runs it to confirm it works. A broken shim left behind by a version manager counts as not found, which is correct: the assistant can't be driven by it either.
• Claude Desktop — it looks for the app and for its settings folder.

Install the assistant, then reopen the panel. It re-checks every time you open it. If it's definitely installed and still not detected, connect by hand — the panel's Or run the command yourself… block has the exact command.

The panel says the connector wasn't found

The connector is the small folder that talks to StoryFolder on the assistant's behalf. In a packaged install you download it once and keep it — grab it from the Codex page or the Claude Code page.

Unzip it, put it somewhere permanent, then reopen the panel. StoryFolder checks your home folder, Downloads, Desktop, Documents and Applications for a folder called StoryFolder-connector. Anywhere else, use Locate connector folder… and pick it yourself.

"That folder does not hold the connector." You picked a folder that isn't it. The right one contains src/index.js and a manifest.json. If you picked the zip's outer folder, look one level in.

Claude Desktop's extension route needs none of this — the extension carries the connector inside it.

The panel says Node wasn't found

Claude Code and Codex run the connector with Node and don't bring their own. Install the LTS build from nodejs.org, then reopen the panel.

If it found Node but warns about the version, it's older than 18. Upgrade it — the connector won't run on it.

The panel says it points somewhere else on this computer

StoryFolder is already set up there, but it points at a location that has moved or no longer exists. This is what a Node upgrade or a moved connector folder looks like.

Press the button again. It sets it up afresh with the current locations. Then restart the assistant.

The panel says it couldn't connect

It shows the assistant's own error output underneath, which is usually the whole answer. Try again re-runs it.

If it keeps failing, use the manual route in the same panel — the command shown there is the exact one StoryFolder was trying to run, with the real paths already filled in, so you can run it in a terminal and see the failure in full.

For Claude Desktop, a failure usually means its settings file couldn't be written. If StoryFolder says the file isn't valid JSON, it has deliberately refused to touch it rather than overwrite a file it can't parse — fix the file by hand, or install the extension instead.

Claude Desktop says "added — not active yet"

That's accurate, not a failure. Claude Desktop reads its configuration only when it starts, so a correct entry on disk still isn't loaded.

Fully quit Claude Desktop and reopen it. On a Mac, closing the window isn't quitting — use Claude → Quit, or ⌘Q.

The panel says "no storyfolder entry yet" but Claude works fine

You installed the .mcpb extension. That registers inside Claude Desktop's own extension store, which the panel can't see — it only reads claude_desktop_config.json.

Believe the extension. If Claude answers questions about your library, it's connected. Don't add it a second way to make the panel happy; running both routes at once isn't something we've tested.

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:

• Connected from inside StoryFolder — open Preferences → MCP Server, pick the assistant, untick Read-only, and connect again. It rewrites the earlier setup. Restart the assistant afterwards.
• Claude Desktop extension — untick Read-only under Settings → Extensions → StoryFolder, then restart Claude.
• Set up by hand — remove STORYFOLDER_MCP_READ_ONLY from what you wrote, or set it to 0, then restart the assistant.

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

Upgrading Node breaks a setup that names the old one — version managers put the version number in the path. Moving or deleting the connector folder does the same.

Open Preferences → MCP Server, pick your assistant, and connect again. The panel will already be showing it pointing somewhere else, and one click repairs it with the current locations. Restart the assistant afterwards.

Claude Desktop extension 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 Desktop, look for the StoryFolder entry under Settings → Extensions. codex mcp list and claude mcp list show what's configured, and each 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, what Preferences → MCP Server says, and what you asked it. A real person answers within one business day.