# agent-mesh [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/johnmwhitman/agent-mesh  
**GitHub Stars:** 1  
**npm Downloads (last month):** 8  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/agent-mesh

## Description
Auditable multi-agent coordination: fleets, P2P messaging, witnessed receipts, quorum.

## Tools
Capabilities this server exposes over MCP:

- **spawn_fleet** — Spawn N parallel agents as independent OS processes; each agent may select a registered `runtime` plus its required opaque `workspace_binding`, or use the default OpenCode runtime and optional `model` (`provider/model`) selector
- **spawn_from_template** — Spawn a fleet from a saved template
- **save_fleet_template** — Reusable, versioned fleet configs
- **list_fleets** — All fleets, or one fleet's full state
- **collect_results** — Gather every agent's final output in one call
- **set_fleet_timeout** — Per-fleet timeout override (in ms)
- **attach_agent** — Dynamically attach a premade agent to a running fleet; the agent may set the same optional `model` (`provider/model`) selector
- **send_message** — P2P message (5 types) — or `to_agent_id: "*"` to broadcast to the whole fleet
- **send_messages** — Batched sends, one atomic transaction per batch (up to 1000 messages; larger batches are rejected)
- **get_inbox** — Poll and acknowledge; every ack writes a per-recipient receipt
- **subscribe_inbox** — Push delivery over SSE instead of polling (optional auth token)
- **subscribe_events** — Unified fleet-wide SSE event stream; optional `fleet_id` filter; emits every ledger event kind as it appends (optional auth token)
- **receipt** — Write and query the witnessed-delivery ledger: who saw what, when
- **verify_ledger** — Audit the whole ledger's internal consistency — errors mean it asserts something its own records don't support
- **verify_ledger_v2** — Versioned unsigned-snapshot consistency envelope around the unchanged verifier report from a dedicated read-only file snapshot; the handler performs no ledger writes
- **verify_ledger_v3** — Opt-in detached verifier envelope with severity-derived local consistency labels only; not provenance or confidence; the handler uses a dedicated read-only file snapshot and performs no ledger writes
- **get_build_identity** — Full BuildIdentityReport for the running install — package name/version, source_commit, entrypoint_count, the per-entrypoint SHA-256 map, and the `entrypoints_match_runtime` bit. Dedicated diagnostic name for verifying a specific path's hash against the published manifest. Same surface as `get_heal…
- **open_ratification** — Put a decision to the fleet: quorum, deadline, required sign-offs, optional per-voter weights
- **cast_vote** — An agent votes, on the record — re-casting changes the effective vote without rewriting history
- **tally_ratification** — Resolve outcomes; expire past-deadline votes
- **register_capability** — Self-describe role + skills for routing
- **route_work** — Match a task to the best agent by keyword + role overlap
- **recommend_route** — Advisory ranking for caller-supplied agent/runtime/model candidates, with hard privacy/capability filters and an opt-in near-reset tie-break
- **plan_speculative_backlog** — Pure projection of caller-approved speculative work, preserving route gates and explicitly leaving capacity unmodeled
- **compile_route_candidates** — Pure offline projection of sanitized manifest/observation snapshots; does not rank, persist, execute, authorize, wake, or contact providers
- **record_routing_outcome** — Feed results back to improve routing
- **list_agents** — Discover 100+ premade agent personalities
- **get_health** — Fleet health and liveness. `get_health` accepts an optional `verbosity` argument — `"full"` (default, full BuildIdentityReport including per-entrypoint SHA-256 map) or `"summary"` (entrypoints map omitted for a smaller routine-probe payload). Use the dedicated `get_build_identity` tool for the diag…
- **ask_peer** — Open a bounded Discussion: send the root question, optionally reserve one peer attempt, wait for a settled answer
- **wake_agent** — The sole general-purpose Discussion run trigger — atomically reserve and launch one bounded attempt
- **reply_discussion** — Submit the one reply an active wake attempt is authorized to produce; never launches an agent
- **get_discussion** — Read-only: derive transcript, attempts, budget, and fail-closed status from durable messages and receipts

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agent-mesh": {
    "command": "npx",
    "args": ["-y","--package=meshfleet","--","agent-mesh"]
  }
}
```

## Documentation

## What agent-mesh MCP server does

The agent-mesh MCP server organizes multiple workers into fleets of independent operating-system processes. A fleet can contain agents with separate roles and prompts, and may use the default OpenCode runtime or an operator-configured runtime. Agents can work in parallel, exchange messages, ask questions, and return final results for collection.

Coordination actions are recorded in a ledger. Messages create per-recipient delivery records, including delivery, viewing, and acknowledgement state. Decisions can be opened as ratifications with a quorum, deadline, required sign-offs, and optional voter weights. Agents can cast or change their effective vote, while the underlying history remains recorded.

The project is an MIT-licensed core and is deliberately pre-1.0. Its stated boundary excludes provider-account management, credentials, billing, spending authority, external publication, and managed policy.

## How it works

Use `spawn_fleet` to start a set of agents, or `spawn_from_template` to create one from a saved configuration. Templates can be versioned and reused. `attach_agent` adds a premade agent to an active fleet. Fleet state, health, timeouts, and final outputs are available through dedicated tools.

Agents communicate through direct or broadcast messages. `send_messages` provides atomic batches of up to 1,000 messages. Consumers can poll with `get_inbox`, which acknowledges received messages, or subscribe through server-sent events with `subscribe_inbox`. `subscribe_events` provides a fleet-wide event stream, optionally filtered by fleet.

The agent-mesh MCP server supports operational checks through ledger verification, build-identity reporting, and health inspection. The versioned verifier variants use read-only snapshots and return consistency information; they do not add ledger writes. Routing tools can match work against registered roles and skills, record outcomes, or produce advisory candidate projections without executing providers.

## Setup and configuration

The published package is named `meshfleet`, not `agent-mesh`. Install it globally with `npm install -g meshfleet`, or clone the repository, install dependencies, and build it with `npm install && npm run build`.

For the published package, configure an MCP host to run `npx -y meshfleet` as a local server, then restart the host. The documented primary host is OpenCode. A source checkout can instead run its built `dist/index.js` entrypoint, but the source-checkout configuration is intended for development rather than release use.

The package includes a no-key demonstration command that uses a temporary ledger. A configured ledger can be inspected with the package explicitly selected through npx. `MESHFLEET_DB_FILE` can point to another ledger file when an existing database was created by a newer package version.

Runtime selection is operator-controlled. OpenCode is the default. Other runtimes require their own configuration; some require an absolute command, a version label, and an opaque workspace binding. Model selectors use the `provider/model` form where supported.

## Tools and capabilities

- Spawn fleets, load saved fleet templates, attach agents, and set fleet-specific timeouts.
- List fleet and agent state, collect final outputs, and inspect health or build identity.
- Send direct, broadcast, or batched peer messages and receive them by polling or SSE.
- Write, query, and verify witnessed-delivery records.
- Open ratifications, cast votes, and resolve quorum decisions.
- Register agent capabilities, route work, recommend routes, and record routing outcomes.
- Discover premade agent personalities and run bounded peer discussions with `ask_peer` and `wake_agent`.

## Limitations and notes

The agent-mesh MCP server does not itself provide provider credentials, account operations, billing information, quota data, authentication claims, or external attestation. Runtime wrappers own their authentication, and the server passes a scrubbed environment rather than reading or serializing credentials.

OpenCode is the first-class host described by the project. The core uses standard MCP, but broader host support is presented as demand-driven rather than guaranteed by the README. The project should therefore be tested with the intended MCP client and configured runtime before production use.

The source-only `local-demo` runtime is a deterministic worker for demonstrations and is not included in the published package. It does not silently replace failed real agents. Cryptographic signing and auditor-grade attestation belong to a separate paid layer, while coordination and verification remain part of the MIT core.

_Full upstream README: https://allmcps.com/mcp/agent-mesh/readme_