Fix an agent connection

This narrows down an agent connection that is not behaving, in the order the failures actually happen. It applies to both apps.

You need:

• The app installed, and a client already registered. See Agent Access.

Steps

1. Check the app is open. The tools live in the running app, not in the client’s config.
2. Check Agent Access is switched on: Settings > General > Agent Access in Cask Film, Settings > Agent access in Cask Flow. Off means no listener at all.
3. Ask your client to list its tools. Empty means it reached the bridge but the bridge found no app.
4. Ask the agent to call observe in Cask Film, or meta_capabilities in Cask Flow. Each reports whether a project is open, and each is the cheapest thing that proves the whole path works.
5. If writes are refused, check the editor for a notice. In Cask Film a Read-only banner names the Mac holding the project’s edit lease. In Cask Flow a notice says the project changed on disk and asks you to choose between reloading and keeping your changes.
6. If the agent describes a project you are not looking at, you have more than one copy of that app running. See below.

Result

The call returns a summary of the project you have open in front of you. That confirms every hop: client, bridge, app, and the right app.

If it doesn’t work

Symptom	Cause	Fix
Client shows the server but no tools	The app is closed, or Agent Access is off	Open the app and check the switch. Tools appear within a few seconds; you do not need to restart the client
Tool calls return an error saying the app is closed	Same	Same
Tools vanished mid-session	You quit the app	Reopen it. The bridge reconnects on its own
Every tool is refused as not signed in, in Cask Flow	Nobody is signed in. Only the capability and guidance tools answer	Sign in in the app window. No tool can do it for you
Every write tool refuses, reads work, in Cask Film	The project is read-only because another Mac holds its edit lease	Click Take Back Editing
Every write tool refuses, reads work, in Cask Flow	The project bundle changed on disk, so saving is paused	Choose reload or keep, in the app’s notice
Writes refused with no notice at all	No project is open	Have the agent list the projects and open one
Claude Desktop shows nothing after connecting	It reads its config at launch	Quit it fully and reopen
Works in one terminal directory only, in Claude Code	Registered at local scope	Re-register with -s user. See Connect Claude Code
Codex returns 401, or worked yesterday and not today	A url config entry naming an old port	Replace it with the command entry. See Connect Codex
The agent edits a project you are not working on	Several copies of that app are running, and it picked one of them	Quit the copies you do not want, or pin the one you do
A pin matches nothing	The selector names an instance that is not running	The error lists what is running. Pick from that

Pin a specific copy of an app

With one copy of an app running, there is nothing to configure. Skip this.

Each app publishes into its own handshake directory and each bridge reads only its own app’s, so Cask Film and Cask Flow never pick each other up. The ambiguity is between copies of the same app: a released build and a development build, for example. Each publishes its own entry, and with nothing pinning the session the bridge picks the most recently published one. It says which one it picked in the instructions it gives the agent, naming the alternatives and telling the agent to confirm before editing.

That is a note, not a guarantee. The default can still connect an agent to a copy you did not mean. If you routinely run two, pin one.

The choice sticks for the whole session once made, and only gives way when the pinned copy exits. Without that, merely opening a project in another window could move a session from one copy to another between two tool calls.

Pin with --instance on the command line, or CASK_MCP_INSTANCE in the environment:

claude mcp add -s user cask-studio-debug \
  "/Applications/Cask Studio.app/Contents/MacOS/cask-mcp" -- --instance config:debug

[mcp_servers.cask-motion-debug]
command = "/Applications/Cask Flow.app/Contents/MacOS/cask-mcp"
args = ["--instance", "config:debug"]

Selectors are case-insensitive:

Form	Matches
pid:30860	that exact process
port:63099	that exact port
config:debug	part of the build configuration name
project:Ad Reel	part of the name of the project currently open
bundle:/Applications	part of the app bundle path
bare digits	a pid or a port
bare text	part of the configuration, project, bundle path, or app name

Pinning by pid: or port: is stronger than by config: or project:, which can match more than one copy.

One caveat on project: in Cask Film. The project name is republished when a project becomes the active editor and cleared when the editor closes, so renaming a project while it stays open is not reflected until the next time you activate its editor. Cask Flow republishes on rename as well. Pin by pid when a name is in flux.

Which bundle the bridge binary itself came from is not a criterion. Running the released app’s bridge against a development copy is a normal thing to do.