Skip to main content
Glama
DevImperatore

mcp-ai-workforce

by DevImperatore
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MCP AI Workforce

Autonomous Model Context Protocol Server for Cost-Effective AI Coding Delegation

CI Python 3.10+ MCP Protocol OpenRouter License: MIT Tests: 32 passed

Empower primary AI orchestrators to delegate token-heavy coding tasks to economical models via OpenRouter, reducing token expenditure by up to 95%.

Key Features | Architecture | Quickstart | Client Integrations | Tools Reference | Security

The Problem and The Solution

The Problem

Frontier AI models (Claude 3.7 Sonnet, Claude Opus, Gemini 2.5 Pro, GPT-4o) cost anywhere from $3.00 to $50.00+ per million tokens. Using these elite models for tasks such as writing repetitive test suites, formatting JSON payloads, generating boilerplate, or fixing syntactic linter errors consumes valuable context windows and leads to high operational costs.

The Solution

mcp-ai-workforce is an open-source Model Context Protocol (MCP) server that establishes a two-tier delegation architecture:

  1. The Orchestrator: The primary AI client (Claude Desktop, Google Antigravity, or Cursor) manages high-level architecture, breaks down engineering goals, and audits changes.

  2. The Autonomous Worker: The orchestrator invokes workforce_delegate. mcp-ai-workforce executes a sandboxed ReAct loop powered by cost-effective coding models (such as Qwen 2.5 Coder 32B or DeepSeek V4 via OpenRouter at approximately $0.20 to $0.50 per million tokens).

  3. The Audit: When execution completes, the orchestrator inspects the unified Git diff (workforce_audit_diff), conducts automated or manual code reviews, and approves the changes.

Related MCP server: Local Worker MCP

Key Features

  • Cost Optimization: Offload routine code generation to economical models while reserving frontier reasoning models for architectural oversight.

  • Zero-Trust Security Sandbox:

    • Path Confinement: Validates canonical paths against the configured root directory to prevent directory traversal (../../) and unauthorized filesystem access.

    • Credential Shielding (CWE-522): Prohibits the worker from accessing or modifying .env* files, server source code, and cryptographic private keys.

    • RCE-Immune Git Auditing (CWE-78): Enforces sanitized flags (--no-ext-diff) to prevent arbitrary command execution via .git/config.

  • Autonomous ReAct Worker Loop: Provides controlled filesystem operations (read_file, write_file, list_dir) with built-in infinite-loop detection and configurable step and timeout budgets.

  • Universal Client Support: Compatible with Claude Desktop, Cursor IDE, Google Antigravity, Windsurf, and any standard MCP client across macOS, Linux, and Windows.

  • Automated Test Coverage: Verified with 32 unit and integration tests executing across Python 3.10, 3.11, and 3.12 in continuous integration.

Architecture

sequenceDiagram
    autonumber
    actor User as Developer
    participant Orchestrator as Primary AI (Claude / Antigravity / Cursor)
    participant Server as mcp-ai-workforce (FastMCP)
    participant Provider as OpenRouter (Qwen / DeepSeek)
    participant Workspace as Local Repository / Workspace

    User->>Orchestrator: Implement unit tests for authentication module
    Orchestrator->>Server: workforce_delegate(task_prompt, model="qwen/qwen-2.5-coder-32b-instruct")
    
    activate Server
    Note over Server: Security Sandbox & Guardrails Active
    loop Autonomous ReAct Loop (max 15 steps)
        Server->>Provider: Send context and available tools
        Provider-->>Server: Tool call (read_file / write_file)
        Server->>Workspace: Execute safe filesystem operation
        Workspace-->>Server: Operation result
    end
    Server-->>Orchestrator: Return task summary report
    deactivate Server

    Orchestrator->>Server: workforce_audit_diff()
    Server-->>Orchestrator: Return sanitized git diff
    Note over Orchestrator: Code review and verification
    Orchestrator-->>User: Implementation complete and verified

Quickstart

Prerequisites

  • Python 3.10 or higher.

  • Git installed and available on system PATH.

  • An OpenRouter API key.

1. Clone and Set Up Environment

# Clone the repository
git clone https://github.com/DevImperatore/mcp-ai-workforce.git
cd mcp-ai-workforce

# Create and activate a virtual environment
# On macOS / Linux:
python3 -m venv .venv
source .venv/bin/activate

# On Windows:
python -m venv .venv
.\.venv\Scripts\activate

# Install in editable mode (registers the 'mcp-ai-workforce' CLI command)
pip install -e .

# Or install dependencies from requirements.txt
pip install -r requirements.txt

2. Configure Environment Variables

Copy the template .env.example to .env:

cp .env.example .env

Edit .env:

# OpenRouter API Key
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Default model for worker tasks
DEFAULT_MODEL=qwen/qwen-2.5-coder-32b-instruct

# Canonical workspace path (defaults to current working directory if omitted)
WORKSPACE_ROOT=/path/to/your/project

