Aegis MCP Server¶

Overview¶

The Aegis MCP server provides custom orchestration, planning, and automation tools specifically designed for autonomous agent operations. It exposes 50+ tools across 24 modules, integrating deeply with Aegis core functionality.

Location: /home/agent/projects/aegis-core/mcp-servers/aegis_mcp/

Tool Prefix: mcp__aegis__

Tool Categories¶

1. Agent Orchestration¶

Tools for spawning, managing, and coordinating autonomous agents.

`spawn_agent`¶

mcp__aegis__spawn_agent(
    task: str,
    template: str = "auto",  # Or: researcher, executor, developer, etc.
    context: dict = {},
    token_budget: int = 50000,
    model: str = "sonnet"
)

Spawns a specialized agent to execute a task. Template auto-detection based on task description.

Templates Available: - researcher - Information gathering, web research - executor - Infrastructure, Docker, deployment - developer - Code writing, debugging - reviewer - Code review, quality checks - communicator - Discord, Telegram, email - monitor - Health checks, system monitoring - coordinator - Multi-agent orchestration - fallback - General-purpose agent

Example:

result = await spawn_agent(
    task="Research best practices for FastAPI testing",
    template="researcher",
    token_budget=30000
)

`list_agents`¶

mcp__aegis__list_agents()

Returns all active agents with status, token usage, and current tasks.

`get_agent_status`¶

mcp__aegis__get_agent_status(agent_id: str)

Detailed status for a specific agent.

`orchestration_dashboard`¶

mcp__aegis__orchestration_dashboard()

Comprehensive overview: - Fleet summary (agent counts by state) - Template performance metrics - Workflow summaries - Messaging statistics

2. HTN Planning¶

Hierarchical Task Network decomposition for complex goals.

`decompose_task`¶

mcp__aegis__decompose_task(
    goal: str,
    description: str = "",
    use_memory: bool = True,
    use_llm: bool = False
)

Breaks down a complex goal into a hierarchical task tree with dependencies.

Built-in Decomposition Methods: - deploy - Service deployment workflow - research - Information gathering pipeline - implement - Feature implementation - debug - Problem-solving steps - create - Content/artifact generation - integrate - System integration

Returns:

{
  "success": true,
  "tree_id": "tree-abc123",
  "goal": "Deploy nginx service",
  "tasks": [
    {
      "id": "task-1",
      "name": "Prepare Docker configuration",
      "task_type": "setup",
      "agent_role": "executor",
      "depends_on": [],
      "priority": 1
    },
    ...
  ],
  "visualization": "ASCII tree diagram"
}

Example:

tree = await decompose_task(
    goal="Deploy the new API service to production",
    description="Node.js API with PostgreSQL backend"
)

`execute_task_tree`¶

mcp__aegis__execute_task_tree(tree_id: str)

Executes a decomposed task tree with: - Dependency tracking - Parallel execution where possible - Progress monitoring - Episodic memory recording

`list_solutions`¶

mcp__aegis__list_solutions(pattern: str = None)

Lists cached planning solutions. Solutions are reused for similar goals.

Solution Cache Stats: - Total solutions: 3+ - Success rate: 100% - Auto-applied when matching goals detected

3. Workflows¶

Graph-based workflow execution with checkpointing and human-in-the-loop gates.

`run_workflow`¶

mcp__aegis__run_workflow(
    workflow_name: str,
    initial_context: dict,
    checkpoint_id: str = None
)

Execute or resume a workflow. Supports: - LangGraph-inspired DSL - PostgreSQL-backed checkpointing - InterruptNode for human approval - Conditional branching - Parallel execution

Example Workflows: - deployment-approval - Deployment with approval gates - research-synthesis - Iterative research refinement - tdd-loop - Test-driven development cycle

`resume_workflow`¶

mcp__aegis__resume_workflow(
    workflow_id: str,
    response: str
)

Resume an interrupted workflow (e.g., after human approval).

`list_workflows`¶

mcp__aegis__list_workflows(status: str = None)

List stored workflows with status filtering.

4. Error Tracking¶

