# AgentsRoom MCP

> AgentsRoom exposes itself to the agents it runs, through the Model Context Protocol.

- Area: Desktop app
- Plans: All plans
- Last checked against the product: 2026-10-02
- Web page: https://agentsroom.dev/docs/agentsroom-mcp

## What it does

AgentsRoom exposes itself to the agents it runs, through the Model Context Protocol. Every agent launched in a project gets a set of local MCP servers that let it read and act on the workspace: the backlog, the saved dev commands, the prompt and skills libraries, the project memory, the agent roster and its mail, the saved SSH and database connections, the app settings, and the embedded browser for QA agents. Every one of these actions keeps its manual path in the UI; MCP adds the option to have an agent do it. The servers are small local processes, talking to the desktop on the loopback interface with a token regenerated at every boot. Nothing goes through a cloud.

## Where to find it

- Nothing to install: the servers are declared to each CLI when an agent starts, in the format that CLI reads (`.mcp.json` for Claude Code, a generated `CODEX_HOME` for Codex, `.cursor/mcp.json` for Cursor, per-CLI project configs for the others).
- Inside a session, the agent sees them as `AgentsRoom-MCP` (the main server), `AgentsRoom-Browser` (QA agents only), `AgentsRoom-Test-Runner` and `AgentsRoom-QA-Tester`. Ask an agent to call `capabilities_get` to list what it has.
- Consent prompts appear in the calling agent's panel (spawning another agent, driving a test tool) and can be relaxed in Settings > AI providers & accounts and per project.
- An agent started in a git worktree (a ticket with its own branch, or an agent pinned to a worktree) gets the same tools as one started at the project root. Claude Code and Copilot only read the tool declaration of the folder they start in, so since 2026-09-22 a worktree launch hands them the AgentsRoom servers with its launch options; the other CLIs were already covered. See [Git Worktrees](https://agentsroom.dev/docs/worktrees.md).
- An agent offloaded to a remote SSH host gets the same tools installed on that host before each launch (Claude Code and Codex only, the host needs Node.js and a plain SSH connection), so a remote agent uses the backlog, memory, skills, prompts, dev commands and agent mail like a local one. See [Remote SSH Offload](https://agentsroom.dev/docs/remote-ssh-offload.md).

## How to use it

1. Talk to the agent in plain language: "log this as a ticket", "start the dev server", "save this prompt", "message the QA agent", "what is my quota". The agent picks the tool.
2. Reads (`*_list`, `*_get`, screenshots) never ask for confirmation. Writes follow an etiquette: an explicit request is acted on, an agent's own initiative is proposed first. Deletions require a request naming the item.
3. Some writes are refused by design and the refusal is returned to the agent with its reason: an agent never edits its own configuration, never closes itself, never edits a team definition while a run of that team is live, and never receives a password or secret value.

Tool families, in user terms:
- **Capabilities**: `capabilities_get` describes the connector itself (versions, tool catalogue by family with read / write / destructive marks, what loaded or not and why, the teams connection contract). The call to make when a tool seems missing.
- **Backlog**: `backlog_list` / `_get` / `_create` / `_update` / `_delete` / `_reorder` / `_start_next`, `backlog_comments` (read a public ticket's reporter thread) and `backlog_comment` / `backlog_notify_done` (answer that reporter), `backlog_submit_for_review` / `backlog_review` (a ticket with a reviewer closes only through review), `backlog_link` / `_unlink` (dependencies: a blocked ticket waits by itself), `backlog_publish_mockup`. `backlog_update({ descriptionAppend })` adds to a ticket's trail without rewriting it and answers with the room left, so an agent knows before the description hits its ceiling.
- **Terminal commands**: `commands_list` / `_get` / `_create` / `_run`, project and account scopes; the way an agent starts a dev server instead of a background shell. `commands_output` reads the tail of what a running tab has printed (a saved command, a tab opened through `commands_propose`, or an SSH tab opened with `ssh_connect`), so the agent follows a build instead of launching it twice; it is refused for a command whose text references a `{{secret:NAME}}`. `commands_propose` is the other side of it: a line the agent's own sandbox refused, handed to you as a card to run or refuse (see [Command Proposal](https://agentsroom.dev/docs/command-proposal.md)).
- **Libraries and memory**: `prompts_*`, `skills_*` (upsert by name; `skills_get` takes a skill id or its name, case, spaces and punctuation ignored, so a skill named in the boot prompt needs no lookup), `memory_*`.
- **Agents**: `agents_list` / `_get` / `_save` (saved agent configuration), `agents_spawn` / `agents_close` (a throwaway colleague, confirmed by you), `agents_restart` (the calling agent starts its OWN console over on a fresh conversation, with the first message it wrote, once its turn ends: what `/clear` plus a typed message would do, for context checkpoint routines; see the question below), `team_finalize_run` / `team_cancel_run`, and Agent Mail: `agents_list_live`, `agents_send`, `agents_message_status`, `agents_read_inbox` (the whole mailbox, or one message with `messageId`, which earns its read receipt on its own), `agents_reply`, `agents_ack`, `agents_report_status`.
- **Teams**: `teams_list` / `_get` / `_save` (with `dryRun`) / `_delete`. A big team no longer has to be read or resent whole: `teams_get` and `teams_save` accept `view: "structure"` (every node and edge, prompts replaced by their size and a preview), `teams_get({ node })` returns one node in full with its edges, and `teams_save` takes incremental operations (`nodePatches`, `addNodes` / `removeNodes`, `addEdges` / `removeEdges` / `edgePatches`) that touch only what they name. A step's check command carries its two delays there too (`checkIdleTimeoutSec`, default 120, and `checkMaxTimeoutSec`, default 3600). Inside a run, the run-scoped team server's `team_complete_step` accepts `needsInput: true` among its flags: the run pauses on that step and shows the summary to you as a question instead of moving on. **Triggers**: `triggers_list` / `_get` / `_save` / `_run` / `_delete`. **Ideas**: the `ideas_*` family of the Idea Radar.
- **Connections**: `ssh_list` / `ssh_exec` / `ssh_transfer` / `ssh_connect` / `ssh_connection_new`, which cover SSH servers, AWS SSM instances and Windows hosts over WinRM (`kind: "winrm"`: `ssh_exec` runs one PowerShell line, read-only for agents unless the owner allowed writes, every write confirmed by you in the agent's pane), `db_list` / `db_schema` / `db_query` (read-only) / `db_connection_new`, `secrets_list` (names only).
- **Quota rules**: `quota_rules_list` / `_save` / `_delete`, the rules of Usage > Quota management (block, redirect or adjust a launch, run a trigger, switch running agents when a gauge reaches a threshold), one rule at a time, checked and applied live.
- **Settings**: `settings_list` / `settings_get` / `settings_set` at three scopes: `global` (the machine's app settings), `project` (this project's overrides, with the inherited and effective value shown, `null` removes an override) and `agent` (one saved agent's configuration, by id or exact name).
- **Workspaces**: `workspace_create`, which opens a new workspace of the account from a name and a mission, with no directory to pick. The zone is named as it appears in the sidebar; an unknown name is refused rather than filed at the root.
- **Product knowledge**: `product_help_index` / `product_help_get` / `product_help_search`, the feature-by-feature knowledge base shipped with the app. Any agent can read it, not only the in-app assistant.
- **Git**: `git_set_commit_message` pre-fills the commit box of the calling agent's pill in the Changes tab with its final commit line, following your commit format rules. It commits nothing and runs no git command: the click stays yours. One write per commit cycle: the tool only fills an empty box (a later call answers `alreadySet` and changes nothing), and committing clears it. A message you typed by hand in that box is kept and the tool answers `keptUserDraft`; it is refused when **Agents write their own commit message** is off.
- **Phone**: `notify_user` sends the calling agent's own message to your phone as a push (plus a desktop notification), for an agent working without you that needs a decision, such as a scheduled run keeping your board moving. The title is always the agent and the project; the agent only writes the body (300 characters). One message per agent per minute. It follows your phone notification levels: an agent set to **Off** reaches only the desktop, and the answer tells it so. See [Agent Notifications](https://agentsroom.dev/docs/agent-notifications.md).
- **Account and support**: `usage_overview` (quota per provider and account, anonymous), `projects_list` (every project of the account, the ones open on this desktop first, each flagged `openHere`) plus a `project` argument on the read tools to look into a sibling project, `report_issue` to file a bug about AgentsRoom itself on the AgentsRoom public board.
- **Browser** (QA agents): `browser_navigate` / `_click` / `_type` / `_screenshot` / `_evaluate` / `_get_logs` / `_get_state` / `_wait_for` / `_go_back` / `_go_forward` / `_reload`.

## Settings

- `askBeforeAgentSpawn` (global, Settings > AI providers & accounts; project override; per-agent exemption): confirm before an agent creates another agent. On by default; the cap on live throwaway agents per project applies either way.
- `maxLiveThrowawayAgents` (global, Settings > AI providers & accounts > **Max throwaway agents per project**; project override in Project settings > Capabilities & permissions): how many throwaway agents (created by an agent, the quick agent or a backlog ticket) can run at once in a project. From 1 to 32, 8 by default. Beyond it, `agents_spawn` is refused with a message that names this setting. It is the guard against an agent that keeps creating agents; raise it for orchestration workflows (a coordinator with an implementer and a reviewer per ticket). Also settable with `settings_set { key: "maxLiveThrowawayAgents" }` at global or project scope.
- `askBeforeTestTools` (global, project override, per-agent exemption): confirm before an agent drives the browser, the Electron inspector or the QA test runner.
- `interAgentMessaging` (global): allow agents to write to each other through Agent Mail.
- `agentCommitMessage` (global, Settings > Git; project override in Project settings > Git; per-agent pin): **Agents write their own commit message**. On by default: the agent posts its commit line through `git_set_commit_message` and the commit box stops guessing one from the session title (a backlog ticket title still prefills it). Off: classic prefill and the tool is refused.
- `analyticsOptedOut` (read-only): what `report_issue` checks before attaching app version and OS to a ticket.

## Agent tools (MCP)

This fiche is the tool list itself; see the families above. Only the names listed exist.

## Providers

All providers except Aider, which has no MCP support. Each CLI receives the servers in its own configuration format, written at launch. Codex runs from a generated home so its user-level config is untouched; Cursor needs the servers approved on the command line, which AgentsRoom does. The servers are run with the `node` found on the agents' PATH. Since 2026-09-28, when that `node` is missing or too old to run them (none of the agent CLIs needs Node.js, so many machines have none), AgentsRoom runs them on the Node.js engine built into the app instead: nothing to install, and machines where `node` works are left exactly as before. Remote SSH hosts still need their own Node.js. Some CLIs register the tools under a prefixed name (server name plus tool name); the agent's boot prompt tells it to call the exact name its tool list shows, and after a "tool not found" answer to retry once with the name that answer lists, then stop instead of looping. oh-my-pi on a Cursor model (Composer) is told to call the full prefixed name directly, since that is the only one it can reach. Master (development) agents do not receive the Browser server: browser testing is delegated to a QA agent through the QA test runner tool, which every agent may call after asking you.

## Mobile

Not applicable: the servers run on the machine that hosts the agents. The phone drives agents through the desktop and sees the results (tickets, commands, messages) in its own screens.

One exception: the questions an agent waits on also appear on the phone, above the composer of the agent that asked: **Create an agent?** (`agents_spawn`, with the same provider, model, reasoning-effort and account choices and the same "Stop asking" boxes, tap **Runs on** to change them), **Run this command?** (`commands_propose`) and **Allow a test tool?**. The first answer wins, on either screen.

## Limits

- Tools that create or drive a console (`backlog_start_next`, `agents_spawn`, `agents_close`, `agents_restart`, `commands_run`, `commands_propose`, `ssh_connect`) need the desktop running; reads of the backlog, memory and libraries work with it closed.
- `backlog_start_next` starts a ticket assigned to a saved agent from any computer of the account, not only the one where the project was created. When the machine has no saved agent for the project, it says so instead of failing silently.
- Cross-project access is read-only except `backlog_create({ project })`; machine-local ids (agents, teams, skills, accounts) cannot be passed from one project to another.
- `report_issue` is rate limited (one per minute, three per hour, ten per day) and refuses without a signed-in email.
- No tool ever returns a credential; `db_query` refuses writes whatever the connection allows a human.
- An agent cannot lift its own consent gates or its own telemetry switch.
- The tools need a live sign-in on the desktop for everything stored in your account (backlog, memory, libraries). When that session is signed out or expired, the tools stop calling the server: since 2026-09-19, after one refusal they answer locally "the AgentsRoom desktop session on this machine is signed out or expired. Open the AgentsRoom desktop app and sign in again; no request was sent" until the desktop holds a fresh sign-in. No retry loop, no network traffic in the meantime.
- On a remote SSH host, the AgentsRoom tools are installed for Claude Code and Codex only; over a password-authenticated connection with no open terminal tab on that host, they are not installed and the terminal says "password connection with no open session on this host, open a terminal tab on it first". The agent then runs without them.

## Common questions

- **Do I have to configure MCP servers?** No. They are added to each agent at launch, in the format its CLI reads, without modifying your own MCP configuration.
- **My agent says it has no AgentsRoom tools.** Ask it to call `capabilities_get` with topic `runtime`: it says which modules loaded and whether the desktop bridge is reachable. Aider has no MCP at all.
- **On 1.185.0 no agent of mine had any AgentsRoom tool.** A release accident: the tool server could not start at all, so every agent opened without it. Fixed in 1.185.1, and the build now refuses to publish a tool server that does not load, so the whole set can no longer disappear for everyone at once. Update the desktop.
- **Every AgentsRoom server shows "Failed to connect" or "Connection closed" and I do not have Node.js.** Fixed on 2026-09-28: when `node` is absent or unusable on the agents' PATH, the servers now run on the engine bundled with AgentsRoom. Update the desktop and restart the agents; no need to install Node.js.
- **My oh-my-pi agent on a Cursor model loops on "tool not found".** Fixed on 2026-09-28: the boot prompt now tells it to call the full tool name oh-my-pi exposes on Cursor models and to stop after one retry. Update the desktop and restart the agent.
- **My agent works in a git worktree and has none of the tools.** Fixed on 2026-09-22 for Claude Code and Copilot, which only read the tool declaration of the folder they start in. Update the desktop; nothing to configure and nothing new is written into the worktree.
- **Every tool answers that the desktop session is signed out or expired.** Your sign-in with agentsroom.dev has lapsed; the desktop shows the **Session expired** banner ("Sign in again to reconnect the app to your account."). Click **Sign in** in the desktop: the very next tool call goes through, nothing to restart on the agent's side. Until then the tools refuse locally instead of retrying against the server.
- **Can an agent change my settings?** Yes, when you ask: `settings_set` at global, project or agent scope, with validation. It cannot change its own agent configuration, its own consent gates or the telemetry switch.
- **Why did the agent ask permission before spawning a colleague?** That is the spawn gate. Turn it off in Settings > AI providers & accounts, or per project or per agent, for orchestration workflows.
- **Can an agent clear its own context and carry on without me typing `/clear`?** Yes, since 2026-10-02: `agents_restart({ prompt })`. Built for context checkpoint (handoff) routines: the agent saves its state to a file, calls the tool as the last step of its turn, and once that turn has ended its console restarts in the same tab on a new conversation whose first message is the prompt it wrote ("Read .handoff/latest.md and continue"). Same agent, CLI, model, account and permissions; nothing it did not write down survives. It only ever restarts the caller, never a colleague, and asks for no confirmation. To stop a routine that loops, it allows one restart every 2 minutes and 6 per hour per agent. It is refused for a step of a running Agent Team, for a QA run, and while the project's terminals are shown in another window (detached terminals or the project's own window); a restart whose turn has not ended 30 minutes later is dropped. Works with every CLI that has MCP.
- **Can I set how hard a requested colleague thinks?** Yes: the **Create an agent?** card has a reasoning-effort row in its **Runs on** block, next to the model. It only shows for the CLIs that have an effort lever, its tiers follow the selected model, and **Default** leaves the CLI on its own choice. The same row exists on the phone's card; the desktop must be up to date for the pick to apply.
- **An agent asked for a colleague while I was on my phone, and the request expired.** Before 2026-09-26 the confirmation only showed in the agent's tab on the desktop, and a request nobody answers within 2 minutes creates nothing. Update the desktop and the mobile app: the **Create an agent?** card now shows on the phone too, in that agent's screen, like **Run this command?** and **Allow a test tool?**.
- **An agent says "this project already has 8 throwaway agents running".** That is the runaway guard of `agents_spawn`, not a plan limit. Close a finished throwaway agent, or raise **Max throwaway agents per project** (1 to 32) in Settings > AI providers & accounts, or for one project in Project settings > Capabilities & permissions.
- **Can agents use my SSH servers and databases?** Yes, by reference: `ssh_exec` runs one command and returns the output, `db_query` runs one read-only statement; the desktop injects the credential, the agent never sees it.
- **Can an agent report a bug in AgentsRoom?** Yes, `report_issue` files it on the AgentsRoom public board, with a five-line diagnostic block unless you opted out of data sharing.
- **The commit box already holds a message I did not type.** The agent posted it through `git_set_commit_message` at the end of its turn; only its own pill is affected and nothing was committed. It stays until you commit: later calls from the agent never overwrite it, so edit it by hand if it needs a fix, or turn off **Agents write their own commit message** in Settings > Git to go back to the classic prefill. A message you typed by hand is never replaced.

## Related

- [Backlog Task Board](https://agentsroom.dev/docs/backlog-task-board.md): the board the `backlog_*` tools drive.
- [Dev Terminals](https://agentsroom.dev/docs/dev-terminals.md): the saved commands behind `commands_*`.
- [Agent Messaging](https://agentsroom.dev/docs/agent-messaging.md): Agent Mail in user terms.
- [Agent Delegation](https://agentsroom.dev/docs/agent-delegation.md): the QA test runner and the QA agent.
- [SSH Connections](https://agentsroom.dev/docs/ssh-connections.md) and [Database Connections](https://agentsroom.dev/docs/database-connections.md): the connections exposed by reference.
- [Multi-Provider Support](https://agentsroom.dev/docs/multi-provider.md): how each CLI receives the servers.
- [Workspaces](https://agentsroom.dev/docs/workspaces.md): what `workspace_create` opens.
- [AgentsRoom Help](https://agentsroom.dev/docs/agentsroom-help.md): the assistant built on the `product_help_*` tools.
- [AI Commit Messages](https://agentsroom.dev/docs/ai-commit-messages.md): the commit box that `git_set_commit_message` pre-fills.
- [Agent Teams](https://agentsroom.dev/docs/teams.md): the graph the `teams_*` tools edit and the run-scoped team server.
- [Windows Connections (WinRM)](https://agentsroom.dev/docs/windows-connections.md): the WinRM hosts reachable through `ssh_exec`.
- [MCP Servers](https://agentsroom.dev/docs/mcp-servers.md): your own MCP servers, handed to agents next to these.
- [Remote SSH Offload](https://agentsroom.dev/docs/remote-ssh-offload.md): the same tools installed on the SSH host an agent is offloaded to.
- [Git Worktrees](https://agentsroom.dev/docs/worktrees.md): the isolated checkout an agent now keeps its tools in.