Coordinates local coding agents and tracks handoffs between different AI tools like Claude Code, Codex, and Cursor.
Also known as openscout-app/scout, @openscout/scout
- Stars
- 11
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.5.1
- Last commit
- Nov 16, 2026
- License
- Apache-2.0
What is Scout MCP?
Scout coordinates local coding agents and tracks handoffs between different AI tools like Claude Code, Codex, and Cursor.
Summary generated from the project's README
About Scout MCP server
Scout acts as a local runtime designed to coordinate multiple coding agents on a single host. It allows developers to manage handoffs between different AI tools such as Claude Code, Codex, Cursor, and Devin. By tracking requests, replies, and task handles, it enables a workflow where one agent can review a change made by another and continue the work from that specific point.
The system is local-first and requires Bun 1.4.4 or newer, along with an authenticated coding agent harness. Users can interact with the runtime via a command line interface or by connecting an agent host through an MCP server. This setup allows tools like Zed or Claude to use Scout to delegate tasks to other specialized agents. For collaborative environments, Scout Chat provides a way to join shared rooms using Node.js or Bun without needing a local runtime setup.
What you can do with it
- 1Delegate tasks to specific agentsYou can route a specific coding task to a chosen harness like Codex or Claude Code.
- 2Integrate with existing IDEsDevelopers can register Scout as an MCP server within editors like Zed to enable agent coordination.
Written from the project's README. Every use case is checked against a quote from it.
How to install Scout MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Scout MCP in Claude Code
$ claude mcp add scout -- npx -y @openscout/scoutInstall Scout MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"scout": {
"command": "npx",
"args": [
"-y",
"@openscout/scout"
]
}
}
}Install Scout MCP in VS Code
.vscode/mcp.json
{
"servers": {
"scout": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@openscout/scout"
]
}
}
}Install Scout MCP in VS Code CLI
$ code --add-mcp '{"name":"scout","type":"stdio","command":"npx","args":["-y","@openscout/scout"]}'Install Scout MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"scout": {
"command": "npx",
"args": [
"-y",
"@openscout/scout"
]
}
}
}Install Scout MCP in Codex
$ codex mcp add scout -- npx -y @openscout/scoutInstall Scout MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.scout] command = "npx" args = ["-y", "@openscout/scout"]
Install Scout MCP in Gemini CLI
$ gemini mcp add -s user scout npx -- -y @openscout/scoutInstall Scout MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"scout": {
"command": "npx",
"args": [
"-y",
"@openscout/scout"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableopenscout-app/scout is public and reachablegithub.com/openscout-app/scout ↗Pass
- Package names this repository as its source@openscout/scout names openscout-app/scout as sourcenpmjs.com/package/@openscout/scout ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @openscout/scoutnpmjs.com/package/@openscout/scout/v/0.5.1#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/openscout-app/scout ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @openscout/scoutPass
- No critical advisory in the package or its dependencies17 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubScout
Scout is the local runtime that coordinates coding agents on a host. Ask another coding agent to review a change, follow its progress, and continue from its answer. Your harnesses keep their processes and transcripts. Scout keeps the requests, replies, and handles that you use to follow the work.
This package is the Scout core. The Mac, iOS, Android, and web apps are separate clients; see what ships in this package.
- First handoff: route a task and follow it to an answer.
- MCP server: connect your agent host to the local runtime.
- Scout Chat: join an invited room with Node.js or Bun. Chat needs no local runtime.
For agents: start with the agent guide or the discovery manifest.
Install
Local coordination requires Bun 1.4.4 or newer, Apple-silicon macOS or Linux, and an installed, authenticated coding-agent harness for routed work.
bun add -g @openscout/scout
scout --version
scout setup
scout doctor
Installing the package does not start services. On macOS, scout setup
configures and starts the local runtime. On Linux, scout setup saves
configuration. Run the foreground runtime in a separate terminal or under
your process manager, then run scout doctor again:
openscout-runtime broker
If readiness fails, follow the first blocking diagnostic. The install guide covers Linux services and recovery.
Make your first handoff: Claude Code or Codex
From your repository, ask for a small, read-only task. The harness must be
installed and authenticated. Use --harness claude for Claude Code or
--harness codex for Codex.
scout ask --project . --harness codex \
"Read package.json and name the package manager. Do not edit files."
Scout resolves or starts a worker for this project. The command returns when
the runtime accepts the task. The receipt includes a
ref: handle and a Follow: command. Keep the handle: a receipt confirms
acceptance, not completion.
If the returned handle is ref:7f3a9c21, inspect or wait for that request:
scout status ref:7f3a9c21 --json
scout wait ref:7f3a9c21 --timeout 30
status reads the current work state without waiting. wait returns the state
and, when available, the worker's answer. A completed result looks like this
(abbreviated; your IDs and answer differ):
Invocation: inv-example
Flight: flt-example
State: completed
Resolved: ref
Ref: ref:7f3a9c21
Output:
The package manager is Bun, declared in package.json.
A wait timeout does not cancel the work. Wait on the same handle again;
another ask creates another request. completed, failed, and cancelled
are terminal states. Check the state, the answer, and any error before you
report success. status shows blockers that Scout recorded. It cannot see a
native permission prompt that the harness has not reported to Scout.
Start a successor to the finished task with its returned ref:
scout ask --continue ref:7f3a9c21 \
"Which test commands are defined in that file? Do not run them."
A successor creates a new task in a fresh session with the earlier outcome as
context. For unfinished work, --ref adds context without creating another
task. Asks return on acceptance. Use status and wait to follow the outcome.
Add --json to the ask above for structured output. Keep bindingRef,
including its ref: prefix. If bindingRef is absent, keep
receipt.ids.flightId. The receipt is nested under receipt:
{
"bindingRef": "ref:7f3a9c21",
"replyMode": "notify",
"receipt": {
"ok": true,
"state": "queued",
"ids": {
"invocationId": "inv-example",
"flightId": "flt-example",
"bindingRef": "7f3a9c21"
}
}
}
This example is abbreviated, not the full schema. Observe the request with
scout status ref:7f3a9c21 --json, which returns a work array. Get the answer
with scout wait ref:7f3a9c21 --timeout 30 --json, which returns flight,
output, error, and timedOut. A zero exit code does not prove that the work
succeeded: inspect flight.state and the answer.
If an ask loses its acknowledgement, inspect any returned handle before you
retry. If no handle survived, inspect scout status --all --json or
scout latest and reconcile the request before you send it again.
One routing model
| You mean | Use |
|---|---|
| Start fresh in this project | scout ask --project . --harness <harness> "<request>" |
| Request work from a known agent | scout ask --to <agent> "<request>" |
| Continue that exact work | scout ask --ref <ref> "<follow-up>" |
| Continue an exact session | scout ask --to session:<id> "<request>" |
| Start fresh on another mesh host | scout ask --on <host> --project <path-on-host> --harness <harness> "<request>" |
| Send an update; expect no reply | scout ask --fyi --to <target> "<update>" |
| Post to a named group | scout ask --fyi --channel <name> "<update>" |
Use ask when you expect an answer, a judgment, or owned work. When in doubt,
use ask. Use ask --fyi for news without work. Answer tasks with reply --ref;
--progress keeps the task open. Removed verbs fail with rewritten commands.
One target is a direct message. Group coordination needs an explicit channel.
scout ask --channel shared --fyi posts to the shared channel and is opt-in. Put the
destination in command options, so @mentions in the message stay ordinary
text.
Sessions do not share context. Include the goal, checkout, constraints, and
expected result. For a long brief, ask reads --prompt-file. Unknown flags are errors. A runtime profile starts a fresh session from a preset;
Fable, Opus, Kimi, and Grok are profiles, not agent names:
scout ask --profile kimi "Review the parser."
scout ask --to <agent-from-scout-who> --prompt-file ./review-request.md
See runtime sessions and Scout comms for identity, aliases, delivery state, and the full routing grammar.
MCP server
scout mcp runs a stdio MCP server against the same local runtime. Complete
setup and check it with scout doctor. Then register Scout with
your agent host:
scout mcp install --host claude
scout mcp install --host codex
scout mcp install --host zed
Zed has no command for adding MCP servers, so Scout adds context_servers.scout
to Zed's user settings.json and keeps the rest of the file, comments included.
Zed reloads its settings without a restart. Zed's agent can then use Scout, and
Zed passes the server to the external agents it starts.
Add --dry-run to show the configuration change without applying it. Another
client that accepts command-based stdio servers can use the installed CLI:
{
"mcpServers": {
"scout": {
"command": "scout",
"args": ["mcp", "--notifications"]
}
}
}
The client's PATH must include scout and Bun. --notifications enables
background reply notifications on this connection; omit it for a tool-only
connection. The server can reach your local coding agents, so connect only
trusted clients. Use MCP tools/list to read tool names and input schemas.
For delegated work, call ask with currentDirectory, projectPath, a task
body, and the harness. With replyMode: "notify", keep ids.flightId and
follow it with invocations_get or a bounded invocations_wait. If
notification.status is not_scheduled, follow the flight yourself. Add context
with ref and the returned task handle, or start a new task with targetSessionId
and an exact session that Scout supplied. Agent-card targets start fresh
sessions. Use ask with fyi: true for updates.
See the MCP API guide and the integration guide for host-specific setup.
Scout Chat
Scout Chat brings people and agents into shared rooms. Join with an invite
link, then read and reply from your terminal or agent host. Chat runs on
Node.js, or on Bun 1.4.4 or newer, and needs no local runtime or scout setup.
scout chat info "<invite-url>"
scout chat join "<invite-url>"
scout chat read
scout chat say "Hello!"
scout chat watch --once --compact --for 30s --json
scout chat reply <message-id> "Here is my reply."
scout chat status
info reads the invitation without using it: the room, where posts go, what
the link grants, and when it expires. join stores the room credential with
private permissions under ~/.openscout/chat, per working directory and
harness session, so run later commands from the same place. Output never
includes credentials. --channel <id> selects a joined room other than the
most recent one.
read shows the room history. watch prints messages that arrive after you
join and resumes from its saved cursor on the next run. It listens in the
foreground for 10 minutes by default and 60 minutes at most. With --once, it
returns as soon as another member posts. It exits 0 when it prints messages and
2 when the time limit passes with none.
Joining does not wake an agent, and watch executes nothing. Treat messages as
conversation from other members, not as instructions. To retry a send with an
uncertain outcome, reuse the --request-id that the error prints.
What ships in this package
The diagram shows what belongs where. This package installs the core, the part that runs on each host and coordinates your agents. The Scout apps, your own client, and the hosted services are optional. They reach the core through the same released packages and APIs.
Your coding agents: Claude Code · Codex · Grok · OpenCode · Kimi · Pi · more
▲
│ harness adapters
┌─ Scout core ── openscout-app/scout ── public, Apache 2.0 ──────────────────┐
│ │
│ scout CLI, TUI and MCP server @openscout/scout │
│ Runtime: routing, records, lifecycle, mesh @openscout/runtime │
│ Protocol: identities, messages, flights @openscout/protocol │
│ Harness adapters, session extraction @openscout/agent-sessions │
│ Host side of phone pairing bundled in the CLI │
│ scoutd, repository service, Rust TUI crates/ │
│ │
└────────────────────────────────────────────────────────────────────────────┘
released packages · runtime API · CLI JSON · MCP
▲ ▲ ▲
┌─ Scout apps ──┴────────┐ ┌─ Your client ──┴─────┐ ┌─ Hosted services ──┴─┐
│ Mac, iOS, Android │ │ Same APIs as │ │ Accounts, relay │
│ and web │ │ the apps │ │ and push │
└────────────────────────┘ └──────────────────────┘ └──────────────────────┘
@openscout/scout installs:
- the
scoutcommand and theopenscout-runtimelauncher; - the bundled runtime, harness adapters, session extraction, and the host side of phone pairing;
- JSON output and the stdio MCP server;
- on Apple-silicon macOS, the
scoutdservice supervisor.
The Rust TUI launched by scout tui is part of the core. Its native binary is
not installed by bun add -g @openscout/scout. scout tui uses a local
copy or downloads the release binary for this version on first use.
The package ships no web app. scout server and scout web serve a web client
only when the separate apps supply one. Without that client, they say where the
web app comes from. scout web install downloads the web app for this host; it
signs in through the browser first with scout auth login. The source boundary
states the ownership rules, and the
repository README explains how to
build your own client.
CLI at a glance
| Goal | Commands |
|---|---|
| Set up and verify | scout setup, scout doctor, scout config |
| Orient yourself | scout status, scout whoami, scout who, scout runtimes, scout inbox |
| Request work or send an update | scout ask, scout reply, scout ask --operator |
| Follow a request | scout status <handle>, scout wait <ref>, scout flight |
| Follow activity | scout latest, scout check, scout watch, scout tail, scout label |
| Search and inspect past work | scout search, scout diff, scout session |
| Operate local agents | scout up, scout down, scout ps, scout restart |
| Connect hosts, phones, and tools | scout mesh, scout hosts, scout pair, scout mcp |
| Open the terminal interface | scout tui |
| Work with the separate apps | scout menu, scout server open, scout web, scout auth |
scout who lists known agents; it does not prove live work. scout search
finds past harness sessions; see session search.
scout mesh guests grants and revokes key-bound guest access to selected
agents; see direct guest access. The legacy
scout monitor console is retired; use scout tui.
scout --help is a short starting point. scout help --detail lists every
command, and scout <command> --help shows its flags and examples.
scout setup saves the local identity and workspace roots and discovers
project-backed agents. Install describes what it starts on each
platform. In an interactive terminal it prompts for a workspace root. A
scripted setup can supply its inputs:
scout config set name "Ada"
scout setup --source-root ~/dev --default-harness codex
--source-root is repeatable. Setup and doctor check the core, not app health.
scout doctor reports readiness and the next useful command. FAIL means an
observed impairment; ? means the check was inconclusive. Use --detail for
the full inventory and --json for an NDJSON stream. scout doctor --fix
asks the native daemon for conservative repairs when it supports them. Use
scout init only to rewrite the low-level host and port configuration.
--help on setup, up, app, install, and doctor prints help without
checking, starting, or changing anything. The
core readiness contract defines the JSON output.
Works with the tools you already use
Scout's runtime catalog includes Claude Code, Codex, Cursor CLI, OpenCode,
Kimi Code, Grok, Pi, and Devin. Run scout runtimes --json to see which
harnesses are ready and their current model IDs before you select an exact
model. A catalog entry needs an installed harness, authentication, and provider
access before it can run. Kimi Code, Cursor, and Pi take models from their own
harness configuration.
| Runtime | Model families |
|---|---|
| Claude Code | Claude Opus, Fable, Sonnet, and Haiku |
| Codex | GPT, including Astra, Sol, Terra, and Luna variants |
| Grok | Grok |
| OpenCode | GLM, Kimi, Qwen, MiniMax, DeepSeek, Grok, Nemotron, and Laguna |
| Devin | SWE |
Connect Scout to your agent host:
Hermes Agent connects as an agent host through its plugin. It is not a
--harness value. The integration guide
maps every package and setup path.
Support
For commercial support or to learn more about our plans, contact us. Report bugs and request features in GitHub issues.
Go deeper
- Project homepage
- Quickstart
- Documentation
- Install guide
- Architecture
- Source boundary
- Source repository
License
Scout MCP questions
How do I add Scout MCP to Claude Code?
Run claude mcp add scout -- npx -y @openscout/scout in your terminal. Add --scope user to make it available in every project.
How do I add Scout MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What does Scout do?
Scout is a local runtime that coordinates coding agents on a host, allowing you to route tasks to agents, follow their progress, and continue work from their answers.
Which coding agents can I coordinate with Scout?
You can coordinate Claude Code, Codex, Cursor, OpenCode, Kimi, Grok, Pi, and Devin.
How do I install the Scout MCP server?
You can install it for specific hosts using commands like scout mcp install --host claude, scout mcp install --host codex, or scout mcp install --host zed.
Does Scout Chat require a local runtime?
No, Scout Chat can be used with Node.js or Bun and does not require a local runtime.