skills/flutterflow-designer/orbit-setup.md

FF Orbit MCP — VSCode / Claude Code Setup

How to set up and run the FlutterFlow Orbit MCP server with Claude Code in VSCode.

1. Install Dependencies

cd /Users/alainbagmi/flutterflow-mcp
npm install

2. Get FlutterFlow API Token

1. Open FlutterFlow web app → Settings → API Token
2. Copy the token

3. Configure MCP for Claude Code

Option A: Project-Level Config (Recommended)

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "ff_orbit_mcp": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/Users/alainbagmi/flutterflow-mcp",
      "env": {
        "FLUTTERFLOW_API_TOKEN": "<your-token>",
        "FLUTTERFLOW_API_MIN_INTERVAL_MS": "1000",
        "ORBIT_POLICY_SAFE_MODE": "guidedWrite"
      }
    }
  }
}

Option B: Claude Code CLI

claude mcp add -s project \
  -e FLUTTERFLOW_API_TOKEN=<your-token> \
  -e FLUTTERFLOW_API_MIN_INTERVAL_MS=1000 \
  -e ORBIT_POLICY_SAFE_MODE=guidedWrite \
  ff_orbit_mcp -- npm start

Option C: Global Config

Add to ~/.claude/settings.json under mcpServers key (same format as .mcp.json).

4. Verify Connection

After restarting Claude Code (or the MCP server), run:

orbit({ cmd: "help" })
orbit({ cmd: "projects.list" })

If either fails:

• Check FLUTTERFLOW_API_TOKEN is set and valid
• Check cwd points to /Users/alainbagmi/flutterflow-mcp
• Check npm start runs without errors in that directory
• Check network access to https://api.flutterflow.io/v2

5. First-Time Project Setup

# List your FlutterFlow projects
orbit({ cmd: "projects.list" })

# Create a snapshot of the target project
orbit({ cmd: "snapshots.create", args: { projectId: "<project-id>" } })

# Verify snapshot
orbit({ cmd: "snapshots.info" })

# List pages
orbit({ cmd: "pages.list" })

Environment Variables Reference

Required

Variable	Description
FLUTTERFLOW_API_TOKEN	Your FlutterFlow API bearer token

Server Configuration

Variable	Default	Description
PORT	8080	HTTP server port
ORBIT_HTTP_ENABLED	1	Set to 0 to disable HTTP health endpoint
ORBIT_DB_PATH	.orbit/orbit.sqlite	SQLite database location
ORBIT_SNAPSHOT_STALE_MINUTES	30	Snapshot staleness threshold
ORBIT_POLICY_FILE	orbit.policy.json	Policy file location
ORBIT_ALLOW_POLICY_WRITE	0	Set to 1 to enable runtime policy updates

FlutterFlow API

Variable	Default	Description
FLUTTERFLOW_API_BASE_URL	https://api.flutterflow.io/v2	API base URL
FLUTTERFLOW_API_MIN_INTERVAL_MS	1000	Minimum ms between API calls

Policy Overrides (Environment)

Variable	Values	Description
ORBIT_POLICY_SAFE_MODE	readOnly, guidedWrite, fullWrite	Write permission level
ORBIT_POLICY_REQUIRE_MANUAL_APPROVAL	true/false	Require manual approval for writes
ORBIT_POLICY_MAX_FILES_PER_APPLY	number	Max files in a single apply
ORBIT_POLICY_MAX_LINES_CHANGED	number	Max line changes per apply
ORBIT_POLICY_ALLOW_PROJECTS	comma-separated	Restrict to specific projects
ORBIT_POLICY_DENY_FILE_PREFIXES	comma-separated	Block file paths from edits

Policy Configuration

Default policy in orbit.policy.json:

{
  "allowProjects": ["*"],
  "allowFileKeyPrefixes": [],
  "denyFileKeyPrefixes": ["lib/custom_code/", "lib/custom_functions/", "lib/main.dart"],
  "maxFilesPerApply": 200,
  "maxLinesChanged": 10000,
  "requireManualApproval": false,
  "allowPlatformConfigEdits": false,
  "safeMode": "fullWrite"
}

Safe mode levels:

• readOnly — No writes allowed, read-only queries only
• guidedWrite — Writes require changeset preview + validate + confirm
• fullWrite — Direct writes with apply: true allowed

Troubleshooting

"MCP server not responding"

• Restart Claude Code / VSCode
• Check if npm start works in /Users/alainbagmi/flutterflow-mcp
• Look for errors in the terminal output

"Invalid token" or authentication errors

• Regenerate token in FlutterFlow Settings
• Update FLUTTERFLOW_API_TOKEN in .mcp.json

Rate limiting (429 errors)

• Increase FLUTTERFLOW_API_MIN_INTERVAL_MS to 2000 or higher
• Use snapshots.refreshSlow instead of snapshots.refresh
• Use changeset.applySafe instead of changeset.apply

Snapshot data looks incomplete

• Run snapshots.refresh with mode: "full"
• Check snapshots.info for authoritative status
• If 429s during refresh, use chunked: { mode: "full", fetchStrategy: "file", maxFetch: 5 }