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

Tool	What it does	Token cost
`aegis_check_permissions`	Pre-check if an operation is allowed	Tiny — just the verdict
`aegis_write_file`	Write with path + content validation	Same as a normal write
`aegis_read_file`	Read with path validation	Same as a normal read
`aegis_delete_file`	Delete with path validation	Tiny — just the verdict
`aegis_execute`	Execute a command in project root	Command output only
`aegis_complete_task`	Run quality gates before marking done	Gate results only
`aegis_policy_summary`	Minimal role + permissions summary	~200 tokens

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

Aegis MCP Server