> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchestrahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestra in your agents (MCP)

> orchestra enable registers Orchestra's MCP server with Claude Code, Codex, Cursor and VS Code, so every agent on your machine can recall and remember. A small default tool set, with more one setting away.

`orchestra enable` gives every agent on your machine Orchestra's tools:
`recall` before re-deriving past work, `remember` when a decision is made, and
your issues. You type nothing else. The server is the `orchestra` binary you
installed, started by the agent as `orchestra mcp`. It talks to the agent over
stdio, so there is no URL to configure and no separate sign-in: it uses the
same backend and sign-in as the rest of the CLI.

## What enable does

For each client installed on this machine, enable registers the server once,
for you, in every project, and prints one line saying what it did:

```
MCP server: every agent on this machine can recall and remember through Orchestra (/Users/you/.orchestra/bin/orchestra mcp)
✓ Claude Code: registered for every project (user scope)
✓ Codex: registered
✓ Cursor: registered in ~/.cursor/mcp.json
✓ VS Code: registered
```

| Client | How it is registered |
| - | - |
| Claude Code | `claude mcp add --scope user orchestra -- ~/.orchestra/bin/orchestra mcp`. User scope, so it is in every project and nothing is written into your repository. |
| Codex | `codex mcp add orchestra -- ~/.orchestra/bin/orchestra mcp` |
| Cursor | Cursor has no command for this, so enable adds an `orchestra` entry to `~/.cursor/mcp.json` and keeps everything else in the file. |
| VS Code | `code --add-mcp`, with the `code` command from your PATH or from the app. |

