MCP Agent Forge

Dispatch AI coding agents as MCP tools. Fan out work to Claude Code, GitHub Copilot, and OpenCode from any MCP client -- Claude Desktop, your own orchestrator, or anything that speaks MCP.

Includes Bounded Plan safety -- constrain what agents can touch before they execute.

You (MCP Client)
    |
    |-- forge_plan("add error handling", no_touch=["auth.py", ".env"])
    |       -> preview: "Agent will touch 3 files, protect 2"
    |
    |-- forge_dispatch_plan("claude_code", "add error handling", ...)
    |       -> job_id: "forge-a1b2c3d4" (bounded execution)
    |
    |-- forge_status("forge-a1b2c3d4")
            -> status: "complete", bounded: true

Why?

You're already talking to Claude Desktop (or another MCP host). You want to delegate coding tasks to specialized agents without leaving your conversation. Agent Forge gives your orchestrator hands -- and Bounded Plans make sure those hands don't break things.

Claude Code -- Agentic, multi-file, reads CLAUDE.md. Best for complex tasks. ~$0.01-0.40/task.
GitHub Copilot CLI -- Free with GitHub Pro. Great for structured analysis and read-only work.
OpenCode -- Gemini Flash via OpenRouter. ~$0.003/task. Fast and cheap.

Install

# Clone
git clone https://github.com/Cloud-Eye-Prime/mcp-agent-forge.git
cd mcp-agent-forge

# Install dependency
pip install fastmcp

# Verify agents are available
claude --version        # Claude Code
github-copilot-cli      # Copilot (optional)
opencode --version      # OpenCode (optional)

You need at least one agent installed. Claude Code is the primary.

Install Claude Code

npm install -g @anthropic-ai/claude-code

Install OpenCode (optional)

npm install -g opencode

Configure with Claude Desktop

Add to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "agent-forge": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-agent-forge/server.py"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

Restart Claude Desktop. You now have seven tools available.

Tools

Core Dispatch

Tool	Description
`forge_dispatch`	Fire-and-forget dispatch. Returns job_id instantly.
`forge_run`	Synchronous dispatch -- waits for result. Use for quick tasks.
`forge_status`	Poll a running job for status and output.
`forge_list`	List all jobs with their current status.

Bounded Plan (Safety)

Tool	Description
`forge_plan`	Preview a constrained execution plan before dispatching.
`forge_dispatch_plan`	Dispatch with boundaries -- file limits, no-touch patterns, verification.

Bounded Plans

The most dangerous thing about AI coding agents is giving them unbounded access. "Refactor the auth module" sounds simple -- until the agent rewrites your database schema, deletes your tests, and installs three new dependencies.

Bounded Plans solve this. Before the agent executes, you define:

allowed_paths -- which files the agent may touch
no_touch -- which files are protected (auth, config, .env)
max_files -- hard cap on how many files can change
verification -- checks to run after execution
ground_rules -- additional constraints in plain language

The agent receives a rewritten prompt that includes all constraints. It doesn't see "refactor the auth module" -- it sees "refactor the auth module, but ONLY touch these 3 files, NEVER touch auth.py or .env, and verify with py_compile when done."

Example: Safe Refactoring

# Step 1: Preview the plan
forge_plan(
    task="Add error handling to all API route handlers",
    cwd="/home/me/myapp",
    max_files=4,
    allowed_paths=["src/routes/*.py", "src/middleware.py"],
    no_touch=["src/auth.py", "src/database.py", ".env", "migrations/"],
    verification=[
        "python -m py_compile src/routes/users.py",
        "python -m py_compile src/routes/orders.py",
        "python -m pytest tests/ -x --tb=short"
    ]
)

