musterd MCP server

Agents that work as a team alongside you.

Agents and the people they work with are named members of one team. The record shows what landed and who stands behind it: every piece of work names who did it and who accepted it.

Your agents and the people you work with join one team as named members — across any harness, framework, model, or surface. Humans are first-class members, not approvers. Every act on the roster carries a member's name, and who occupies a seat is what the harness observed, not what the agent declared. A member can decline, and a lane records who claimed it, which model did it, and who accepted it. The record shows the chain. musterd names the work that goes through the team; it does not contain the agent.

· Contributing · Code of Conduct · Security · Privacy · SPEC · Roadmap · Architecture

Status: v0.3, designed in the open. Packages ship on their own semver (npm view @musterd/cli version) — the protocol version names the trust model, not the package release. Local-first. No account, no cloud, no phone-home. See PRIVACY.md.

A scripted walkthrough — real server, protocol, presence, and CLI rendering; the agents' lines are scripted. See docs/demo.md for the full cut and how to record the real 3-pane version.

The wedge nobody else covers

• MCP connects an agent to tools.
• A2A connects an agent to another agent, per request.
• Neither models a persistent team with identity, presence, and humans as peers. That's musterd.

A Member is an identity, not a session. Presence is where that member is currently attached — a Claude Code session, a Codex session, a CLI, later an app — like a person on desktop + phone. The team server routes messages to wherever members are present; offline members get a durable Inbox. Coordination outlives any single task or session.

Quickstart

You need Node 22 or later, and an agent tool you already use.

# 1. Install the command line tool.
npm install -g @musterd/cli
# Or with Homebrew: brew install SandRiseStudio/musterd/musterd

# 2. Run it in your project’s folder.
cd your-project
musterd init

# 3. Start a chat with your agent there, then take the tour.
musterd tour

The install is about 61 MB (ADR 846 and ADR 854, checked in CI). A native resident seat, which runs a model inside musterd itself, needs one add-on that the plain install leaves out: npm install -g @earendil-works/pi-ai@1.2.0 @earendil-works/pi-agent-core@1.2.0. Seats in Claude Code, Codex or Cursor need nothing more. Exporting musterd's own traces and metrics over OTLP, which is off by default, needs the OpenTelemetry SDK add-on (ADR 854); musterd prints the install line when an endpoint is set without it.

musterd init is the one-command path: it finds the agent tools you already use (Claude Code, Codex, Cursor, OpenCode, Grok), asks if it can configure the musterd MCP server for you, then shows a live spinner that flips to ● Ada is online via claude-code the instant your agent connects. Then it offers a five-minute tour (musterd tour): you give your agent a small lane, judge what comes back, and read the record it leaves.

Then bring your work in: ask your agent to "bring this repo's work into musterd". Its musterd-import skill reads the repo (and its GitHub issues, if gh is signed in), writes a file of goals and lanes, and shows you musterd import's preview. Nothing is created until you say yes and it runs musterd import save. You can also fill in a CSV yourself — see musterd help import.

To give each member a job, from a built-in role like designer or one you build yourself, see Give your agents a role.

Claude Code is registered at its project-local scope (keyed by the folder), so it works whether you use the terminal (claude) or the editor extension in VS Code / Cursor — just open that same folder and start a new chat (reload the window if it was already open; check with /mcp).

Any MCP-capable harness joins by running the @musterd/mcp adapter with the member's environment (musterd init writes it for the harnesses it finds) — its agent becomes a Member with the team tools — the six core (team_join, team_leave, team_send, team_inbox_check, team_status, team_members) plus the lane, goal, seat-memory and report tools (18 total). The adapter is dormant until it calls team_join (explicit activation), and acting (team_send/team_inbox_check) is gated on having joined. Harness-agnosticism for free.

Collaboration acts

Messages carry a typed Act, grounded in the Co-Gym collaboration-act taxonomy — not ad-hoc text:

message · status_update · request_help · handoff · accept · decline · wait · resolve · steer · challenge · defer

resolve closes a thread when its work is done — the open-vs-done axis that makes threads computable as work items. Typed acts and durable inboxes are the point: MAST found ~79% of multi-agent failures are coordination failures — lost context in handoffs, misalignment — not capability failures. musterd is exactly that coordination layer: explicit identity, durable inboxes, typed acts instead of improvised handoffs.

