# babbleBrush agent collaboration and MCP

> Canonical guide hub: https://babblebrush.com/ways-to-use/

babbleBrush gives a human and an AI agent a shared, visible image workspace. The Mac app runs a local HTTP Model Context Protocol server while it is open. An authorized MCP client works against the live app state rather than a detached copy: canvas selections, version selections, new edits, generation progress, and batch work can be seen by both participants.

## Recommended collaboration loop

1. The human opens babbleBrush and the relevant canvas, or asks the agent to create one.
2. The agent calls the state-inspection tool first to learn which canvas, version, model, and viewing mode the human is currently using.
3. The agent reads the canvas's version graph and chooses an explicit parent version.
4. The agent creates an edit or background-removal branch. Long operations can return immediately and be monitored, or the agent can wait for completion.
5. The result appears in the live version graph. The human can compare it, select it, branch another direction, export it, or ask the agent to continue.
6. For a set of images, the agent uses a batch canvas so the action, progress, outputs, failures, and spend remain grouped and inspectable.

## MCP capability groups

- **State and discovery:** inspect the human's current location, list canvases, list available models, and see whether provider credentials are configured.
- **Canvas control:** create, rename, select, and inspect normal canvases.
- **Version control:** read the full graph, select a version, retrieve a version or image, and branch an AI edit or local background-removal operation.
- **Synchronization:** wait for app changes and generation completion without repeatedly guessing the state.
- **Batch control:** list, create, select, inspect, and delete batch canvases; import source images; start, inspect, stop, and retry runs; retrieve individual output images.
- **Cost context:** read estimated spend on versions, canvases, batch runs, and batch canvases.

## Connection and authorization

Open **Settings → Connect an agent (MCP)** in babbleBrush and confirm that the server status is Running. The Setup menu provides client-specific commands where available and a generic MCP configuration JSON. The local discovery file at `~/.babblebrush/mcp.json` contains the current endpoint information for compatible tooling. Endpoint and token values are specific to the user's Mac and must not be copied into public documentation or shared with an untrusted party.

## Behavioral guidance for connected agents

- Inspect current state before changing the canvas.
- Name canvases and prompts clearly so the human can understand the graph later.
- Branch exploratory alternatives from the same parent rather than serially mutating one direction.
- Do not delete a batch canvas or other material work without explicit user intent.
- Surface estimated provider cost before starting a large or expensive operation when the information is available.
- Remember that AI generation sends image data to the provider selected by the user; local background removal does not require a provider call.

## Client guides

- [Claude](https://babblebrush.com/ways-to-use/claude.md)
- [Codex](https://babblebrush.com/ways-to-use/codex.md)
- [OpenClaw](https://babblebrush.com/ways-to-use/openclaw.md)
- [Hermes Agent](https://babblebrush.com/ways-to-use/hermes-agent.md)