Skip to main content
Glama
iron-manus-mcp
by dnnyngyen

Build Status Tests TypeScript Node.js License: MIT Docker Hub GitHub Container Registry Source Code

Iron Manus MCP

Model Context Protocol server for AI workflow orchestration inspired by Manus AI's orchestration patterns and Andrej Karpathy's "Iron Man" analogy.

Extended context management through agent delegation and Todos as a custom agent dispatch tool

Demo

πŸŽ₯ Video Tutorial

Iron Manus MCP Deep Dive

Watch the detailed walkthrough

Related MCP server: agent-runtime-mcp

Historical Notes: Architectural Patterns

Note: This project is now archived. The following notes document architectural decisions that later appeared in mainstream AI tooling.

Several patterns implemented in Iron Manus MCP (June 2024) were later adopted by Claude Code and similar tools. These emerged from independent experimentation rather than foresight, solving problems that turned out to be common across the ecosystem.

Patterns That Became Standard

1. Todos as Subagent Dispatch Queue

interface TodoItem {
  type?: 'TaskAgent' | 'SubAgent' | 'DirectExecution';
  meta_prompt?: MetaPrompt;  // Declarative agent configuration
}

This MCP was the first to use todos as a subagent dispatch queue. Claude Code had TodoWrite/TodoRead at that point, but nobody (including Anthropic) was thinking of todos as an agent coordination primitive. The Task tool existed but was just non-specialized agents. Our implementation connected the two: todos become task dispatches. Boris Cherny announced "We're turning Todos into Tasks" on January 22, 2026, seven months after we shipped the same idea.

2. Phase-Gated Tool Access

const PHASE_ALLOWED_TOOLS = {
  PLAN: ['TodoWrite'],
  EXECUTE: ['TodoRead', 'TodoWrite', 'Task', 'Bash', 'Read', 'Write', 'Edit'],
  VERIFY: ['TodoRead', 'Read'],  // Read-only during verification
};

Restricting tool availability by phase prevented misuse (e.g., writing files during verification). This pattern appears in Claude Code Agent Teams (February 2026) via phase-based permissions.

3. Structured Planning Phase

The explicit INIT β†’ QUERY β†’ ENHANCE β†’ KNOWLEDGE β†’ PLAN β†’ EXECUTE β†’ VERIFY β†’ DONE workflow enforced planning before execution. Claude Code's Plan Mode (August 2025) provides similar structure.

4. Context Isolation via File-Based Communication

./iron-manus-sessions/{session_id}/
β”œβ”€β”€ synthesized_knowledge.md
β”œβ”€β”€ primary_research.md
└── agent_output.md

Task() agents have isolated contexts and cannot share state directly. This project used session workspaces for inter-agent coordination. Claude Code Agent Teams implements similar patterns via ~/.claude/teams/ and ~/.claude/tasks/.

5. Role-Based Prompt Switching

Nine specialized roles (planner, coder, critic, researcher, analyzer, synthesizer, ui_architect, ui_implementer, ui_refiner) with distinct thinking methodologies. Claude Code custom subagents (July 2025) provide similar specialization.

6. Meta-Prompt DSL for Agent Spawning

(ROLE: coder) (CONTEXT: auth_system) (PROMPT: Implement JWT auth) (OUTPUT: auth_module.ts)

Declarative syntax for agent configuration embedded in todo content. Similar patterns appear in Claude Code's subagent configuration.

Timeline Context

Iron Manus MCP (June 2024) introduced todos as subagent dispatch, phase-gated tools, structured planning phases, context isolation, and role-based agents. Claude Code adopted these patterns between July 2025 and February 2026. These patterns emerged from practical necessity. Multi-agent orchestration requires task decomposition, context isolation, and workflow structure, all of which eventually appeared in production tooling.

What It Does

8-phase workflow orchestration: INIT β†’ QUERY β†’ ENHANCE β†’ KNOWLEDGE β†’ PLAN β†’ EXECUTE β†’ VERIFY β†’ DONE

Tools:

  • JARVIS - 8-phase workflow controller

  • APITaskAgent - API discovery and fetching with SSRF protection

  • PythonComputationalTool - Python execution for data analysis

  • IronManusStateGraph - Session state management

  • SlideGenerator - HTML slide generation

  • HealthCheck - Runtime diagnostics

Quick Start

