USER HANDBOOK

Put governance between agents and real systems.

Aegis is the MCP-first governance platform for real-system actions. Its own host and optional Apache Knox extension are deployment choices; the Aegis engine always evaluates action class, resource scope, policy, approvals, receipts, and audit intent before a backend call.

THE PROBLEM

MCP makes tools easy to call. Governance decides whether a call may execute.

MCP is a common protocol for clients such as agents, IDEs, and services to discover and call structured tools. That turns a data platform, cluster, catalog, or business API into an agent-callable control plane. Route security can protect POST /mcp, but it cannot by itself decide whether a specific tool, resource, and argument set is appropriate.

Untrusted context can influence an agent; Aegis applies a fixed governance gate before an approved backend action.

Without semantic governance

A model can be influenced by untrusted content while a broad service credential can carry out its tool request. The backend and a route ACL see only part of that decision.

With Aegis

Aegis evaluates the tool class, typed resource, policy, egress, approval, receipt, and audit intent before it resolves the backend credential.

CHOOSE YOUR PATH

What are you trying to do?

Hello World: IDE + first prompt

Build Aegis, start a verified profile, point Cursor/VS Code/Kiro at /mcp, and see allow / approve / audit.

Open the Hello World guide

Connect an existing MCP server

Keep the server’s capability and schemas; add Aegis’s governance at the MCP boundary.

Use the MCP integration guide

Start from an OpenAPI document

Generate a draft with --openapi-draft: every tool DESTRUCTIVE and a deny-all policy until a person reviews it.

Read the draft command

Offer an A2A agent as a tool

One A2A 1.0 agent becomes one governed tool; Aegis is an A2A client, not an A2A server.

Open the A2A profile

Start with an Apache engine

Choose a retained two-front-door example, or a clearly labelled contract-only profile.

Open the adopter catalog

OPERATING MODEL

Aegis owns one MCP decision path; hosts are deployment choices.

Aegis owns the MCP action decision in every deployment. Its own host establishes identity with Aegis configuration. An optional Knox integration supplies external identity and route admission from an existing topology. The Aegis engine then evaluates exposure, input and resource scope, policy, egress, rate/budget, breaker, screening, approval, receipt, audit intent, and execution in a fixed order.

Aegis is the MCP-first governance core, with its own host and optional Knox adapter as deployment choices. Aegis own-host and Apache Knox integration choices reach one shared governance core before configured backend sources.
READStandard governance controls.
MUTATEIndependent per-call approval by default.
DESTRUCTIVEApproval plus a fresh bound dry-run receipt.

Aegis complements backend authorization and network policy; it does not replace either. Use least-privilege backend credentials regardless of tool class.

THREAT COVERAGE

OWASP MCP Top 10: coverage is not a claim of elimination.

The OWASP MCP Top 10 is a threat checklist for systems that expose AI-callable tools. Aegis maps each item to a gateway control and states what remains an operator, identity-provider, backend, or network responsibility. See the product threat model and security validation record for STRIDE scenarios and dated control-suite results with their attestation status.

Aegis coverage of all ten OWASP MCP risk areas, grouped as strong, partial, limited, or external.
MCP01 to MCP03Strong gateway controls for tokens, privilege scope, and changed tool definitions; provided the first pin is trusted.
MCP04 and MCP05Partial supply-chain and command-execution coverage; release controls and runtime sandboxing remain outside Aegis.
MCP06Prompt-injection screening reduces impact but is heuristic. Typed scope and independent approval are the durable safeguards.
MCP07 and MCP08Strong authentication/authorization and local audit evidence controls; identity operations and off-host monitoring remain deployment work.
MCP09Shadow servers cannot be discovered or prevented by a gateway that is not in their network path.
MCP10Caller-filtered discovery and guarded content help, but clients can retain or disclose received data.

Read the full S1 to S31 security mapping, test evidence, and residual responsibilities. The HTML security guide collects the threat-model diagram, abuse cases, and validation record in one place: open the security guide.

THREAT MODEL

Review the governed MCP boundary before you trust a claim.

Security reviewers start with the product threat model: trust zones Z1 to Z6, STRIDE, abuse scenarios TM01 to TM10, and residual risk. Control promises S1 to S31 are listed with their tests. A 2026-10-05 record reports a focused selection of 227 tests with 0 failures.

Aegis threat model: trust zones, STRIDE, and the governed MCP boundary.

DEPLOYMENT ONE

Run Aegis as its own host.

Use the shaded executable for an HTTP(S) or stdio MCP endpoint, or the container image and Helm chart built from the repository (Dockerfile, charts/aegis). Configure host identity, routes, sources, policy, audit, and state explicitly.

java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --config aegis.yaml

Open the configuration reference for TLS, JWT/static identity, OAuth metadata, CORS, route and per-tool scopes (actionScopes), egress, the signed serverCatalog with break-glass containment, and source settings. Use the fixed-journal audit verification endpoint only through its dedicated verifier group.

DEPLOYMENT TWO

Optional: run Aegis in Apache Knox 3.0.

Use this integration only when Knox already supplies your HTTP perimeter. Knox owns edge authentication, identity assertion, and route admission. Aegis receives the Knox subject, parses the MCP body, and applies its standard per-tool governance decision.

  1. Build Aegis with JDK 17+ and Maven 3.9+.
  2. Copy the documented jars or the Knox bundle to Knox ext/.
  3. Add AEGIS_MCP to a topology with identity assertion and authorization.
  4. Point the service at the Aegis configuration and restart Knox.

Follow the exact Knox installation steps. Add only the state and plugin jars required by your configuration.

EVIDENCE BEFORE CLAIMS

Prove the exact path you plan to operate.

The default build establishes deterministic governance, configuration, documentation-contract, and embedded-real converter evidence. A retained run against the named target version establishes target verification for an adopter profile.

Verified examples

Twenty-eight profiles have retained own-host and Knox results, configuration, topology, engine files, and audit journals, each with an IDE-ready tutorial.

Browse verified examples

Contract-only profiles

Four profiles load and are governance-tested. Atlas, Cassandra, Impala, and Paimon are on the future roadmap until a real product answers them.

Read validation boundaries

New to Aegis? The Spark and Iceberg tutorial takes you from a tiny dataset to a governed change from your IDE, with and without Knox. Then pick the real walkthrough closest to your deployment from the tutorial index: Kafka, Spark, Iceberg, or Flink. Docker Keep tutorials now also cover Airflow, CouchDB, Doris, Druid, Hadoop, HBase, NiFi, Pinot, Storm, and Superset.

OPERATIONAL CHECKLIST

Operate safely from day one.

REFERENCE MAP

Continue by role.