Bloom Docs

Orchestrate with MCP

Connect an agent in your own terminal to Bloom, then turn one conversation into several isolated tasks you can review in parallel.

Start several tasks through MCP

Bloom's owner MCP connects an agent in your own terminal to the projects and workspaces in Bloom. This is useful when a conversation turns into several independent tasks. Ask once, then review the workspaces as they finish.

The outside agent uses project_list to resolve the repository and workspace_start once per task. Bloom shows every workspace in its sidebar. Repeating the same request returns the workspace already created rather than creating a duplicate, and Bloom limits rapid bulk creation to six workspaces in fifteen minutes.

Connect it from Settings › Command Line. Choose Claude or Codex, copy the generated command and run it once. The command is user-scoped, so it belongs to you rather than to one repository. Start a fresh terminal session afterwards.

Connecting your own agent

Bloom can be driven from outside its own window. Connect Claude, Codex or another MCP client and it can work with the projects, workspaces and panes you already have in Bloom. This is most useful when a conversation in your terminal turns into work that belongs in one or more isolated workspaces.

The tools are grouped by the part of Bloom they control. Start with whoami, project_list and workspace_list when you want an agent to orient itself before it changes anything.

• Connection: whoami confirms which copy of Bloom is connected and which capabilities that connection has.
• Projects: project_list, project_add, project_hide and project_unhide inspect and manage the repositories Bloom knows about. Adding a project registers a git repository that already exists on this Mac. It does not create one.
• Workspaces: workspace_list, workspace_start, workspace_rename and workspace_merge start and manage isolated tasks. A merge call asks the workspace agent to perform Bloom's normal merge flow. It does not silently merge the pull request itself.
• Tabs and panes: workspace_tabs, workspace_tab_select, pane_list, pane_open, pane_split, pane_close and pane_rename inspect and arrange chat, terminal and browser panes.
• Terminal: terminal_start, terminal_read, terminal_write and terminal_send_key let an agent start and control a command in a terminal pane, then inspect its output.
• Browser: browser_read, browser_reload, browser_go, browser_scroll, browser_screenshot and browser_text inspect or move a browser pane. Bloom asks before an action moves your page or sends its contents to an agent.
• Quick prompts: quick_prompt_list, quick_prompt_create, quick_prompt_update and quick_prompt_delete manage the reusable instructions shown beside the composer.
• Files and media: reveal opens a project or workspace in Bloom, Finder or a configured editor. media_show adds an image or video from the current workspace to the chat.

Tools that depend on a particular workspace are available to the agent running inside that workspace. An outside client can list projects and workspaces, start work, and use global features, but it cannot guess which open pane you mean. Destructive or privacy-sensitive actions still stop for confirmation.

None of the browser tools runs JavaScript in the page, and that is a decision rather than something we have not got to. The browser pane is your browser, with your session in it, so a script running there could read whatever that session can read and act as you. Asking you first would not fix it either: a permission prompt showing a paragraph of JavaScript is a prompt nobody can really read. So what Bloom offers instead is a handful of narrow verbs it carries out itself: look at the toolbar, take a picture, read the visible text, scroll, reload, go to an address. The two scripts Bloom does run are written into the app, and the only thing a caller puts into either of them is a number. What that costs is worth saying plainly: an agent cannot click a button on your page or fill in a form. If it needs to do that, give it a browser of its own, where nobody is signed in as you.

Only the two that report the window are answered without asking you. pane_list and browser_read say what is open and where each page is pointed, which is what you can see by looking at the screen. Reloading, going somewhere and scrolling all move a page you are reading, and a screenshot or a page's text carries a page you may be logged into to a model, so those five stop and ask every time. Text read off a page comes back marked as somebody else's writing, with the address it came from, so an agent reading it treats it as data rather than as an instruction. A web page can say anything, and some of them are written to be read by a model.

A client connected this way is sitting in no workspace, which shapes the rest. An agent running inside a Bloom workspace never has to say which project it means, because the worktree it is standing in answers that. An outside client is standing nowhere, so it names the project every time, and Bloom resolves that name against projects it already has. Ask for one it does not know and it says so, and lists the ones it does. Ask for a name that two projects share and it refuses rather than picking one, because picking one puts a worktree in the wrong repository.

