Skip to main content
Glama

opencode-army-mcp

An MCP server that lets an orchestrator bot run a free-model OpenCode worker army. It can inspect the fleet, start and queue tasks, plan waves, tune policy, open PRs, and restart itself.

Safety invariants are hardcoded in src/invariants.js and checked at boot:

  • A1 — only free model ids (opencode-go/*-free, OpenRouter :free, a narrow Zen-free allowlist). Paid models are refused; an empty free pool queues work rather than falling back to a paid model.

  • A2 — no merge to main, no push to protected branches, no deploys. Pushing an oc/* branch and opening a PR is allowed.

  • A3 — workers write only under a configured worktree root. Named production trees may be registered as read-only git sources, never as a working directory.

  • A4 — no tool returns a secret. Sensitive paths are unreadable; log output is redacted.

  • A5 — the only LaunchAgent it may restart is its own (configured label).

The rules are not configurable at runtime. The paths and hosts they apply to (worktree root, protected trees, listen address, token file, order-book directory) come from environment variables. There is no baked-in private layout.

A product-specific booking front door that lived beside this server in the original tree is not included here.

Stack

Node.js 20+, @modelcontextprotocol/sdk, zod. Tests use node --test.

Related MCP server: pi-mcp

Setup

npm install
cp .env.example .env   # optional; most values have local defaults
# write a bearer token (mode 600) to ~/.config/opencode-army-mcp/token
# or let the server generate one on first boot
npm test                  # unit tests; Mac-only integration tests are skipped
# ARMY_LIVE_TESTS=1 npm test   # also run tests that need this machine's layout
node src/index.js      # loopback, dispatch unarmed unless COS_MCP_DISPATCH=1

Config

The default worktree root is ~/oc-worktrees (override with ARMY_WORKTREE_ROOT). See .env.example. Important variables: ARMY_WORKTREE_ROOT, ARMY_PROTECTED_PATHS, COS_MCP_TOKEN_PATH, COS_MCP_DISPATCH, ARMY_LAUNCHD_LABEL. Optional order-book tools talk to ARMY_HQ_DIR if you have that CLI; they are skipped if it is absent.

Licence

MIT, Copyright (c) 2026 Emil Senkel.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables supervising and coordinating local coding agents across allowed repositories, including inspecting context, reviewing sessions, launching or continuing tasks, and retrieving redacted logs under owner-controlled access.
      17 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Orchestrates multiple coding agents at once so an MCP client can delegate implementation work while retaining judgment: each agent runs in its own isolated git worktree and branch, claims the files it edits, and communicates via a mailbox and shared board. Supports blocking questions to the orchestrator, Codex-written acceptance tests locked before workers start, scope validation, and reporting on first-pass success.
      1
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables Codex to orchestrate persistent Pi RPC workers over a local MCP server, spawning dev, explore and review agents in isolated git worktrees or in place. Codex can inspect status, activity, token/cost metrics and real diffs, then merge only the accepted work and clean up idle workers.
      13
      MIT