Skip to main content
The control plane has one rule at its centre: the client’s call is your consent. A client acting on your request already has your go-ahead, so the things you asked for happen without a second question. A few actions are different because they kill or tear down work, and those always ask you in Fermata.

What runs on the call

Reading anything runs on the call. So does everything that creates or publishes work: filing, editing, cancelling, and releasing drafts, creating pieces, answering the interview, approving the spec and the strategy, starting and resuming agents, recovering failed agents, asking for changes, sending agents back, changing the lane, opening the pull request, and archiving. When you say “start SUP-12 on Auto”, it starts.

What always asks

Two actions raise a confirmation card on your Mac every time, whatever else you set:
  • Stopping agents (stopAgents), because it kills running work.
  • Marking a piece done (markDone), because it can remove a worktree.
The card is titled “Allow the MCP client to stop agents?” or “Allow the MCP client to mark the piece done?”, and its body names the piece and the project: “An external MCP client wants to stop agents on ‘upload-retry’ (muse).” You answer Allow or Deny.

Ask before runs and pull requests

If you would rather approve runs and pull requests too, turn on Ask before runs and pull requests in Settings → MCP, in the “Server” card under the server switch. It is captioned “Approve each one in Fermata”, and it is off by default. With it on, these also wait for a card, and the card’s title names each one: Approving a spec onto the Manual lane, and releasing a Manual or Loop draft, still run on the call: those start a spec step or a strategy, not an unattended run. The setting is read on every call, so turning it on applies to the next request without a restart. For a release through create_draft, the card shows before anything is filed, so a denied card leaves nothing behind.

The cards

A card shows in the window of the project the piece belongs to. A card for a piece with no project shows in every open project window, and answering it in one clears it from all of them. One card shows at a time; the next one presents when you answer. If the project’s window is closed, a notification carries the same sentence, and the card presents as soon as you open the window. That notification follows the Required input switch in Settings → Notifications. A waiting card has no timeout, exactly like a gate: the client waits as long as you do. If the call is taking long, look at Fermata on your Mac. A denied card fails the call and changes nothing on the piece. Four things deny every waiting card at once: the client giving up on the call, Retry in Settings → MCP, switching the server off, and quitting Fermata.

What a client can never do

Merge a pull request. Merging writes to a shared repository and cannot be undone, so it is not exposed over MCP at all. Fermata opens the pull request; you merge, in the app or from a paired phone. Get past your gates. Lanes, gates, and permission profiles behave exactly as they do in the app. A piece on the Manual lane still stops at every phase, and a build agent on the Safe profile still raises its tool approvals inside Fermata. The client presses the same buttons you would, only where the app would offer them. Act in the wrong phase. Each action is checked against the piece’s current phase before it runs, and again after a card is answered, because the piece may have moved while the card waited. An illegal action fails and lists what is legal now.

Fermata’s own agents can read, not drive

Once you register the server, the sessions Fermata itself starts load it too: build agents, the spec interview, reviews, feedback sessions, and sessions you open on the canvas. They can use the read tools under their normal approval rules. They are refused every tool that creates or changes work: creating pieces and drafts, editing, cancelling, and releasing drafts, registering projects, opening a workspace, and every piece_action. The refusal reads “Fermata’s own agents can’t drive Fermata through its MCP server. Ask the person to do this from the app or from their own MCP client.” This holds on every permission profile and every lane, so an agent inside one piece can never start runs or open pull requests on another. To drive Fermata, use the app or a Claude Code session you started yourself. The rule matches the server by the name Register gives it, fermata. If you add the endpoint by hand under a different name, Fermata’s own agents are not fenced off from it.

The connection itself

The server binds to 127.0.0.1 only, so nothing on your network can reach it. Every request carries the token in its URL, and a wrong token is refused before anything else happens, including the handshake. The token lives in your Keychain. Regenerate Token retires it for every client at once; see connect a client.