Aegis MCP server

by cleburn·io.github.cleburn/aegis-mcp·v0.1.15·3 stars

No reviews yet

Runtime governance enforcement for AI agents. Zero token overhead.

A88/100grade A

Write a review Install

What users say

No reviews yet

Be the first

Safety scan

A88/100

full report

Adoption

Growing

3 stars60 downloads/wk

Reviews

Write one

Nobody has reviewed Aegis yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

Aegis tools (9, 3 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

aegis_check_permissions
…Check if an operation is allowed on a path before attempting it. Use this to pre-validate before writing or reading files — saves you from composing content that would be blocked. Denied checks are logged automatically by the server. Args: - path (string): Target file path relative to project root - operation ('read' | 'write' | 'delete'): The operation to check Returns: { "allowed": true } or {
aegis_complete_task
…Signal task completion and run required quality gates. Args: - task_id (string): Identifier for the task being completed - summary (string): Brief summary of what was accomplished Returns: { "status": "passed", "gates_run": [...] } or { "status": "failed", "failures": [...] }
aegis_delete_filewrite action
…Delete a file with governance enforcement. Write permissions are required. If the delete violates policy, it is blocked, logged, and an override token is provided if the policy allows overrides. Args: - path (string): File path relative to project root Returns: { "status": "success", "path": "..." } or { "status": "blocked", "reason": "...", "override_available": bool, "override_token": "..." }
aegis_executewrite action
…Execute a shell command in the project directory with governance oversight. Args: - command (string): Shell command to execute - cwd (string, optional): Working directory (defaults to project root) Returns: { "status": "success", "stdout": "...", "stderr": "..." } or { "status": "error", ... }
aegis_policy_summary
…Get your governance summary. In universal mode (no role pre-assigned), this returns the list of available roles — present them to the user and ask which role to use, then call aegis_select_role. In fixed mode (role pre-assigned), this returns your role boundaries and governance rules. Call this FIRST before doing any work. Returns: Universal mode: { "mode": "role_selection_required", "available_r
aegis_read_file
…Read the contents of a file with governance enforcement. Path is validated against your role's read permissions. If the read violates policy, it is blocked and logged. Note: Native read tools are acceptable for general file exploration. Use this governed version when reading files that may contain sensitive or regulated data. Args: - path (string): File path relative to project root Returns: File
aegis_request_override
aegis_select_role
…Select a role for this session. Call this after aegis_policy_summary shows available roles and the user has chosen one. The MCP locks to the selected role for the remainder of the session — all enforcement uses this role's boundaries. This is a one-time selection per session. Args: - role_id (string): The role ID to select (e.g., "backend", "frontend", "qa") Returns: { "status": "role_selected",
aegis_write_filewrite action
…Write content to a file with governance enforcement. Path is validated against your role's permissions and governance boundaries. Content is scanned for sensitive patterns. If the write violates policy, it is blocked, logged, and you receive an override_token if the policy allows overrides. Present the violation to the user — if they confirm, call aegis_request_override with the token to proceed.

Public scan report

scanner v0.1.10 · 2026-09-27 · same rubric, same numbers if you re-run it

no findings

Code scan18 source files scanned25/25
–Live reliabilityno gateway calls yet and no remote to proben/a
–Tool poisoningtools not inspected (local package is not executed); not countedn/a
Auth qualitylocal package, no credentials required12/15
Maintenancelast push 45 days ago12/15
Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Overall 88/100. Components that don't apply are left out of the denominator. Any critical finding is an F.Rubric Appeal a finding JSON

How Aegis compares

Against every graded MCP server, from our own scans and uptime checks. Updated after each scan run.

Safety score: 88/100; higher than 75% of 48,255 servers
Tools: 9; the typical server has 7
Tools that change things: 33%; typical: 0%. Fewer write tools means less an agent can break
GitHub stars: 3; more than 80% of 28,688 servers
Downloads a week: 60; more than 49% of 12,191 servers with a package

What its tools let an agent do: 6 read · 3 change

Install Aegis in Claude Code, Cursor or VS Code

Runs npx -y aegis-mcp-server on your machine. Read the scan report first; the gateway never runs local packages.

claude mcp add aegis-mcp -- npx -y aegis-mcp-server

Add to Cursor

What the publisher says

From the Aegis repository's README, as published. We do not edit it. Read it on GitHub

aegis-mcp-server

MCP enforcement layer for the Aegis agent governance specification.

Policy at the root. Enforcement at runtime. Accountability on every action.

What It Does

aegis-mcp-server is an MCP server that validates every agent action against your .agentpolicy/ files before it happens. Path permissions, content scanning, role boundaries, quality gates — all enforced at runtime with zero token overhead to the agent.

The agent never loads your governance files. The MCP server reads them into its own process memory and validates silently. The agent calls governed tools and gets back either a success or a blocked response with the specific reason.

Quick Start

# Install globally
npm install -g aegis-mcp-server

If you generated your policy with aegis-cli, the .mcp.json connection config is already in your project root. Just install the MCP and open your agent — it connects automatically.

First Prompt

When starting a new agent session in a governed project, use this as your first prompt:

Call aegis_policy_summary now. This is your governance contract — it defines your
role, your boundaries, and which tools to use. Do not take any action until you have
called this tool and received confirmation from the user to proceed.

For initial builds, the Aegis CLI generates a custom handoff prompt tailored to your project — use that instead.

How It Works

Universal Mode (Default)

The MCP starts without a pre-assigned role. When the agent calls aegispolicysummary, it receives the list of available roles — including the built-in construction role and all specialist roles from .agentpolicy/roles/. The agent presents them to the user, the user picks, and the agent calls aegisselectrole to lock in. All enforcement uses the selected role for the rest of the session.

This is the default behavior — no configuration needed beyond the .mcp.json that aegis init creates automatically.

Construction Mode

The construction role is always available for initial builds and major restructuring. When selected:

The agent has full repository access (all paths writable and readable)
The .agentpolicy/ files serve as the blueprint — the agent reads constitution, governance, and role files to understand the project's architecture, conventions, and quality standards
File operations run through native tools rather than governed tools, for speed
The MCP logs the construction session start to state/overrides.jsonl with a timestamp and human_confirmed: true
When the build is complete, the agent calls aegiscompletetask to run quality gates and close construction mode — the closing timestamp is logged alongside the opening entry
All future sessions after construction should select a specialist role for governed operations

Construction mode is not a bypass — the agent still follows the governance files as its blueprint. It's a speed optimization for greenfield builds where enforcing write restrictions on every file would be counterproductive.

Fixed Mode

If you know which role to assign at startup:

{
  "mcpServers": {
    "aegis": {
      "command": "aegis-mcp",
      "args": ["--project", ".", "--role", "backend"]
    }
  }
}

The MCP locks to that role immediately. aegispolicysummary returns the role's boundaries directly, skipping role selection.

Shortened. The full README is on GitHub.

Nothing above is checked by us. What we check is on the safety report.

Aegis: common questions

Is Aegis MCP server safe?: Yes, by our scan: it is graded A (88/100). Read the Aegis safety report
How do I install Aegis?: It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.
Does Aegis need an API key?: Not as far as the registry entry and our scan can tell: no credentials are declared or required.
Is Aegis maintained?: The last commit was 83 days ago (2026-08-13). The latest release is v0.1.15.
How does Aegis compare with other MCP servers?: safety score 88/100 (higher than 75% of 48,255 servers); tools 9 (the typical server has 7); tools that change things 33% (typical: 0%. Fewer write tools means less an agent can break). Full comparison.