A client that is not installed is skipped and says so. Running enable again
changes nothing. When an older Orchestra install registered the server at a
different path, enable points it at this one. When a client runs Orchestra
from a build in a checkout of Orchestra's source (`node
.../packages/mcp/dist/bin.js`, or `node .../apps/cli/dist/index.js mcp`),
enable names each one and asks before pointing it at this install; the answer
is yes when you press Enter, pass `--yes`, or run enable with no terminal. When
something else is registered under the name `orchestra` (a hosted server URL,
a wrapper of your own), enable leaves it alone and tells you.

The desktop app's Orchestra Local setup does the same registration.

## The tools an agent gets

Every tool definition sits in the agent's context on every turn, whether or not
it is used, so the server offers a small set by default:

| Tool | What it does |
| - | - |
| `recall` | Searches your workspace's memory and session history, with citations |
| `remember` | Saves a decision or fact so later sessions can recall it |
| `get_me` | Who the agent is acting as, and the workspace's issue statuses |
| `list_people` | People and agents in the workspace, to assign or mention |
| `list_sessions` | Recent agent sessions |
| `list_issues` | Issues, filtered by status, assignee or project |
| `get_issue` | One issue in full |
| `save_issue` | Creates or updates an issue |
| `add_issue_comment` | Comments on an issue |

These are the tools agents actually called: in 998 Orchestra tool calls across
128 recorded Claude Code sessions, these nine were each used in at least ten
sessions and made 94% of the calls. In Orchestra Local, the server offers
every tool Local answers on your laptop, with no setting: `recall`,
`remember`, `list_memories`, `forget`, `share_memory`, the team tools
`message_teammate` and `ask_team`, the setup tools, `get_me`, `list_people`,
the issue tools `list_issues`, `get_issue`, `save_issue` and
`add_issue_comment`, `list_sessions`, and the tools that answer why code is
the way it is: `sessions_for_commit`, `get_session`, `list_session_messages`
and `fork_session`. On Local, `list_sessions` lists your sessions and, on
every plan, the sessions teammates published to the repo's git, newest first,
each with the name of the person who started it. `get_session` and
`list_session_messages` read a teammate's published session read only, on
every plan. `fork_session` makes it a new private session of yours, on the
Team plan (forking your own is free).

Local also offers `dispatch_session` and `post_session_message`, so one agent
session can run others on your laptop (see
[One session runs others](#one-session-runs-others)). Local's issues live on your laptop, and on the Team plan
they reach your teammates through the repo's own git remote, never through
Orchestra's servers (see [Issues](https://docs.orchestrahq.ai/shared-memory.md#issues)). An issue from
Linear is not on Local: the tools say so and point to the hosted workspace.

### Why was this written?

On Orchestra Local, an agent can go from a commit, a line of code or a pull
request to the session that wrote it, and read it. `sessions_for_commit`
takes exactly one of `commit` (a SHA or any revision), `file` with `line`
(`git blame` names the commit that last wrote it), or `pr` (its commits). It
reads the Orchestra-Session trailer that Orchestra's git hook adds to each
commit made in a saved session, and answers with each session, whose it is,
and `atEventId`: the message the commit's turn ended on. Your sessions come
from your laptop; a teammate's from what they published to the repo's git.
`list_session_messages` then reads it, and `fork_session` with `atEventId`
continues it from that moment as a new private session of yours. A commit
made without the git hook says so (run `orchestra enable` to add it), and a
teammate's session that was never published says whose it is, so you know
who to ask. The same answer is `orchestra why` in a terminal.

### One session runs others

On Orchestra Local, an agent in Claude Code or Codex can start other agent
sessions on your laptop and hear back from them, with nobody carrying
messages in between.

`dispatch_session` starts a session from a prompt, in the harness you name
(`claude-code`, `codex` and the others your laptop has). It runs in its own
git worktree under `~/.orchestra/worktrees`, on a new branch made from the
remote's default branch as it is now, so it never edits the folder you or the
dispatching agent are working in. The answer comes back at once with the
session's id, its folder and its branch. No terminal window opens: the
session runs in the background, and you can watch it with `orchestra tui` or
in the desktop app. Orchestra Local starts sessions on this machine only.

A session is named by its id or by any unique start of it, six characters or
more: the eight characters every screen shows are enough. `get_session`,
`list_session_messages` and `post_session_message` all take that short id.
`post_session_message` reaches any session you can see: one of your own, or a
teammate's live session on their laptop over the relay, where their own rule
decides whether your agent may message it. A private session of someone
else's is never listed, read or written to, and its short id reads exactly
like one that does not exist.

`list_sessions` and `get_session` say, for each session, its harness,
repository and branch, whether it is live, idle or ended, what it did last,
`needsYou` when its agent asked a question and is waiting, and `dispatchedBy`:
the session that started it.

A dispatched session knows who dispatched it, because its prompt says so. It
is told to report with `message_session` when it starts, opens a pull
request, is blocked or is done. Orchestra also reports by itself, so nothing
depends on the agent remembering: when the worker starts, when it opens a
pull request, when it asks a question and waits, and when it stops, with its
last words. The pull request and question reports come from Claude Code
workers today. Each report arrives in the dispatching session at its next tool
call, or wakes it if it is idle, and names the worker's session. This works
when the dispatching session is a plain Claude Code session in a terminal
with Orchestra enabled.

## Turn on more tools

The rest come in groups. Turn a group on with the `mcp.tools`
[setting](https://docs.orchestrahq.ai/settings.md):

| Group | Tools |
| - | - |
| `sessions` | `get_session`, `list_session_messages`, `dispatch_session`, `post_session_message`, `interrupt_session`, `rerun_session_request`, `fork_session`, `answer_question` |
| `issues` | `get_issue_template`, `draft_issue_prompt`, `assign_issues`, `prioritize_issues` |
| `memory` | `list_memories`, `forget`, `share_memory`. Always on in Orchestra Local |
| `team` | `message_teammate`, `ask_team`. Always on in Orchestra Local, where they answer: see [When a teammate's agent asks yours](https://docs.orchestrahq.ai/shared-memory.md#when-a-teammates-agent-asks-yours) |
| `setup` | `get_setup_status`, `apply_setup`. Always on in Orchestra Local, where they answer: see [Share your setup](https://docs.orchestrahq.ai/share-setup.md) |
| `commits` | `sessions_for_commit`. Always on in Orchestra Local, the only place it answers: it reads your checkout |
| `docs` | `list_docs`, `search_docs`, `get_doc`, `save_doc` |
| `graph` | `get_neighbors` |
| `capture` | `save_session`, `save_screenshot`, `save_preview` |
| `files` | `list_project_files`, `search_project_files`, `read_project_file`: the files people put on a project, and the text inside them (each match names its file and page, or a notebook's cell). A text file comes back as text. In a research workspace a notebook comes back cell by cell, its code and saved text outputs, and `recall` also names the notebook cells that answer a question, from the projects the agent's person can see; nothing in a notebook is ever run. For a PDF or an image the agent gets its path on this computer, or a download link that lasts a few minutes on a cloud workspace, and reads it with its own tools. An agent started on an issue in a project also begins with the passages of that project's files that bear on the issue, each naming its file and page. Those passages are part of the session from then on: if the issue later moves out of a private project, its sessions move with it, and everyone who can then see a session can read the passages it started with |
| `research` | `search_runs`: the Weights & Biases runs shown on a project in a research workspace, with each run's metrics, config, commit and link, and the agent session that produced it when its commit matches one Orchestra captured. A session you cannot see is not named |

In `~/.orchestra/settings.json`, for every project:

```json theme={null}
{
  "mcp": { "tools": ["docs", "sessions"] }
}
```

Or in a repository's `.orchestra/settings.json` for that project only, or in
the environment: `ORCHESTRA_MCP_TOOLS=docs,sessions`. `"all"` turns on every
group. The server reads the setting when an agent session starts it, so a
change reaches the next session.

## Check it

`orchestra doctor` says, for each installed client, whether the server is
registered and the command that fixes it when it is not. A client whose
`orchestra` server runs something other than this install (an older install, a
build from a checkout, or someone else's server) gets a warning that names the
client, what it runs, and the fix: `orchestra enable` for one of Orchestra's
own. In the folder you run doctor in, it also warns about a Claude Code server
registered for that folder alone (local scope, or the folder's `.mcp.json`),
which Claude Code uses there before the one for every project. It then starts
the server the way a client would and reports the tools it answers with and
which groups are on:

```
✓ MCP: Claude Code has the Orchestra server registered
✓ MCP: Codex has the Orchestra server registered
✓ MCP: the server answers with 9 tools, the default set (get_me, list_people, ...)
✓ MCP tool groups: none on. The mcp.tools setting turns more on (docs: Settings)
```

In Claude Code, `claude mcp list` shows `orchestra: ... - ✔ Connected`.

## Leave a client out

To skip registration, set `ORCHESTRA_MCP_CLIENTS=off` when you run enable, or
name only the clients you want: `ORCHESTRA_MCP_CLIENTS=claude-code,codex`. To
remove the server from a client, use the client's own command, for example
`claude mcp remove --scope user orchestra` or `codex mcp remove orchestra`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.