# Step 2: Review the constrained prompt, then execute
forge_dispatch_plan(
    agent="claude_code",
    task="Add error handling to all API route handlers",
    cwd="/home/me/myapp",
    max_files=4,
    allowed_paths=["src/routes/*.py", "src/middleware.py"],
    no_touch=["src/auth.py", "src/database.py", ".env", "migrations/"],
    verification=[
        "python -m py_compile src/routes/users.py",
        "python -m py_compile src/routes/orders.py",
        "python -m pytest tests/ -x --tb=short"
    ]
)

Default Ground Rules

Every bounded plan automatically includes these constraints:

Do not modify any file not listed in allowed_paths
Do not delete files unless explicitly asked
Do not install new dependencies without mentioning it
Verify your changes compile/parse before finishing
If uncertain, explain what you would do instead of doing it

You can add more with the ground_rules parameter.

Usage Patterns

Pattern 1: Simple dispatch (unbounded)

For low-risk tasks where you trust the agent:

forge_dispatch("claude_code", "fix the typo in README.md", "/myapp")

Pattern 2: Bounded dispatch (safe)

For anything touching production code:

forge_dispatch_plan(
    agent="claude_code",
    task="optimize the database query in user_service.py",
    cwd="/myapp",
    max_files=1,
    allowed_paths=["src/services/user_service.py"],
    no_touch=["src/models/", "src/auth/", "alembic/"],
    verification=["python -m py_compile src/services/user_service.py"]
)

Pattern 3: Fan-out

Dispatch multiple agents on different tasks simultaneously:

forge_dispatch("claude_code", "refactor auth to use JWT", "/myapp")
forge_dispatch("opencode", "add type hints to utils.py", "/myapp")
forge_dispatch("copilot", "explain the database schema", "/myapp")

Poll all three. Collect results. Synthesize.

Pattern 4: Research then execute

# Step 1: cheap read with OpenCode
forge_run("opencode", "list all files that import auth_middleware", "/myapp")

# Step 2: bounded execution with Claude Code
forge_dispatch_plan(
    agent="claude_code",
    task="update auth_middleware imports to use new pattern from utils.py",
    cwd="/myapp",
    max_files=3,
    no_touch=["src/auth_middleware.py"],
    verification=["python -m py_compile src/routes/api.py"]
)

Pattern 5: Agent comparison

Send the same task to multiple agents and compare:

forge_dispatch("claude_code", "review this PR for security issues", "/myapp")
forge_dispatch("opencode", "review this PR for security issues", "/myapp")

Different models catch different things.

Agent Comparison

Agent	Model	Cost	Speed	Writes Files?	Best For
`claude_code`	Sonnet 4.6	$0.01-0.40	15-135s	Yes	Complex multi-file changes, agentic tasks
`copilot`	Sonnet 4.6 (via GitHub)	Free	30-60s	Limited	Analysis, structured reports, Q&A
`opencode`	Gemini Flash	~$0.003	14-25s	Yes	Fast reads, simple rewrites, type hints

Tips

Always pass absolute paths for cwd. Relative paths resolve from the server's working directory.
Use Bounded Plans for production code. Unbounded dispatch is fine for exploration and analysis. Use forge_dispatch_plan when changes matter.
Poll every 10-30 seconds for long tasks. Claude Code can take up to 5 minutes.
Claude Code reads CLAUDE.md -- if your project has one, the agent follows those conventions.
Copilot may not write files in headless mode. Use it for analysis, not execution.
The no_touch list is your safety net. Always protect auth, config, env files, and database migrations.

Cloud-Eye LXR-5 (Optional Cloud Brain)

Agent Forge gives your orchestrator hands. Cloud-Eye LXR-5 gives it a brain -- persistent memory, workspace isolation, 20-tool agent loops, thermodynamic routing, and institutional knowledge that accumulates across sessions.

If you outgrow stateless agent dispatch and want agents that remember, learn, and coordinate -- check out Cloud-Eye.

License

MIT. Use it, fork it, build on it.

Built by Cloud-Eye Prime -- the Dragon's open hand.

mcp-agent-forge

Links

README