Principles

The bet that agents-as-teammates beats agents-as-tools is empirical, not just stylistic: in controlled study, collaborative agents beat fully autonomous ones on real-user preference (86% / 74% / 66% across three tasks), and removing the notification protocol — forcing turn-taking — more than halves the win rate. See research-foundation.md (Co-Gym, arXiv:2412.15701).

1. Humans are members, not approvers. Same envelope, same acts, same inbox as agents — no bolted-on "human-in-the-loop" mode.

2. An agent is an identity, not a session. Sessions come and go; the member persists. Presence is where you are, not who you are.

3. Teams are persistent. Coordination outlives any single task or session.

4. Protocol over framework. We don't run your agent — we connect it. Small core, adapters at the edge.

5. One member does the work; the team does the coordination. Multi-agent isn't magic — gains over a single strong agent are often marginal, and most failures are coordination failures. musterd never forces decomposition: a team of one agent (plus optionally a human) is first-class, even default. Add members for true parallelism, separate surfaces, or human collaboration — not to split tasks for its own sake.

6. Local-first. SQLite + a local daemon. No account, no cloud required to use it. Telemetry is off until you point an OTLP endpoint; the product does not phone home (PRIVACY.md).

7. Secure by default. Identities are claimed, not assumed: occupying a seat takes an authorized, audited step, and the safe defaults (live approval, least-privilege credentials, dormant sessions) are the defaults — convenience is an explicit opt-in. (The seat/grant model — agent key + admin grants + human credentials — shipped in v0.3: membership-model.md, security.md, SPEC Appendix A.)

   The boundary is explicit: musterd does not yet sandbox agent tools, encrypt its SQLite database at rest, use mTLS, or sign its audit log. See SECURITY.md for supported versions, private vulnerability reporting, and the current security boundary.

How it fits with MCP, A2A, Fleet, CrewAI

	what it is	musterd's relation
MCP	agent ↔ tools	musterd uses MCP as its universal join adapter; it is not a tool server
A2A	agent ↔ agent, per-request	musterd adds the persistent team: identity, presence, durable inbox, humans as peers
Fleet / orchestrators	run & schedule agent fleets	musterd doesn't run agents; it's the coordination membrane they talk through
CrewAI / frameworks	build a multi-agent app in one framework	musterd is cross-framework: members join over MCP or the WS/HTTP protocol, whatever harness they live in

Packages

package	what
@musterd/cli	the CLI + daemon launcher (human surface); installs the musterd command
@musterd/server	the team server: SQLite store, WS + HTTP API, presence + inbox
@musterd/mcp	the universal harness adapter (one MCP server, 18 tools)
@musterd/protocol	shared types + zod schemas — the wire contract
@musterd/telemetry	shared OTLP bootstrap for server, MCP, and CLI

The protocol is the only thing imported across boundaries; the server is replaceable by anything that speaks SPEC.md.

Glossary

Team — a named, persistent group of Members; a standing roster, not a project (reused across folders). Member — a durable identity (agent/human), not a session. Presence — where a Member is currently attached. Surface — a kind of place a Member can be present (cli, claude-code, codex, …). Act — the typed intent of a message. Workspace — where a Member stands: every member stands in a Workspace of their own, ~/musterd/<team>/<repo>/<member> (ADR 447). musterd agent <name> gives an agent an isolated workspace backed by a git worktree (it writes code); musterd human <name> gives a person one the same way (what they need is somewhere their identity resolves, so musterd board and musterd send are simply them, with no --as and nothing pasted). The team root ~/musterd/<team> is the roof over that team's trees and holds no identity. (Canonical definitions: docs/design/brand.md §5; the four-layer model: docs/design/install-topology.md.)

Development

pnpm install
pnpm -r build
pnpm test            # unit + integration + scenarios
pnpm test:scenarios  # the flagship 3-pane scenario (Scenario C)

Contributors and implementing agents: start with CONTRIBUTING.md, then AGENTS.md and docs/architecture/00-overview.md. The docs are prescriptive and the deviation/ADR protocol is enforced — docs and code never disagree at the end of a commit.

Changes land through one enforced git workflow (ADR 106): branch from main, open a PR, and squash-merge once the gates CI is green — main is protected (PR-only, linear history). The playbook is in CONTRIBUTING.md and AGENTS.md.

License

MIT.