Aegis MCP

Security guardrails for AI coding agents powered by threat models

Aegis is an MCP server that gives AI coding agents (Cursor, Claude Code, Cline, Windsurf, etc.) project-specific security requirements in real time. You define your threat model once in a security-context.yaml file; every time the agent is about to write security-relevant code, it calls aegis_assess and gets back mandatory requirements, approved patterns, and anti-patterns -- deterministically, with zero token cost. After code is generated, aegis_review checks requirement-to-implementation completeness before final output.

Why

AI coding agents write working code fast, but they don't know your project's security rules. They'll generate a login endpoint without your rate-limiting policy, or query a database without your parameterization requirement. Aegis fixes that by injecting your threat model into the agent's workflow at the moment it matters.

• Deterministic. Pure structured lookup. No LLM on the hot path, no hallucinated security advice.
• Project-specific. Your trust boundaries, your data classifications, your approved patterns.
• Agent-agnostic. Works with any MCP-compatible agent.

Quickstart (2 minutes)

From your project root:

cd your-project
pip install aegis-mcp
aegis setup

aegis setup handles setup end-to-end in one command:

• Finds an existing security-context.yaml or helps you generate one with your IDE LLM
• Validates the file and loops until it is valid
• Detects your IDE (Cursor, Claude Code, Cline, Windsurf)
• Writes/merges MCP config with the aegis server entry
• Installs the matching agent instruction template

When setup completes, start coding. The agent will call aegis_assess and aegis_review automatically for security-relevant work.

Useful CLI commands:

aegis validate security-context.yaml
aegis help
aegis about

Manual setup (advanced)

If you prefer to set everything up by hand, see docs/quickstart.md and docs/generating-security-context.md.

Reference files:

• catalogs/security-patterns.yaml -- comprehensive traditional + LLM code-gen pattern catalog
• templates/security-context.template.yaml -- blank schema-shaped template
• schemas/security-context.schema.json -- schema contract
• docs/schema-reference.md -- field-level reference

Starter contexts from examples/:

• examples/minimal.yaml -- smallest valid context for first-time setup.
• examples/rest-api.yaml -- healthcare-style REST API with PHI-focused guardrails.
• examples/ecommerce.yaml -- e-commerce and payments with card-data and checkout controls.
• examples/internal-tool.yaml -- internal admin dashboard with role-based controls.
• examples/microservices.yaml -- multi-service architecture with mTLS and service-identity controls.
• examples/security-context.example.yaml -- comprehensive reference covering most sections.

How it works

sequenceDiagram
    participant You
    participant Agent as AI Coding Agent
    participant Aegis as Aegis MCP Server

    You->>Agent: "Build a signup endpoint"
    Note over Agent: Reads template instructions
    Note over Agent: Categorizes task into canonical IDs
    Agent->>Aegis: aegis_assess(boundary, data_types, action, ...)
    Aegis->>Agent: Requirements + approved patterns + anti-patterns
    Note over Agent: Writes code following the checklist
    Agent->>Aegis: aegis_review(requirements, self-report mappings)
    Aegis->>Agent: pass: false (missing encrypt-pii-at-rest)
    Note over Agent: Revises code to satisfy missing requirements
    Agent->>Aegis: aegis_review(updated mappings)
    Aegis->>Agent: pass: true (4/4 covered)
    Agent->>You: Delivers secure code

1. You ask the agent to write code ("Add a user signup endpoint").
2. The agent recognizes the task is security-relevant and categorizes it using canonical IDs from aegis://summary (e.g. boundary_crossing: "public-to-internal", data_types: ["user-pii"], action: "create-endpoint").
3. The agent calls aegis_assess with those IDs. Aegis does a deterministic lookup against your security-context.yaml and returns all matching requirements, approved patterns, and anti-patterns.
4. The agent writes code guided by the returned checklist.
5. The agent calls aegis_review with the requirements and a self-report of how each was satisfied. If any critical/high requirements are missing, Aegis returns pass: false and the agent revises the code.
6. You receive code that enforces your project's security rules.

The agent calls aegis_assess with the relevant service IDs, data types, boundary crossings, and action (using canonical values from aegis://summary, including known_actions). Aegis returns:

Field	Description
requirements	Mandatory security constraints the generated code must satisfy.
approved_patterns	Preferred implementations (e.g. "use auth middleware").
anti_patterns	Forbidden practices (e.g. "no raw SQL interpolation").
warnings	Unknown IDs or potential schema gaps.
conflicts	When multiple sources disagree on a requirement.
no_match	true if the boundary crossing wasn't found in the context.

After implementing code, the agent calls aegis_review with:

• requirements from the latest aegis_assess response
• mappings entries with requirement_id and satisfied_by

aegis_review returns covered, missing, extra_mappings, coverage, and pass.

Tools and resources

Name	Type	Description
aegis_assess	Tool	Returns requirements, approved patterns, and anti-patterns for a given context. Deterministic; no LLM.
aegis_validate	Tool	Validates a security-context.yaml against the schema; reports errors with line numbers.
aegis_review	Tool	Verifies requirement-to-implementation coverage after code generation using provided mappings. Deterministic completeness check.
aegis://summary	Resource	Lightweight overview of trust boundaries and data classifications. Read once per session.

Advanced

Practical QA workflow

See qa/README.md for a step-by-step benchmark workflow (task suite, manual A/B agent runs, scoring, and aggregate statistics generation).

Schema reference

See docs/schema-reference.md for the full field reference and contract rules.

Development

git clone https://github.com/bgigurtsis/aegis-mcp.git
cd aegis-mcp
pip install -e .
python -m unittest discover -s tests -v

License

MIT