Three-strike protocol support with knowledge graph integration.

`error_record`¶

mcp__aegis__error_record(
    error_type: str,
    context: str,
    error_message: str = None,
    resolution: str = None,
    severity: str = "error",  # info, warning, error, critical
    strike_count: int = 1
)

Records errors to the knowledge graph for pattern detection.

Categories Auto-Detected: - Import errors - Syntax errors - Runtime errors - Network errors - Database errors - Container errors - Authentication errors - Resource errors - Configuration errors

Example:

await error_record(
    error_type="ModuleNotFoundError",
    context="Dashboard container startup",
    error_message="No module named 'aegis.workflows.storage'",
    resolution="Fixed import to use direct db queries",
    strike_count=2
)

`error_search`¶

mcp__aegis__error_search(query: str, limit: int = 5)

Find similar past errors and their resolutions.

`error_recent`¶

mcp__aegis__error_recent(
    hours: int = 24,
    category: str = None,
    severity: str = None,
    limit: int = 20
)

Get recent errors for pattern detection.

`error_resolution`¶

mcp__aegis__error_resolution(
    error_type: str,
    resolution: str,
    lessons_learned: str = None
)

Record how an error was resolved for future learning.

5. Memory & Knowledge¶

`journal_entry`¶

mcp__aegis__journal_entry(
    content: str,
    date: str = "today",
    section: str = "general"
)

Append to daily journal (~/memory/journal/YYYY-MM-DD.md).

`read_journal`¶

mcp__aegis__read_journal(date: str = "today")

Read a journal entry.

6. Beads Task Management¶

Git-backed issue tracker for persistent tasks.

`beads_list_ready`¶

mcp__aegis__beads_list_ready()

Get unblocked tasks ready for work.

`beads_create`¶

mcp__aegis__beads_create(
    title: str,
    description: str = "",
    priority: int = 2,
    task_type: str = "task"
)

Create a new task.

`beads_update`¶

mcp__aegis__beads_update(
    task_id: str,
    status: str = None,
    notes: str = None
)

Update task status (backlog, ready, in_progress, blocked, done).

`beads_close`¶

mcp__aegis__beads_close(task_id: str, resolution: str)

Close a task with resolution notes.

7. Critic Agent¶

Output validation with multi-dimensional scoring.

`critique_output`¶

mcp__aegis__critique_output(
    output: str,
    context: str,
    task_type: str = "general",
    use_llm: bool = False
)

Validate output quality across 6 dimensions: - Accuracy (30%) - Factual correctness - Completeness (25%) - All requirements met - Safety (25%) - No harmful patterns - Clarity (10%) - Clear communication - Alignment (5%) - Matches intent - Actionability (5%) - Provides next steps

Task Profiles: - code - Emphasis on accuracy, safety, completeness - research - Emphasis on accuracy, completeness, clarity - communication - Emphasis on clarity, alignment, actionability - deployment - Emphasis on accuracy, safety, completeness

Returns:

{
  "approved": true,
  "overall_score": 0.85,
  "dimensions": {
    "accuracy": 0.9,
    "completeness": 0.8,
    "safety": 1.0,
    "clarity": 0.7,
    "alignment": 0.9,
    "actionability": 0.8
  },
  "feedback": "Good output. Consider adding more examples.",
  "recommendations": ["Add code examples", "Include error handling"]
}

`validate_and_improve`¶

mcp__aegis__validate_and_improve(
    output: str,
    context: str,
    max_iterations: int = 2
)

Iteratively improve output until approval threshold met.

8. System Status¶

`system_health`¶

mcp__aegis__system_health()

Comprehensive health check: - Docker containers - PostgreSQL connection - LLM API status - Resource usage (CPU, memory, disk) - Service health endpoints

`get_config`¶

mcp__aegis__get_config(key: str = None)

Get Aegis configuration values.

9. Research¶

`notebooklm_research`¶

mcp__aegis__notebooklm_research(
    question: str,
    notebook_id: str = None
)

Query NotebookLM for source-backed research answers.

`reddit_research`¶

