Connect Motionfly to Claude Code, Codex and Claude

Overview

How it works

Your AI app talks to the Motionfly desktop app through a small bridge that ships inside Motionfly.

Your AI app

Claude Code, Codex / ChatGPT or the Claude desktop app.

Bridge

Bundled inside Motionfly. Your AI app starts it, so you don't need Node.js.

Motionfly desktop app

Runs a local MCP server on 127.0.0.1 while it's open.

Links itself on every launch

Each time it starts, Motionfly writes a motionfly server entry into the config of every AI app it finds. There's no setup command and nothing to paste.

Finds the app on its own

The bridge finds the running Motionfly app by itself, so a port change never needs a config edit.

Uses your AI subscription

Your own Claude or ChatGPT subscription pays for the model, so it doesn't use your Motionfly launch-video budget.

Requirements

Before you start

All three need to be true.

  • The Motionfly desktop app is open and signed in

    The MCP server only runs while the app is open. Don't have it? Download Motionfly for Mac.

  • Your account is on the Premium or Studio plan

    Connecting AI apps is part of Premium and Studio. On another plan, Settings → MCP shows an Upgrade button.

  • Settings → MCP → MCP server is switched on

    The list of AI apps and their statuses appears once it's on.

First step

Check the connection

Before you ask for a video, make sure your AI app can see Motionfly.

  1. 1

    Start a new chat or session

    AI apps load their tools when a chat starts, so use a fresh one after Motionfly links itself. In the Claude desktop app, fully quit and reopen it once first.

  2. 2

    Ask the AI to check the connection

    Prompt
    Check that the MotionFly MCP connection is working by listing my MotionFly projects.

    If it lists your Motionfly projects, you're connected. If it says Motionfly isn't reachable or can't find the tools, go to Problems and fixes.

  3. 3

    Ask for a launch video

    Prompt
    Make a 45-second launch video for https://your-product.com with MotionFly. Show me the storyboard scene by scene before you build anything.

    Swap in your own site. The AI shows you the storyboard before it builds anything.

Settings → MCP

What each status means

Settings → MCP shows a status next to each AI app. Here's what to do for each one.

Linked
Ready. Start a new chat or session in that app.
Linked · paused
The MCP server is off or still starting. Switch on MCP server.
Not linked
Click Check again.
Not installed
Motionfly detects an app by its config folder and didn't find one. Install the AI app, open it once, then click Check again.
Needs attention
Motionfly couldn't update that app's config file. Close the AI app, then click Check again. If the message stays, find it under Problems and fixes.

Check again is under Installed a new AI app? in Settings → MCP. Motionfly also re-links every app each time it starts.

Troubleshooting

Problems and fixes

Find the message you're seeing, in the AI chat or under the app in Settings → MCP.

In the AI chat

The AI says Motionfly isn’t reachable

MotionFly isn't reachable.

Why
Your AI app started the bridge, but the bridge couldn't reach the Motionfly desktop app. Motionfly is closed, signed out, not on Premium or Studio, or its MCP server is off.
Fix
  • Open the Motionfly desktop app and sign in.
  • Make sure your plan is Premium or Studio.
  • Switch on Settings → MCP → MCP server.

Your AI app reconnects on its own once Motionfly is back. If it doesn't, start a new session or chat.

After linking

Motionfly’s tools don’t show up in the AI app

Why
AI apps load their tools when a session or chat starts, and the Claude desktop app reads its config when it launches. A chat that was open before Motionfly linked itself won't have them.
Fix

First check that the app shows Linked in Settings → MCP. Then:

  • Claude Code. Start a new session, or type /mcp and reconnect motionfly.

  • Codex / ChatGPT. Start a new chat. Restart the app if the tools still don't appear.

  • Claude desktop app. Fully quit it (on a Mac, ⌘Q; closing the window isn't enough), reopen it once, then start a new chat.

In the AI chat or Settings → MCP

Motionfly says MCP needs a Premium or Studio plan

MCP needs a Premium or Studio plan

Why
Connecting AI apps to Motionfly is part of the Premium and Studio plans.
Fix
Upgrade to Premium or Studio. Settings → MCP shows an Upgrade button while your plan doesn't include it.
In the AI chat or Settings → MCP

Motionfly asks you to sign in

sign in to MotionFly in the app

Why
The Motionfly desktop app isn't signed in, so it can't check your plan.
Fix
Sign in to the Motionfly desktop app with your Motionfly account.
In the AI chat or Settings → MCP

Motionfly couldn’t check your plan

could not check your plan (…)

Why
Motionfly checks your plan with its servers and couldn't reach them. The text in brackets says what went wrong.
Fix
Check your internet connection, then reopen Motionfly or click Check again in Settings → MCP.
Needs attentionCodex / ChatGPT

The Codex config has a hand-written motionfly entry

config.toml defines "motionfly" in a form MotionFly can't update

Why
A motionfly entry was added to the Codex config by hand, in a form Motionfly won't overwrite.
Fix
Open ~/.codex/config.toml (or $CODEX_HOME/config.toml when CODEX_HOME is set), delete the hand-written motionfly entry and save. Then click Check again, and Motionfly writes its own.
Needs attentionClaude Code or Claude desktop app

A Claude config file isn’t valid JSON

config root is not a JSON object

Why
The Claude Code or Claude desktop app config file is malformed, so Motionfly leaves it alone rather than overwrite it.
Fix
Fix the JSON in the file named under the app in Settings → MCP, or back it up and remove the broken file. Then click Check again. The file locations are in the app reference.
Any AI app

It stopped working after you moved or updated Motionfly

Why
Each AI app's config points to the bridge inside Motionfly, so a new location leaves the old path behind.
Fix
Open Motionfly once. On launch it rewrites the configs with its new location. Then start a new chat.
Codex / ChatGPT

Codex keeps asking for approval

Why
Motionfly auto-approves its tools in Codex except two: approving the storyboard and exporting the video. Those always ask, on purpose.
Fix
Nothing to fix. Approve those two steps in Codex when you're ready.

Config files

App reference

Motionfly edits these files for you. They're listed so you know where to look.

Claude Code

Config file
~/.claude.json
Detected when
~/.claude or ~/.claude.json exists.
Reconnect
Start a new session, or type /mcp and reconnect motionfly.

Codex and the ChatGPT desktop app

Codex and the ChatGPT desktop app share one config.

Config file
~/.codex/config.toml
When CODEX_HOME is set
$CODEX_HOME/config.toml
Detected when
The ~/.codex folder (or $CODEX_HOME) exists.
Reconnect
Start a new chat. Restart the app if the tools still don't appear.

Claude desktop app

macOS
~/Library/Application Support/Claude/claude_desktop_config.json
Windows
%APPDATA%\Claude\claude_desktop_config.json
Detected when
A Claude folder exists in ~/Library/Application Support (macOS) or %APPDATA% (Windows).
Reconnect
Fully quit the app and reopen it once, then start a new chat.

Still stuck?

Email us which AI app you're using and the status or message Settings → MCP shows for it. We'll help you get connected.

natnael@motionfly.coDownload Motionfly