Overview

The brainCloud MCP Helper is a small companion to the brainCloud MCP server. It runs locally on your own machine and gives Claude the one thing the hosted server deliberately cannot have: access to your filesystem. With both connected, you can ask Claude to sync your cloud code scripts between brainCloud and a folder on your computer - pull the latest scripts down, push your local edits up, or do a full two-way sync with automatic merging.

The helper is trustless by design: it never logs in to brainCloud and stores no credentials. Whenever a sync is needed, Claude asks the hosted brainCloud MCP for a short-lived, app-scoped ticket and hands it to the helper for that one operation. Your script data flows directly between your machine and brainCloud - it never passes through the AI.

Prerequisites

The brainCloud MCP server already connected to Claude. If you have not done this yet, follow Getting Started with brainCloud MCP in Claude first. The helper does nothing on its own - it relies on the hosted server for credentials.
Node.js 18 or newer installed on your machine. The helper launches via npx, which ships with Node.
A local folder for your scripts (typically a git repository). Claude and the helper manage a small .bcsync file there to remember which brainCloud app maps to which branch.

Step 1: Register the Helper

Unlike the hosted MCP server (which you connect to by URL), the helper runs as a local process that Claude starts on demand. You register it once in your Claude configuration.

Claude Code CLI

Run the following command from your terminal:

claude mcp add braincloud-helper -- npx -y @braincloud/mcp-helper@latest

That is the whole setup. The npx ... @latest launch fetches the newest helper each time Claude starts it, so it stays current automatically. (For CI or reproducible setups, pin a specific version, e.g. @braincloud/mcp-helper@1.0.0.)

Claude Desktop App & other MCP clients

For the Claude Desktop App, Cursor, or any other MCP client, add the helper to the mcpServers section of your client's MCP configuration file:

{
  "mcpServers": {
    "braincloud-helper": {
      "command": "npx",
      "args": ["-y", "@braincloud/mcp-helper@latest"]
    }
  }
}

If you already have the hosted brainCloud server in this file, just add braincloud-helper alongside it - you want both entries. Save the file and restart the client.

Step 2: Verify the Connection

In the Claude Code CLI, type /mcp to list your connected servers. You should see both braincloud (the hosted server) and braincloud-helper (the local helper). In the Desktop App, the helper appears in your list of connectors after a restart.

The helper requires no login or authentication step of its own - if it shows as connected, it is ready.

Step 3: Sync Your Scripts

With both servers connected, just describe what you want in plain language. Claude handles the handshake between the two servers for you - it requests a ticket from the hosted server and passes it to the helper.

First, make sure the hosted server is pointed at the right team and app (e.g. "Switch to my Acme team and use GameApp."). Then try:

Check status - "Show me the sync status of the scripts in ./cloud-code." Claude reports which scripts are in sync, changed locally, changed on brainCloud, new, or in conflict. Nothing is written.
Pull - "Pull the latest cloud code from brainCloud into this folder." Brings down brainCloud changes for scripts you have not edited locally.
Push - "Push my local script changes up to brainCloud." Sends your local edits up in a single bulk import.
Full two-way sync - "Sync this folder with brainCloud." Reconciles both directions and automatically merges scripts changed on both sides. Genuine conflicts are flagged with standard <<<<<<< merge markers for you to resolve.

Cloud code metadata - callable flags, timeouts, descriptions, parameters, and folder placement - travels with each script's .ccjs file, so a synced folder is a complete, faithful copy of your app's cloud code.

Live App Safety

The helper is covered by brainCloud's live-lock protection automatically. Reading (status and pull) always works, even on a locked live app, so you can always inspect a production app for drift. Writing (push and sync), however, requires the app to be unlocked - Claude will ask you to confirm an unlock through the brainCloud portal before any change is pushed. Because the helper cannot get a write ticket for a locked app, a live app is protected even though the helper is running on your own machine.

Need Help?

If the helper does not appear after registering it, confirm Node.js 18+ is installed (node --version) and that the hosted brainCloud MCP server is connected first. Visit the brainCloud portal or contact brainCloud support if you have trouble connecting.

Syncing Cloud Code to Local Files with the brainCloud MCP Helper