worker-mcp

worker-mcp is a Model Context Protocol (MCP) server that empowers a highly intelligent coordinator agent (like Claude 3.5 Sonnet or Gemini Pro) to spawn, control, and interactively guide lower-intelligence, locally hosted worker agents.

Instead of rolling a custom local LLM tool loop, worker-mcp delegates coding, bash, and filesystem operations to the pi coding agent (@earendil-works/pi-coding-agent) by running it in JSON-RPC mode. Since these small local models require significant supervision, worker-mcp acts as a gating and auditing harness.

Features

• Interactive Gating (Consent Hook): Automatically intercepts and blocks high-risk operations (e.g. executing shell commands or writing files) and prompts the coordinator for approval before execution.

• MCP Tool Integration: Standardized tools to spawn worker sessions, dispatch prompts, list active runners, and approve/deny pending commands.

• Log and History Resources: Message history and subprocess logs (including stderr feeds) are exposed as standard MCP resources.

• Session Registry Persistence: Session configurations and directory bindings survive server restarts via state files in ~/.config/worker-mcp/sessions.json.

• Automatic Extension Deployment: Deploys its supervisor gate extension directly into ~/.config/worker-mcp/ and loads it explicitly when spawning the worker agent (leaving standalone pi agent runs unaffected).

Related MCP server: projscan

Installation & Usage

worker-mcp is published on npm as @noosxe/worker-mcp. This is the recommended installation path for most users.

1. Install via npm (Recommended)

Option A: Global Installation

Install the package globally on your system:

npm install -g @noosxe/worker-mcp
# or using pnpm
pnpm add -g @noosxe/worker-mcp

Once installed globally, you can run the server using the worker-mcp command.

Option B: Run ad-hoc via npx

Alternatively, you can run the server on stdio immediately without installing it:

npx @noosxe/worker-mcp

2. Install via Nix

This project also provides a Nix flake to ensure consistent environments and easy installation.

Option A: Run Directly (Ad-hoc)

You can run the server on stdio immediately using Nix:

nix run github:noosxe/worker-mcp

Option B: Install to User Profile

Install the worker-mcp executable globally in your user profile:

nix profile install github:noosxe/worker-mcp

Once installed, run it with:

worker-mcp

3. Declarative Installation via Flake Overlay (System / Home Manager)

If you manage your operating system or user profile declaratively via NixOS or Home Manager, you can consume our default overlay.

Step 3.1: Add the Flake Input

Add worker-mcp to your system's flake.nix input section:

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  
  # Add worker-mcp input
  worker-mcp.url = "github:noosxe/worker-mcp";
};

Step 3.2: Configure the Overlay and Install

Option A: NixOS Configuration

Add the overlay to nixpkgs and include worker-mcp in your system packages:

outputs = { self, nixpkgs, worker-mcp, ... }@inputs: {
  nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
    system = "x86_64-linux"; # Or your system architecture
    modules = [
      ({ pkgs, ... }: {
        # Apply the overlay
        nixpkgs.overlays = [
          worker-mcp.overlays.default
        ];

        # Install the package
        environment.systemPackages = [
          pkgs.worker-mcp
        ];
      })
      ./configuration.nix
    ];
  };
};

Option B: Home Manager Configuration

Add the overlay to nixpkgs and install it in your user packages:

outputs = { self, nixpkgs, worker-mcp, ... }@inputs: {
  homeConfigurations.my-user = inputs.home-manager.lib.homeManagerConfiguration {
    pkgs = import nixpkgs {
      system = "x86_64-linux";
      overlays = [ worker-mcp.overlays.default ];
    };
    modules = [
      ({ pkgs, ... }: {
        # Install the package
        home.packages = [
          pkgs.worker-mcp
        ];
      })
      ./home.nix
    ];
  };
};

Harness Integration (Antigravity CLI / agy)

To register the worker-mcp server with your Antigravity TUI/CLI (agy), follow these steps:

Step 1: Register the Server via mcp_config.json (Declarative)

Antigravity CLI resolves MCP servers from dedicated configuration files (rather than the old settings.json). Add the configuration in one of the following locations:

• Global Configuration: ~/.gemini/config/mcp_config.json

• Project-local Configuration: .agents/mcp_config.json (at the root of your project workspace)

Configuration file schemas:

Option A: If installed globally (via npm or Nix)

{
  "mcpServers": {
    "worker-mcp": {
      "command": "worker-mcp",
      "args": []
    }
  }
}

Option B: If running ad-hoc via npx

{
  "mcpServers": {
    "worker-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@noosxe/worker-mcp"
      ]
    }
  }
}

Option C: If running ad-hoc via GitHub Flake

{
  "mcpServers": {
    "worker-mcp": {
      "command": "nix",
      "args": [
        "run",
        "github:noosxe/worker-mcp?ref=main"
      ]
    }
  }
}

Option D: Declarative Home Manager Configuration

If you manage your user configuration via Home Manager, you can declare the global mcp_config.json file in your home.nix using home.file combined with builtins.toJSON:

home.file.".gemini/config/mcp_config.json".text = builtins.toJSON {
  mcpServers = {
    worker-mcp = {
      # If installed via overlay in system/home packages or globally via npm:
      command = "worker-mcp";
      args = [];

      # Alternatively, if running ad-hoc via npx:
      # command = "npx";
      # args = [ "-y" "@noosxe/worker-mcp" ];

      # Alternatively, if running ad-hoc via Nix:
      # command = "nix";
      # args = [ "run" "github:noosxe/worker-mcp?ref=main" ];
    };
  };
};

Step 2: Verify and Manage via TUI (/mcp command)

Once you have added the server configuration to mcp_config.json, you can manage it interactively inside the CLI:

1. Launch the Antigravity TUI:

   agy

2. Type the slash command /mcp in the prompt input and press Enter.

3. An interactive management overlay will open, showing worker-mcp in the list. You can inspect its status, trigger manual reloads, or verify that the tools/resources are successfully discovered by the coordinator agent.

Operational Configuration

Environment Variables

• WORKER_MCP_PI_PATH: Absolute path to the pi coding-agent binary (defaults to searching PATH for pi).

Pre-requisites

Make sure you have the global pi coding-agent CLI installed in your local system:

npm install -g @earendil-works/pi-coding-agent

Configure your models in pi (e.g. using pi --mode rpc to set default models, or registering Ollama model definitions).

MCP Reference

Exposed Tools

• spawn_pi_session: Spawns a new supervisor-gated worker agent in the specified workspace directory.

• send_pi_command: Dispatches prompts to the worker session. Supports background MCP task execution (resolving asynchronously) or blocking mode with an optional timeout.

• cancel_pi_command: Aborts the currently running command in a session and cancels its background task.

• list_pi_sessions: Returns a list of active sessions, directory targets, and current states.

• get_pending_actions: Fetches the details of an intercepted command awaiting consent.

• approve_action: Approves execution of a gated tool call.

• reject_action: Blocks a gated tool call and forwards feedback to correct the agent's course.

• set_risk_policy: Updates the risk-based auto-approval policy for a session at runtime.

• get_auto_approved_log: Retrieves the audit log of actions that were auto-approved by the risk policy.

Exposed Resources

• worker-mcp://sessions/{sessionId}/history: Returns the conversation log and internal message stream.

• worker-mcp://sessions/{sessionId}/logs: Returns the stdout/stderr trace logs of the subprocess.

Local Development

If you are contributing to this codebase, you must enter the Nix development shell:

nix develop

This enters an environment pre-packaged with:

• Node.js 24

• pnpm

• TypeScript

• BiomeJS

Dev Tasks

• Code Quality (Check, Lint, Format): biome check --write src/

• Compile TypeScript: pnpm run build

• Run local server: pnpm run dev

• Build Nix Derivation: nix build