mcp__aegis__reddit_research(
    topic: str,
    research_type: str = "pain_points"  # or: demand, competitors
)

Generate Reddit search queries and parse results for competitive intelligence.

`create_share_link`¶

mcp__aegis__create_share_link(
    file_path: str,
    expires_hours: int = 24
)

Create time-limited shareable links for files in ~/memory or ~/projects/aegis-core/data.

Returns:

{
  "url": "https://aegisagent.ai/share/TOKEN",
  "expires_at": "2026-01-26T12:00:00Z",
  "token": "abc123...",
  "file_path": "/home/agent/memory/semantic/document.md"
}

Viewers: - Markdown: Syntax-highlighted viewer - Download: Add ?download=true - Raw: Add ?raw=true

11. Compliance & Autonomy¶

`check_compliance`¶

mcp__aegis__check_compliance()

Check compliance status (autonomous mode, financial controls, security boundaries).

`autonomous_status`¶

mcp__aegis__autonomous_status()

Get autonomous mode state.

`autonomous_enable`/`autonomous_disable`¶

mcp__aegis__autonomous_enable()
mcp__aegis__autonomous_disable()

Control autonomous operation mode.

12. Messaging¶

`send_agent_message`¶

mcp__aegis__send_agent_message(
    from_agent: str,
    to_agent: str,
    message: str,
    priority: int = 1
)

Inter-agent communication.

`broadcast_message`¶

mcp__aegis__broadcast_message(
    from_agent: str,
    message: str,
    agent_filter: dict = None
)

Broadcast to multiple agents.

Configuration¶

Startup¶

The Aegis MCP server is started via:

python -m aegis_mcp.server

Configured in ~/.claude.json:

{
  "mcpServers": {
    "aegis": {
      "command": "python",
      "args": ["-m", "aegis_mcp.server"],
      "env": {
        "AEGIS_HOME": "/home/agent",
        "PYTHONPATH": "/home/agent/projects/aegis-core"
      }
    }
  }
}

Dependencies¶

Python 3.11+
mcp[server] package
Aegis core modules
PostgreSQL (for workflows, checkpointing)
FalkorDB (for knowledge graph)

Integration Patterns¶

1. Agent-First Workflow¶

# Decompose complex goal
tree = await decompose_task(
    goal="Implement user authentication",
    description="OAuth with Google, GitHub, and email"
)

# Execute with specialized agents
result = await execute_task_tree(tree.tree_id)

# Record outcomes
await journal_entry(
    content=f"Completed auth implementation: {result.summary}",
    section="implementations"
)

2. Error Recovery Pattern¶

try:
    # Attempt operation
    result = deploy_service()
except Exception as e:
    # Record error (Strike 1)
    await error_record(
        error_type=type(e).__name__,
        context="Service deployment",
        error_message=str(e),
        strike_count=1
    )

    # Search for similar errors
    similar = await error_search(str(e))

    # Apply known resolution if found
    if similar.related_resolutions:
        apply_resolution(similar.related_resolutions[0])

3. Quality Gate Pattern¶

# Generate output
output = await generate_code(requirements)

# Validate before committing
critique = await critique_output(
    output=output,
    context=requirements,
    task_type="code"
)

if not critique.approved:
    # Improve iteratively
    improved = await validate_and_improve(
        output=output,
        context=requirements,
        max_iterations=2
    )
    output = improved.output

Performance Considerations¶

Token Usage¶

Aegis MCP tools are designed for efficiency: - Most tools: <500 tokens per call - Dashboard tools: ~1,000 tokens - Planning tools: ~2,000 tokens (tree visualization)

Caching¶

Solution cache: Reuses decompositions for similar goals
Template metrics: Cached performance data
Agent registry: In-memory state

Async Operations¶

All tools use async/await for non-blocking I/O:

# Parallel agent spawning
tasks = [
    spawn_agent("Research X", "researcher"),
    spawn_agent("Research Y", "researcher"),
    spawn_agent("Research Z", "researcher"),
]
results = await asyncio.gather(*tasks)

Troubleshooting¶

Common Issues¶

"Graphiti client not available"
Check FalkorDB is running: docker ps | grep falkordb
Initialize client: await GraphitiClient().initialize()
"Workflow not found"
Workflows require PostgreSQL
Check connection: await system_health()
"Agent spawn failed"
Check token budget not exceeded
Verify template name is valid

Debug Mode¶

Enable detailed logging:

export AEGIS_LOG_LEVEL=DEBUG
python -m aegis_mcp.server

Next Steps¶

MCP Overview - Protocol basics
Docker MCP - Container management
Graphiti MCP - Knowledge graph operations
Agent Templates
HTN Planning

Complete Tool List¶

Module	Tools	Description
orchestration	1	orchestration_dashboard
agents	4	spawn_agent, list_agents, get_agent_status, template_metrics
planning	4	decompose_task, execute_task_tree, list_solutions, get_solution
workflows	4	run_workflow, resume_workflow, list_workflows, get_workflow_status
errors	4	error_record, error_search, error_recent, error_resolution
journal	2	journal_entry, read_journal
beads	5	beads_list_ready, beads_create, beads_update, beads_close, beads_sync
critic	3	critique_output, validate_and_improve, get_critic_config
system	2	system_health, get_config
status	1	status_dashboard
research	2	notebooklm_research, reddit_research
files	1	create_share_link
compliance	1	check_compliance
autonomy	3	autonomous_status, autonomous_enable, autonomous_disable
messaging	3	send_agent_message, broadcast_message, get_pending_messages
registry	2	list_templates, register_custom_template
notebook	2	notebook_query, notebook_add_sources
news	1	get_ai_news
ralph	3	ralph_enable, ralph_disable, ralph_status
memory	2	memory_search, memory_store
consolidation	1	consolidate_knowledge

Total: 50+ tools across 24 modules

Aegis MCP Server¶

Overview¶

Tool Categories¶

1. Agent Orchestration¶

spawn_agent¶

list_agents¶

get_agent_status¶

orchestration_dashboard¶

2. HTN Planning¶

decompose_task¶

execute_task_tree¶

list_solutions¶

3. Workflows¶

run_workflow¶

resume_workflow¶

list_workflows¶

4. Error Tracking¶

error_record¶

error_search¶

error_recent¶

error_resolution¶

5. Memory & Knowledge¶

journal_entry¶

read_journal¶

6. Beads Task Management¶

beads_list_ready¶

beads_create¶

beads_update¶

beads_close¶

7. Critic Agent¶

critique_output¶

validate_and_improve¶

8. System Status¶

system_health¶

get_config¶

9. Research¶

notebooklm_research¶

reddit_research¶

10. File Sharing¶

create_share_link¶

11. Compliance & Autonomy¶

check_compliance¶

autonomous_status¶

autonomous_enable/autonomous_disable¶

12. Messaging¶

send_agent_message¶

broadcast_message¶

Configuration¶

Startup¶

Dependencies¶

Integration Patterns¶

1. Agent-First Workflow¶

2. Error Recovery Pattern¶

3. Quality Gate Pattern¶

Performance Considerations¶

Token Usage¶

Caching¶

Async Operations¶

Troubleshooting¶

Common Issues¶

Debug Mode¶

Next Steps¶

Complete Tool List¶

`spawn_agent`¶

`list_agents`¶

`get_agent_status`¶

`orchestration_dashboard`¶

`decompose_task`¶

`execute_task_tree`¶

`list_solutions`¶

`run_workflow`¶

`resume_workflow`¶

`list_workflows`¶

`error_record`¶

`error_search`¶

`error_recent`¶

`error_resolution`¶

`journal_entry`¶

`read_journal`¶

`beads_list_ready`¶

`beads_create`¶

`beads_update`¶

`beads_close`¶

`critique_output`¶

`validate_and_improve`¶

`system_health`¶

`get_config`¶

`notebooklm_research`¶

`reddit_research`¶

`create_share_link`¶

`check_compliance`¶

`autonomous_status`¶

`autonomous_enable`/`autonomous_disable`¶

`send_agent_message`¶

`broadcast_message`¶