Installation Guide

Multiple Ways to Get Started with MCP Aegis

Choose the installation method that best fits your workflow. Most users should start with the Recommended Setup for the fastest experience.

🎯 Choose Your Installation Method

🚀 First Time / Trying Out

No installation needed - jump to Recommended Setup

→ Recommended Setup

🔧 Regular CLI Usage

System-wide access to aegis command

→ Global Installation

📦 Project Dependency

Include in your project's dependencies

→ Local Installation

Prerequisites

Node.js 18+ and npm 8+

Check with: node --version && npm --version

🚀 Recommended Setup (Fastest)

This is the same approach shown in our Quick Start Guide. Perfect for first-time users and trying out MCP Aegis:

bash

# Navigate to your MCP project directory
cd my-mcp-project

# Initialize MCP Aegis (auto-installs + creates structure)
npx mcp-aegis init

This command: Installs mcp-aegis as dev dependency, creates aegis.config.json, sets up test directories, and includes AI agent guides. No separate installation step needed!

🔧 Global Installation

Install globally for system-wide access to the aegis command:

bash

npm install -g mcp-aegis

Verify Global Installation

bash

aegis --version

# Test with help command
aegis --help

📦 Local Installation

Install as a project dependency (the init command does this automatically, but you can also do it manually):

bash

npm install --save-dev mcp-aegis

npx mcp-aegis --help

✅ Quick Verification

Verify your installation works with a simple version check:

bash

# If installed globally
aegis --version

# If using npx or local install
npx mcp-aegis --version

# Should output something like: 1.0.16

🎯 Next Steps

New to MCP Aegis?

Follow our step-by-step guide to create your first test

Start with Quick Start Guide →

Ready to Deep Dive?

Explore advanced features and configuration options

Explore Pattern Matching →

🔧 Advanced Configuration Reference

If you need custom configuration beyond what init provides:

Basic Configuration

Create aegis.config.json:

json

{
  "name": "My MCP Server",
  "command": "node",
  "args": ["./server.js"],
  "startupTimeout": 5000
}

Advanced Configuration

json

{
  "name": "Advanced MCP Server",
  "command": "node",
  "args": ["./server.js"],
  "cwd": "./server-directory",
  "startupTimeout": 10000,
  "readyPattern": "Server listening on port \\d+",
  "env": {
    "NODE_ENV": "test",
    "LOG_LEVEL": "debug"
  }
}

CONFIGURATION DEFAULTS

cwd: Current working directory at invocation time
env: Inherits process environment + any overrides in config.env
startupTimeout: 5000 ms (runtime default) / 10000 ms (init generates)
readyPattern: null (optional regex to scan stderr for readiness)
protocolVersion: 2025-06-18 (automatic MCP handshake version)

Configuration Fields

name: Human-readable server name
command: Executable command (e.g., "node", "python", "/usr/bin/node")
args: Array of command arguments
cwd: Working directory for the server (optional)
startupTimeout: Milliseconds to wait for server startup
readyPattern: Regex pattern to detect when server is ready (optional)
env: Environment variables for the server process (optional)

Note: For detailed configuration options, see ourConfiguration Guide.

🛠️ Troubleshooting Common Issues

NPM Package Not Found

Problem: npm: package 'mcp-aegis' not found

Solution:

bash

# Update npm and try again
npm install -g npm@latest
npm install -g mcp-aegis

Permission Errors

Problem: Permission denied during installation

Solutions:

bash

# Option 1: Use npx (no global install needed)
npx mcp-aegis --help

# Option 2: Fix npm permissions (recommended)
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g mcp-aegis

# Option 3: Use local installation
npm install --save-dev mcp-aegis
npx mcp-aegis --help

Command Not Found

Problem: aegis: command not found

Solutions:

bash

# Check if installed globally
npm list -g mcp-aegis

# Check PATH includes npm global bin
echo $PATH

# Use full command name or npx
mcp-aegis --help
npx mcp-aegis --help

Node Version Issues

Problem: Compatibility errors with older Node.js versions

Solution:

bash

# Check Node.js version (needs 18+)
node --version

# Update to Node.js 18+ using nvm:
nvm install 18
nvm use 18

# Or download from nodejs.org

Development/Latest Features

For development or to use the latest unreleased features:

bash

# Clone the repository
git clone https://github.com/taurgis/mcp-aegis.git
cd mcp-aegis

# Install dependencies and test
npm install
npm test

# Use development version
node bin/aegis.js --help