workspace_list does not look at GitHub unless you ask it to. By default it reads Bloom's own database and nothing else, so it answers in a moment and knows nothing about pull requests or checks. That is worth saying plainly, because the tool answers perfectly happily without them, and a model reading an answer that has no pull request in it can conclude there is no pull request when the truth is that nothing looked. Pass include_github when the answer matters. It costs a gh call and a git call for every workspace in the list, which is slow once the list is long, and that is why it is not the default. The worktree path is in every answer either way, and it is the most useful thing there: it is an ordinary git checkout, so read the diff and the log in it with your own tools rather than asking Bloom for them.

Hiding a project stops nothing. It closes nothing and it deletes nothing. The agents in that project keep running, its worktrees stay where they are, and its workspaces still show up on Home, in search, in the menu bar and in Shortcuts. All it changes is which rows are in your sidebar, which means a hidden project is not a project that is finished with, and every project on the list can still be worked in whether it is hidden or not. Hiding one that is already hidden is not an error and changes nothing. You reverse it with project_unhide, or in the app by turning on Show hidden projects in the sidebar's filter menu.

A workspace you start this way is yours, not an agent's, and Bloom records it the same way it records one made in the Create sheet. There are still two brakes on it, and they are on the tool rather than on you. Bloom will start six workspaces from an outside client in fifteen minutes and then say no, because six worktrees and six agents in a quarter of an hour is what a misread instruction looks like rather than a plan. And a call that is repeated gives back the workspace the first one made instead of cutting a second worktree, because a model that retries is the ordinary way a duplicate happens. Neither applies to Bloom's own window, which starts workspaces with no limit at all, one deliberate press at a time.

project_add registers a repository. It does not create one. That sounds like a quibble and it is the most important sentence here, because add a project reads like it makes something, and it does not. If the folder is not a git repository Bloom refuses it, and it will not run git init to make it one, and the refusal says so in as many words, because an agent told to set my projects up will otherwise decide that creating the repository was implied.

A few real repositories are turned down as well: your home folder, the root of the volume, and anything under ~/bloom/workspaces, which is a worktree Bloom already cut and would leave you with worktrees of a worktree.

Connecting it takes one command. Open Settings › Command Line, choose Claude or Codex and copy the generated command. Run it once in a terminal and start a fresh session afterwards.

claude mcp add --scope user bloom -e 'BLOOM_BRIDGE_ROLE=owner' -e 'BLOOM_BRIDGE_SOCKET=<socket>' -e 'BLOOM_BRIDGE_TOKEN=<token>' -- '<path to bloom-bridge>'

codex mcp add bloom --env 'BLOOM_BRIDGE_ROLE=owner' --env 'BLOOM_BRIDGE_SOCKET=<socket>' --env 'BLOOM_BRIDGE_TOKEN=<token>' -- '<path to bloom-bridge>'

The three angled parts are filled in for you. The socket is where this copy of Bloom is listening, the token is how Bloom tells you apart from the agents running inside its own workspaces, and the last one is the small program that carries MCP from your client to that socket, which ships inside Bloom. Copy the command from the pane rather than typing this one out. Sessions already running will not pick it up, so start a new one and ask it what it is connected to.

The name is derived from the copy of Bloom you are running. The one you downloaded registers as bloom, and a second copy registers as something else, so two of them on one Mac cannot quietly overwrite each other's entry. Earlier versions all registered as bloom-owner-bridge, whatever copy they came from. If you ran that command, the old entry is still in your configuration and Bloom will not take it out for you, so remove it yourself:

claude mcp remove --scope user bloom-owner-bridge

For Claude, leave --scope user alone. Claude Code has three places it can write an MCP server, and only one of them is right here. local is per project, in your ~/.claude.json under that project's own key. project writes a .mcp.json in the directory you happen to be standing in, and that file exists to be committed and shared with everyone who clones the repository, token and all. user is the top level of ~/.claude.json and applies to every project on this Mac, which is what you want, because this connection is yours and belongs to no repository. Nothing in the token gets anyone anything they could not already do sitting at your Mac, since Bloom only answers on a socket that is yours alone, but a credential in a commit is still a credential in a commit.

The token outlives quitting the app, so a connection set up once keeps working. Regenerating it in Settings is revoking it. The old token stops being answered the moment you press the button, and whatever you pasted it into is dead until you run the new command. Do that if it has been somewhere it should not have been, a commit or a screen share.