From Source

git clone https://github.com/dnnyngyen/iron-manus-mcp
cd iron-manus-mcp
npm install
npm run build
npm start

Docker

docker build -t iron-manus-mcp .
docker run -d --name iron-manus-mcp iron-manus-mcp

Or with docker-compose:

docker-compose up -d

MCP Integration

Add to Claude Code:

claude mcp add iron-manus-mcp node dist/index.js

Or add to your MCP config:

{
  "mcpServers": {
    "iron-manus-mcp": {
      "command": "node",
      "args": ["path/to/iron-manus-mcp/dist/index.js"]
    }
  }
}

Configuration

ALLOWED_HOSTS=api.github.com,httpbin.org    # SSRF whitelist
ENABLE_SSRF_PROTECTION=true                  # Enable security
KNOWLEDGE_MAX_CONCURRENCY=2                  # API concurrency limit
KNOWLEDGE_TIMEOUT_MS=4000                    # Request timeout (ms)

Development

npm run build     # Compile TypeScript
npm run lint      # Check code style
npm run format    # Format code
npm start         # Run server
npm run dev       # Build + watch mode

Security

  • SSRF protection blocks private IPs (192.168.x.x, 127.x.x.x, etc.)

  • URL validation (HTTP/HTTPS only)

  • Host allowlist enforcement

  • Request timeout and size limits

License

MIT

Available Tools

6 tools
APITaskAgentC

Specialized API research agent that orchestrates discovery, validation, and data fetching workflows. When you need structured data from external sources, ask: What type of evidence does my current research objective require? How can I ensure data reliability while maintaining research efficiency? This agent guides you through strategic API selection based on your cognitive role, automatically validates sources, and provides comprehensive data synthesis with actionable insights.

Inputs: objective (required), user_role (required), headers, timeout_ms, +4 more.

HealthCheckC

System intelligence assessment - evaluates not just operational health, but the cognitive readiness of your tools and infrastructure. When questioning system performance, ask: Are your tools thinking clearly? What might cognitive degradation look like in an AI system? This tool prompts you to consider: How do I assess whether my system is ready for intelligent decision-making, not just basic functionality? What early warning signs might indicate declining analytical capability?

Inputs: detailed.

IronManusStateGraphC

Project-scoped FSM state management using knowledge graphs. Manage sessions, phases, tasks, and transitions with isolated state per project.

Inputs: action (required), session_id (required), role, names, +11 more.

JARVISB

JARVIS Finite State Machine Controller - Implements the 8-phase agent loop (INIT β†’ QUERY β†’ ENHANCE β†’ KNOWLEDGE β†’ PLAN β†’ EXECUTE β†’ VERIFY β†’ DONE) with Meta Thread-of-Thought orchestration. Features: Role-based cognitive enhancement through systematic thinking methodologies, meta-prompt generation for Task() agent spawning, fractal task decomposition, performance tracking, and single-tool-per-iteration enforcement. Enables Claude to autonomously manage complex projects through context segmentation.

Inputs: payload, session_id, phase_completed, initial_objective.

PythonComputationalToolC

Unified Python execution and data science tool with automatic library management and comprehensive workflow support

Inputs: operation (required), input_data, parameters, custom_code.

SlideGeneratorB

Generates HTML slides from templates and content data. Takes template ID and structured content, returns rendered slide HTML.

Inputs: templateId (required), contentData (required), sessionId, designOptions.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 6 tools

    Disambiguation3/5

    JARVIS and IronManusStateGraph both deal with state management, creating potential confusion. Other tools like APITaskAgent, PythonComputationalTool, HealthCheck, and SlideGenerator are more distinct, but HealthCheck's abstract description adds ambiguity.

    Naming Consistency3/5

    Most tools follow PascalCase (APITaskAgent, PythonComputationalTool, etc.), but JARVIS is an all-caps acronym outlier. There is no verb_noun pattern; names are descriptive nouns or proper names.

    Tool Count4/5

    Six tools is a reasonable count for a multi-purpose server covering orchestration, API research, computation, state management, health check, and slide generationβ€”neither too few nor too many.

    Completeness2/5

    The tool set mixes concrete (SlideGenerator) and abstract (HealthCheck) tools without clear domain coverage. Gaps exist in typical project management functions like file handling or user interaction, and some tools have vague purposes.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers