Hello World: IDE + first prompt
Build Aegis, start a verified profile, point Cursor/VS Code/Kiro at /mcp, and see allow / approve / audit.
USER HANDBOOK
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 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.
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.
Aegis evaluates the tool class, typed resource, policy, egress, approval, receipt, and audit intent before it resolves the backend credential.
CHOOSE YOUR PATH
Build Aegis, start a verified profile, point Cursor/VS Code/Kiro at /mcp, and see allow / approve / audit.
Keep the server’s capability and schemas; add Aegis’s governance at the MCP boundary.
Use the MCP integration guideDeclare methods, paths, schemas, resources, and backend success semantics as type: http tools.
Use JDBC, ZooKeeper, Kafka Admin, Spark Connect, A2A, or a custom Java plugin.
Explore typed integrationsGenerate a draft with --openapi-draft: every tool DESTRUCTIVE and a deny-all policy until a person reviews it.
One A2A 1.0 agent becomes one governed tool; Aegis is an A2A client, not an A2A server.
Open the A2A profileChoose a retained two-front-door example, or a clearly labelled contract-only profile.
Open the adopter catalogOPERATING MODEL
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 complements backend authorization and network policy; it does not replace either. Use least-privilege backend credentials regardless of tool class.
THREAT COVERAGE
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.
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
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.
DEPLOYMENT ONE
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
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.
ext/.AEGIS_MCP to a topology with identity assertion and authorization.Follow the exact Knox installation steps. Add only the state and plugin jars required by your configuration.
EVIDENCE BEFORE CLAIMS
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.
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 examplesFour profiles load and are governance-tested. Atlas, Cassandra, Impala, and Paimon are on the future roadmap until a real product answers them.
Read validation boundariesNew 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
credentials.type: token-exchange).adopters/hooks.REFERENCE MAP