# Remote agents (MCP) (/docs/rlx/remote-agents)

`rlx serve` exposes a project's board as an MCP server, so Claude clients
that are not sessions in your fleet can work alongside it. The classic case: a
browser-debugging agent in the Claude desktop app files every bug it finds
straight onto the board, and the manager staffs coders to fix them.

A remote client acts as an attributed **virtual session**
(`mcp:<client>:<project>`), scoped to the project. Its tasks and notes show on
the board under its own name, and reach every agent's context the same way a
teammate's do.

## Setup [#setup]

The server needs the `serve` extra, which brings in the MCP SDK (`mcp` 2.1 or
later, below 3):

```sh
uv tool install --python 3.13 'aisquare-cli[serve]'   # the one-line installer's uv tool install
pipx inject aisquare-cli 'mcp>=2.1,<3'                # a pipx install
pip install 'aisquare-cli[serve]'                     # a virtualenv
```

uv cannot add a package to an installed tool, so the first line installs it
again and keeps only the extras it names: list every extra you use, such as
`'aisquare-cli[serve,code]'`. If the extra is missing or the installed `mcp`
is out of range, `rlx serve` says which and prints a fix, though its hint
names only the pip and pipx forms.

Starting the server in a project opts that project in to the board, the same
as `rlx team on`, and says so. A remote client can only reach a project
you have added.

**Claude Desktop (stdio, simplest).** Register a local MCP server in
`claude_desktop_config.json`, and the app launches and owns the process:

First find where `rlx` lives: run `command -v rlx` in your terminal
(for the one-line installer's uv tool install it is usually
`~/.local/bin/rlx`). Claude Desktop does not start the server from your
shell, so it may not find `rlx` on its own `PATH`; give it that absolute
path.

On macOS or Linux, with the path `command -v` printed:

```json
{"mcpServers": {"aisquare-team": {"command": "/Users/you/.local/bin/rlx",
  "args": ["serve", "--stdio"],
  "env": {"AISQUARE_TEAM_HUB": "/path/to/your/repo", "AISQUARE_SERVE_CLOSE_AFTER": "0"}}}}
```

On Windows, with the repo in WSL2, using the path `command -v rlx` prints
inside WSL:

```json
{"mcpServers": {"aisquare-team": {"command": "wsl", "args": ["-e", "bash", "-c",
  "cd /path/to/your/repo && AISQUARE_SERVE_CLOSE_AFTER=0 /home/you/.local/bin/rlx serve --stdio"]}}}
```

Claude Desktop starts the server in your home folder, and the stdio server
refuses to start outside a project root (a folder with `.git`, `.hg` or
`.aisquare`) unless `AISQUARE_TEAM_HUB` is set, so a desktop app cannot adopt
your home folder by accident. `AISQUARE_TEAM_HUB`, an absolute path, passes
that check and picks the board; the WSL form `cd`s into the repo instead,
because `env` in this file reaches `wsl.exe`, not the Linux side. Pointing
`command` at `rlx` with neither fails with `not_a_project`. Avoid a login
shell (`bash -l`) here: anything a login profile prints reaches the client
before the server's first message and breaks the stdio stream. An idle stdio
server exits after 300 seconds without a client message or a running tool
call (`--close-after`); a client that stays connected, like Claude Desktop, should
set `AISQUARE_SERVE_CLOSE_AFTER=0` as above.

**HTTP (for anything else).**

```sh
rlx serve                   # streamable HTTP on 127.0.0.1:8747
rlx serve --show-token      # the URL and the bearer token to give the client
```

Every HTTP request needs the bearer token, which is stored owner-only in
`~/.aisquare/credentials`. `--port` (or `AISQUARE_SERVE_PORT`) changes the port.
The server binds loopback by default, and Windows reaches a server in WSL2
through localhost. `--bind` with anything other than `127.0.0.1`, `localhost`
or `::1` turns off the transport's Host and Origin checks and leaves the token,
sent in clear over plain HTTP, as the only gate; `serve` says so when you do
it. Use another bind only on a trusted network or behind a TLS proxy.

**Name the client** so its board entries read right: set
`AISQUARE_SERVE_CLIENT=browser-debugger` and `AISQUARE_SERVE_ROLE=debugger` on
the `serve` process. Without them the client and its role are both `remote`.

## The eight tools [#the-eight-tools]

The tool surface is deliberately small, because a large MCP surface spends a
client's context before any work happens. Every server has these eight:

| Tool                                        | What it does                                                                                                                                                |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `team_board`                                | The live board: sessions, open tasks, recent updates. Check it first.                                                                                       |
| `task_add(title, role?, detail?, needs?)`   | Add a task, idempotently. `needs` lists the tasks it depends on, as numbers (`12`, `#12`) or ids, comma-separated.                                          |
| `task_next(role?, status?, claim?)`         | The next ready task for a role; `claim=true` claims it atomically, `status="review"` draws from the review pool.                                            |
| `task_update(ref, action, note?)`           | Move a task: `done`, `review`, `block`, `reopen`, `release` or `drop`. `ref` is the task's number on the board or its id. `block` and `reopen` need a note. |
| `note_add(text, kind?, task?, to_role?)`    | Share a note, decision, question or result with every session on the board.                                                                                 |
| `team_log(since_seq?, limit?, by_session?)` | Board events after a cursor. `by_session="me"` reads back the client's own writes.                                                                          |
| `verify(receipt)`                           | Re-check a write receipt (a seq number or event id): is it really on this board?                                                                            |
| `signal(name, value?)`                      | Set or read a named board state as a structured event, never free text.                                                                                     |

One more appears only where it has something to answer:
`code_lookup(query, mode?, limit?)`, which asks the project's symbol index
where a name is defined (`find`), every place it is used (`refs`), or what
already looks like it (`similar`). The server lists it only once the project's
index is built, the same index `rlx code find`, `refs` and `similar`
read. A parked [CI test bed](/docs/rlx/explainability) tool,
`collective_intelligence_recall`, can also register, but only while that
experiment is turned on.

Task numbers work here exactly as on the command line: `12` and `#12` name a
task on the client's own board, never another project's. A failing tool
returns a real MCP error with a stable message, such as `no task #12 on this
board (<name>)`, so a client can correct itself.

Two tools matter most for a client that cannot see your terminal. Every write
returns a `seq` receipt, and `verify(receipt)` proves the write landed, so the
client confirms its own work instead of assuming it. `signal` lets clients
coordinate on payload fields instead of parsing each other's prose. In a
terminal, the same two are `rlx team verify <seq>` and `rlx team
signal <name> [value]`.

A useful set of instructions for a remote debugging agent:

> You are the team's debugger. Check `team_board` first. File every bug you
> find with `task_add` (role `coder`, with repro steps in `detail`). Report
> what you verified with `task_update` and share findings with `note_add`.
> Confirm each write with `verify`.

## A session's own server stays that session [#a-sessions-own-server-stays-that-session]

You can also mount `rlx serve --stdio` inside a Claude Code session,
including a solo one with no team, to use the board tools from it. When the
server can prove that it is that session's own, it acts **as the session**
rather than as a separate teammate:

* Its notes, claims and `team_log(by_session="me")` are the session's own, and
  the board shows one session for the agent, with no extra `mcp:` row.
* A solo session stays solo: calling a board tool does not make it look like a
  team, so it is not handed the board and the team's instructions on its next
  prompts.
* After a `/clear`, a fork or a resume, the server's writes follow the session
  the Claude Code process serves now.

The proof is that the Claude Code process the session's start hook recorded
started this very server, directly or through `uv`, `uvx`, `pipx` or its own
launcher. How you mount the server does not change.

What cannot be proved is still a teammate, as before: Claude Desktop, a server
over HTTP, a server given `AISQUARE_SERVE_CLIENT` or `AISQUARE_SERVE_ROLE`, a
`serve` started from a shell (the Bash tool's included), and a session whose
rlx hooks never ran on this board or that started before you upgraded to
0.9.1, until it restarts.

The stdio server also keeps its protocol pipe to itself: no `git` or tmux
process a tool starts can hold or read the pipe the client writes requests
into.

<Cards>
  <Card title="Tasks and the work cycle" href="/docs/rlx/tasks" description="The same task lifecycle the tools drive." />

  <Card title="The board" href="/docs/rlx/board" description="Where a remote client's tasks and notes show up." />

  <Card title="Control the fleet remotely" href="/docs/rlx/remote-control" description="A different kind of remote: you, from your phone or claude.ai/code." />
</Cards>