# Execution limits
MAX_STEPS=15
TIMEOUT_SECONDS=300

Client Integrations

The server can be executed directly via its entry point command (mcp-ai-workforce), via uvx / pipx, or by referencing the virtual environment Python interpreter.

Claude Desktop

Add the following entry to claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ai-workforce": {
      "command": "mcp-ai-workforce",
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Or using an explicit virtual environment:

{
  "mcpServers": {
    "ai-workforce": {
      "command": "/path/to/mcp-ai-workforce/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-ai-workforce",
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

Note: On Windows, use .venv\\Scripts\\python.exe with properly escaped backslashes.

Cursor IDE

Configure through .cursor/mcp.json or through Cursor Settings:

  1. Open Cursor Settings (Ctrl + Shift + J or Cmd + Shift + J).

  2. Navigate to Features > MCP.

  3. Select Add New MCP Server:

    • Name: ai-workforce

    • Type: command

    • Command: mcp-ai-workforce (or /path/to/mcp-ai-workforce/.venv/bin/python -m src.server)

Or add directly to .cursor/mcp.json:

{
  "mcpServers": {
    "ai-workforce": {
      "command": "mcp-ai-workforce",
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Google Antigravity

Add the server configuration to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "ai-workforce": {
      "command": "mcp-ai-workforce",
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Or using virtual environment paths:

{
  "mcpServers": {
    "ai-workforce": {
      "command": "/path/to/mcp-ai-workforce/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-ai-workforce",
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

Windsurf (Codeium)

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ai-workforce": {
      "command": "mcp-ai-workforce",
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Or using explicit Python path:

{
  "mcpServers": {
    "ai-workforce": {
      "command": "/path/to/mcp-ai-workforce/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-ai-workforce",
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

Tools Reference

Tool Name

Parameters

Description

workforce_delegate

task_prompt (str, required)target_files (list[str], optional)model (str, optional)timeout_seconds (int, default: 300)

Dispatches an autonomous ReAct worker agent to inspect, modify, and create workspace files under strict security guardrails.

workforce_models_status

None

Reports API key connectivity, canonical workspace root path, execution limits, and recommended models.

workforce_audit_diff

staged (bool, default: False)

Executes a non-blocking git diff across the repository to inspect all changes generated by the worker.

Security and Sandboxing

The autonomous worker executes within a zero-trust sandbox:

  1. Path Jail (validate_safe_path):

    • Canonicalizes and normalizes all target paths against WORKSPACE_ROOT.

    • Rejects directory traversal attempts (../, ..\\, symlink redirection).

    • Blocks access to system directories (/etc, C:\Windows, etc.).

  2. Credential and Secrets Protection:

    • Strictly blocks access to .env*, .git/, .agents/mcp-ai-workforce/, and private keys (.pem, .key, id_rsa).

  3. Execution Guardrails:

    • Infinite Loop Detection: Halts execution if identical tool signatures are called 3 consecutive times.

    • Resource Limits: Enforces step bounds (MAX_STEPS) and hard timeouts (TIMEOUT_SECONDS) to prevent runaway API consumption.

Example Prompts

Once configured, invoke tasks in natural language via your primary AI interface:

"Please delegate to the workforce the task of writing comprehensive pytest 
unit tests for 'src/services/auth.py'. Once the worker finishes, call 
workforce_audit_diff to verify the changes."
"Use workforce_delegate with model 'deepseek/deepseek-chat' to refactor 
all utility functions in 'utils/formatter.py' by adding full type annotations 
and Google-style docstrings."

Running Tests

The test suite covers OpenRouter API mocks, path traversal defenses, loop traps, and FastMCP tool endpoints.

pytest -v
============================= test session starts =============================
platform win32 / linux -- Python 3.10+ -- pytest-9.1.1
collected 32 items

tests/test_agent_loop.py::test_execute_tool_read_and_write PASSED        [  3%]
tests/test_agent_loop.py::test_execute_tool_guardrail_protection PASSED  [  6%]
tests/test_agent_loop.py::test_infinite_loop_detector PASSED             [  9%]
tests/test_agent_loop.py::test_agent_max_steps_limit PASSED              [ 12%]
tests/test_agent_loop.py::test_agent_normal_completion PASSED            [ 15%]
tests/test_fs_tools.py::test_worker_write_and_read_file PASSED           [ 18%]
...
tests/test_server.py::test_workforce_delegate_success PASSED             [ 81%]
tests/test_worker_loop.py::test_worker_loop_successful_termination PASSED [100%]

============================= 32 passed in 2.80s ==============================

License

This project is licensed under the MIT License. See the LICENSE file for details.

Developed by DevImperatore

Available Tools

3 tools
workforce_audit_diffA

Execute a git diff inspection across the workspace to audit worker modifications.

Args: staged: If True, inspect staged changes (git diff --staged); otherwise inspect unstaged workspace modifications (git diff).

Returns: str: The unified git diff output or an informative message if no changes exist.

ParametersJSON Schema
NameRequiredDescriptionDefault
stagedNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It discloses the exact git commands used (`git diff --staged` vs `git diff`), the read-only 'inspection' nature of the operation, and the return behavior including the no-changes message. This is strong behavioral disclosure for a simple audit tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured with distinct Args and Returns sections. Every sentence adds necessary information, and the primary purpose is front-loaded in the first sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a low-complexity tool with a single optional boolean parameter and an output schema available. The description covers what the tool does, how the parameter behaves, and what it returns, including the no-changes case. Nothing essential is missing for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides only a boolean `staged` with a default, but the description fully explains both parameter states: True inspects staged changes, otherwise unstaged modifications. It even names the precise git command each state triggers, which is more than sufficient despite 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Execute a git diff inspection across the workspace to audit worker modifications.' It clearly identifies what the tool does and differentiates it from the sibling worker tools by focusing on diff auditing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: auditing worker modifications via git diff. It also explains the staged vs. unstaged distinction, giving an agent enough context to invoke it appropriately, though it does not explicitly mention when not to use it or compare it to siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

workforce_delegateA

Delegate a software engineering task to an autonomous ReAct worker agent.

The worker operates with filesystem tools under strict guardrails to inspect, read, modify, and create workspace files safely.

Args: task_prompt: Comprehensive description of the task or feature to implement. target_files: Optional list of relevant workspace-relative file paths. model: OpenRouter model to utilize (defaults to DEFAULT_MODEL). timeout_seconds: Execution timeout limit in seconds (default: 300).

Returns: str: Final completion summary or diagnostic output from the worker agent.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNo
task_promptYes
target_filesNo
timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It discloses that the worker uses filesystem tools to inspect, read, modify, and create files under 'strict guardrails,' and that it returns a completion summary or diagnostic. It does not detail side effects, failure modes, or cost/time implications, but the core mutation behavior is explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with a one-sentence purpose, a brief safety/behavior note, an Args list, and a Returns line. No filler; all sentences add information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, all parameters, behavior, and return type, and an output schema exists. The only gap is the absence of any comparison to sibling tools or explicit usage boundaries, so it is not quite as complete as it could be.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema has no property descriptions, the tool description's Args section explains every parameter: task_prompt content, target_files as optional workspace-relative paths, model as an OpenRouter model with a default, and timeout_seconds with its default. This fully compensates for the schema's 0% description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action ('Delegate a software engineering task') and a specific target ('autonomous ReAct worker agent'). It clearly distinguishes from siblings like workforce_audit_diff and workforce_models_status, which are about auditing diffs and checking model status, not delegating implementation work.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for delegating implementation tasks, but it gives no explicit when-to-use or when-not-to-use guidance and never references the sibling tools. There is no exclusion criteria or alternative selection advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

workforce_models_statusA

Inspect current configuration, supported models, and OpenRouter readiness.

Returns: Dict[str, Any]: Configuration status including API key presence, default model, configured workspace root, and suggested coding models.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. 'Inspect' signals a non-destructive read, and 'API key presence' (rather than the key value) discloses that secrets are not exposed. It doesn't state side effects or access requirements explicitly, but the read-only nature is reasonably clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in a single sentence, and the return summary is compact and informative. Every sentence earns its place with no filler or repetition of the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter status tool with an output schema, this description is nearly complete: it states what is inspected, what is returned, and the readiness angle. The only gap is when to run it relative to siblings, which is a usage-guidance concern rather than a completeness failure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description adds value by explaining what the return payload contains, which is more relevant than parameter semantics for this tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Inspect current configuration, supported models, and OpenRouter readiness') and enumerates what the status contains. It doesn't explicitly differentiate from siblings, but the sibling names (audit_diff, delegate) are so different that no ambiguity exists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or alternatives are named, but the phrase 'OpenRouter readiness' implies a workflow of checking status before delegating work. The usage context is inferable rather than stated, which is acceptable but not actively instructive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observedworkforce_audit_diff
    • First observedworkforce_delegate
    • First observedworkforce_models_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct function: workforce_delegate executes tasks, workforce_audit_diff reviews changes, and workforce_models_status checks configuration. There is no meaningful overlap or ambiguity between them.

Naming Consistency4/5

All tools share a consistent workforce_ prefix and snake_case style. The final word pattern varies slightly—verb-object, bare verb, and noun phrase—but the naming remains predictable and readable.

Tool Count5/5

Three tools is well within the ideal well-scoped range, and each tool supports a clear step in the delegate-audit-status workflow. None feel redundant or unnecessary.

Completeness4/5

The server covers a coherent end-to-end workflow: readiness check, task delegation, and post-work audit. It lacks live progress tracking or cancellation, but the timeout and final summary provide reasonable workarounds.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers