Skip to content
Ripple Effect

How to connect an AI assistant (MCP client)

Use this to point an MCP client — Claude Code, Claude Desktop, Cursor or anything else that runs local servers — at the project you have open in Ripple Effect.

  1. Switch agent access on.

    Open the gear in the app bar, which is on every screen, and pick the Agents page; the command palette’s Agents command opens the same page. Switch on Let agents reach this app. An assistant can now read the project and play it, but change nothing.

    Leave Let agents change files off until you want an assistant to change files. It only does anything while the first switch is on, and reading is useful on its own. With it off, a tool that writes answers refused.

    Both switches are for the app rather than for one project: the app serves whichever project is open.

  2. Copy the configuration.

    Press Copy client configuration on the page. The clipboard receives the block most clients read, already pointing at the right place on your machine:

    {
      "mcpServers": {
        "ripple_effect": {
          "command": "/opt/ripple_effect/ripple_effect_mcp",
          "args": []
        }
      }
    }

    The path is a small program installed beside the app that the client starts and that talks to the app for it. Copy it from the page rather than typing it; the app installs to a different place on each platform.

  3. Paste it where your client reads it.

    One command, with the path from the page:

    Terminal window
    claude mcp add ripple_effect -- /opt/ripple_effect/ripple_effect_mcp

    Quote the path on Windows, where it contains a space. claude mcp list shows it registered; /mcp inside a session shows whether it connected.

  4. Ask it something.

    A client with the bridge configured appears in the page’s Connected list as soon as access is on; it does not wait for its first request. The app bar shows nothing for agents until there is news. While a client is connected its mark appears there, with its name and version on the tooltip. If the app could not open its local connection, the mark appears in the error colour instead. Either one opens the Agents page.

    A good first request is project_outline — the shape of the whole story in about twenty lines — or ask what is this project about? and let the assistant find that tool itself.

If it says the app is not running

Section titled “If it says the app is not running”

While the app is closed or agent access is off, every tool call answers:

ripple_effect is not running, or agent access is switched off.
Open the project in ripple_effect and switch on "Let agents reach this app" under Settings → Agents.

Open the project and switch access on in the Agents page of Settings. The client does not need restarting. The assistant sees the full tool list either way, so it can tell you what it would be able to do before the app is up.

Find the program by hand

Section titled “Find the program by hand”

If you need the path without opening the app, it is:

Platform Path
Linux, .deb /opt/ripple_effect/ripple_effect_mcp
Linux, .rpm /usr/share/ripple-effect/ripple_effect_mcp
Windows %LOCALAPPDATA%\Programs\Ripple Effect\ripple_effect_mcp.exe
macOS /Applications/Ripple Effect.app/Contents/MacOS/ripple_effect_mcp

It is deliberately not on your PATH: the app installs to three different places on three platforms, and no one command line is true on all of them. The connection between it and the app is a private local channel that only your own account can open, never a network port.

A build run from source has no such program beside it; melos run editor:mcp:bridge makes one and prints where it put it.

Section titled “Related”