aegis-mcp-server

MCP enforcement layer for the Aegis agent governance specification.

The spec writes the law. The CLI generates the law. This enforces the law.

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 (aegis_write_file, aegis_read_file, etc.) and gets back either a success or a blocked response with the specific reason.

Quick Start

npm install -g aegis-mcp-server

# Or use npx
npx aegis-mcp-server --project . --role default

Claude Code Configuration

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

For role-specific enforcement:

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

Tools

Zero Token Overhead

Traditional approach: load governance files into the agent's context window. Token cost scales with policy complexity.

Aegis MCP approach: the server loads policy into its own process memory. The agent calls tools and gets structured results. A project with 200 lines of governance has the same token cost as one with 20 lines. The complexity is absorbed by the server, not the agent.

Enforcement

• Governance boundaries — writable, read_only, forbidden path lists from governance.json

• Role scoping — agents confined to their role's writable and readable paths

• Sensitive pattern detection — content scanned against governance-defined patterns

• Cross-domain boundaries — imports validated against shared interface rules (when configured)

• Quality gate validation — pre_commit flags mapped to build_commands and executed

• Override logging — violations logged to append-only overrides.jsonl

• Immutable policies — designated rules that cannot be overridden, even with human confirmation

Architecture

Agent ──→ aegis-mcp-server ──→ File System
              │
              ├── Loads .agentpolicy/ into process memory (once)
              ├── Watches for policy changes (auto-reload)
              ├── Validates every tool call against policy
              └── Returns success or blocked with reason

Three artifacts, one governance framework:

• aegis-spec — Writes the law

• aegis-cli — Generates the law

• aegis-mcp-server — Enforces the law

License

MIT