Cluster Execution

Cluster Execution MCP Server enables distributed task routing and parallel command execution across a diverse AGI agentic cluster. It automatically selects optimal nodes based on load, capabilities, and requirements, and it enforces security-conscious execution with environment-based configuration and validation. This guide walks you through usage patterns, installation, configuration, and common operational considerations so you can reliably run commands across the cluster.

How to use

You interact with the Cluster Execution MCP Server through your MCP client to submit commands that should run on the most suitable node in the cluster. Use automatic routing for heavy or parallel workloads to maximize throughput, or explicitly offload certain commands to a specific node when you know the target is best for the task.

How to install

Prerequisites: ensure you have Python available on your system and a working environment for Python development.

Acquire the MCP server locally and install it in editable mode to enable development and local testing.

cd /mnt/agentic-system/mcp-servers/cluster-execution-mcp
pip install -e .

# For development:
pip install -e ".[dev]"

Configuration and runtime details

Configure the client to reference the MCP server as the execution backend. You add an MCP server entry under your Claude Code configuration to point to the runtime that hosts the cluster execution mcp server.

{
  "mcpServers": {
    "cluster-execution": {
      "command": "/mnt/agentic-system/.venv/bin/python3",
      "args": ["-m", "cluster_execution_mcp.server"]
    }
  }
}

Security and runtime configuration notes

All configuration is externalized via environment variables to avoid hardcoding credentials. SSH connectivity includes retry logic and timeouts. Commands are executed with strict validation to prevent injection and dangerous patterns.

Key runtime environment variables include SSH settings, timeouts, resource thresholds, and timeouts for command execution and status checks. See the table below for defaults and descriptions.

Troubleshooting and tips

If you encounter issues, verify configuration and connectivity first. Test SSH reachability to each node and confirm that the cluster routing remains healthy before running heavy operations.

Tools and commands overview

You have access to tools for executing, routing, and monitoring cluster tasks. The main tools are designed to submit commands, query cluster status, force routing to a specific node, and run commands in parallel across the cluster.

Available tools

cluster_bash

Execute bash commands with automatic cluster routing across the selected node set.

cluster_status

Retrieve the current state of the cluster, including load distribution and node health.

offload_to

Explicitly route a command to a specific node by node identifier.

parallel_execute

Run multiple commands in parallel across different cluster nodes and gather their results.