OpenScout

Local MCP stdio server for discovering coding agents, requesting work, exchanging messages, and tracking handoffs through a Scout broker; requires Bun 1.3+ and trusted local clients.

GitHub

Try this MCPSponsored

Documentation

Scout — your personal agent cloud

Your personal agent cloud.
A local control plane and mesh network for coding agents across the machines you own.

Scout is the CLI, broker, runtime, protocol, and web control surface behind the OpenScout agent mesh. It gives Codex, Claude Code, Cursor, Pi, and future harnesses one explicit coordination model instead of a pile of one-off relays. It also implements a Model Context Protocol (MCP) server that exposes local agent coordination tools to MCP clients over stdio. See MCP setup.

Local control plane + mesh network = your personal agent cloud. Control stays with you while Scout makes sessions reachable and useful across your own machines.

Current posture: Scout is for high-trust local developer pilots. It is not yet a hardened multi-tenant or compliance-ready control plane.

Start on Apple-silicon macOS in 60 seconds

Scout uses Bun 1.3 or newer as its runtime.

bun add -g @openscout/scout

scout setup
scout doctor
scout who

On Linux, Scout uses the same package but runs its broker as a foreground process under your process manager. Follow the quickstart for that lifecycle.

Then route real work from any project:

scout ask --project . --harness codex \
  "Review this repository and return the three highest-leverage improvements."

Scout resolves or starts the right local session, records the request with the broker, and returns durable handles for follow-up.

MCP server

OpenScout includes an MCP server implemented with the official TypeScript @modelcontextprotocol/sdk, using McpServer and StdioServerTransport. The scout mcp command starts it over stdin/stdout. MCP clients call tools that connect to Scout's local broker; the internal Scout protocol describes broker records and is separate from the MCP interface exposed to clients.

Install and connect

Requires Bun 1.3 or newer on macOS or Linux. Initialize the local broker before using coordination tools:

bun add -g @openscout/scout
scout setup
scout doctor

Add this entry to an MCP client's command-based stdio configuration:

{
  "mcpServers": {
    "openscout": {
      "command": "bunx",
      "args": ["@openscout/scout", "mcp"]
    }
  }
}

The client must be able to find bunx on its PATH. The client launches the server and communicates over stdio; this command does not start a public HTTP MCP endpoint. Only connect trusted clients: coordination tools can launch local coding agents, send messages, and update broker-owned work.

MCP tools

Representative tools exposed by the server:

Tools	Purpose
`whoami`	Identify the current broker actor and project context.
`agents_search`, `agents_resolve`	Discover and resolve coding-agent targets.
`ask`	Request work, investigation, review, or a reply from an agent.
`messages_send`, `messages_inbox`, `messages_reply`	Send updates, read messages, and reply in context.
`invocations_get`, `invocations_wait`	Observe an existing flight and its result.
`work_update`	Report progress or change the state of existing work.

Use MCP tools/list to inspect the current tool names and input schemas. ask creates owned work; messages_send is for updates that need no reply. The broker remains the canonical writer of coordination records.

Implementation and verification

MCP server implementation: SDK imports, tool registrations, and stdio transport.
CLI entry point: the scout mcp command.
MCP tests: client/server connection, tools/list, and tool behavior.
Package registry metadata: io.github.oscout/scout, npm package, and stdio launch arguments.
MCP API guide and CLI setup guide.

The small model

You mean…	Use…	What Scout records
“Heads up.”	`scout send --to <target>`	A durable message
“Do this and get back to me.”	`scout ask --to <target>`	An invocation, flight, and reply path
“Start fresh in this project.”	`scout ask --project . --harness <harness>`	A capability-routed session
“Continue that exact run.”	`scout ask --to session:<id>`	A continuation on one concrete session
“Coordinate the group.”	`scout send --channel <name>`	An explicit channel message

One target is a DM. Group coordination uses a named channel. Broadcast is opt-in. Routing lives in structured metadata—not in accidental @mentions inside the message body.

One broker, many surfaces

                                                    ╔══════════════════════╗
                     ╔══════════════════════╗       ║ ◆ Local broker       ║
                     ║ ◆ Scout surfaces     ║       ║ canonical writer     ║
┌────────────────┐   ║ CLI + local web      ║   ┌──▶║ route + run          ║
│ ◆ Operator     │ ┌▶║ one control plane    ║───┘   ║                      ║
│ or agent       │─┘ ║                      ║       ╚══════════════════════╝
└────────────────┘   ╚══════════════════════╝                   │
                                                                │
                                                                │
                                              ┌─────────────────┴─────────┐
                                              │                           │
                                              ▼                           │
                                  ╔═══════════════════════╗               ▼
                                  ║ ◆ Harnesses + mesh    ║      ┌────────────────┐
                                  ║ Codex · Claude · ACP  ║      │ ◆ Records      │
                                  ║ reachable peers       ║      │ durable        │
                                  ║                       ║      │                │
                                  ╚═══════════════════════╝      └────────────────┘

The broker is the canonical writer for Scout-owned coordination records. Harness transcripts remain observed source material; Scout does not bulk-import them as first-party conversation history. “Mesh” means reachability and coordination—not global consensus or exactly-once delivery.

What ships here

Surface	Path	Role
CLI package	`packages/cli`	`scout` command and bundled distribution
Broker/runtime	`packages/runtime`	routing, mesh, pairing, knowledge, durable work
Shared protocol	`packages/protocol`	wire types, identities, runtime catalog
Harness sessions	`packages/agent-sessions`	observed session descriptors and lifecycle
Web control plane	`packages/web`	baseline local operator UI, reusable web primitives, app shell, and local server
Trace tooling	`packages/session-trace`	portable trace model and React viewer
Native services	`crates`	`scoutd`, repo service, portable voice core

Public core, private product

This is the destination for Scout's strong public primitives and a complete baseline web control plane. A public installation should support the ordinary local workflow—setup and health, agents and sessions, conversations and requests, work and activity, runtimes, projects, mesh, and settings—without private-only placeholders.

The product split is an active migration, not a claim that the repositories and release pipeline have already been cut over. The target is one-way: the private OpenScout product consumes exact released public packages and adds native apps, hosted services, advanced operations, and product-specific UI through trusted build-time web composition. It must not carry copied public source or a mirrored packages/web, and public Scout must never depend on private code.

See the public-source boundary for current migration status, target ownership, and release invariants.

Work on Scout

git clone https://github.com/oscout/scout.git
cd scout
bun install

bun run --cwd packages/cli build
./packages/cli/bin/scout --version

Run bun run sync-exec:fence before submitting changes that add or modify shell execution. Use the package-local checks for the area you changed; the complete suite is available through bun run check and bun run test:unit.

Go deeper

Install and verify — supported installation paths and clear success criteria
CLI guide — setup, routing, profiles, sessions, and operator commands
Runtime guide — broker and runtime internals
Protocol guide — integration contracts and shared types
Agent sessions — harness observation and session models
Public-source boundary — what ships here and how package/source parity stays verifiable
Release guide — reviewed-source, package, tag, and registry invariants
OpenScout for macOS — public downloads, updater trust, and verification
Architecture diagram source — editable Arc model behind the README diagram
Brand assets — canonical mark, hero, avatar, and social preview sources
OpenScout — product context and project home

License

Apache-2.0. See LICENSE.