HELLO WORLD

Add Aegis to your development cycle.

You do not rewrite Kafka, Spark, Airflow, or your existing MCP server. You put Aegis in front, point your IDE’s MCP settings at Aegis, and every tool call is classified, scoped, approved when needed, and audited before the backend runs.

WHAT CHANGES

One new hop. Same tools. Governed decisions.

Without Aegis an agent can reach backends with a broad credential; with Aegis a fixed governance gate runs first.

Before

Cursor, VS Code, Kiro, or Claude Desktop talks straight to an MCP server or product API. Whatever credential that path holds can execute the tool.

After

The IDE talks only to Aegis (/mcp). Aegis applies tool class, groups, policy, egress, approval, dry-run receipt, and audit. Only then does it call your MCP server or Apache engine.

Aegis does not replace backend authorization or network policy. Use least-privilege backend credentials in every path.

PICK ONE START

Three Hello World paths. Same governance engine.

2. You run an Apache engine with a shipped profile

Copy a retained adopter config (Kafka, Spark, Flink, Airflow, ZooKeeper, …). Start the engine, start Aegis, paste the IDE JSON.

Tutorial index · Adopter catalog

3. You only have a REST API

Declare type: http tools (method, path, schema, class, resources). Or generate a deny-all draft from OpenAPI and review it.

HTTP tools reference · OpenAPI draft

Optional: Apache Knox already at the edge

Knox authenticates and admits the route. Aegis still decides each MCP action. Same YAML governance as own host.

Knox extension guide

Links ending in .html on this page target the rendered documentation site. In a source checkout, open the corresponding .md source when a rendered page has not been generated locally.

FIRST-GREEN PATH

Hello World: build once, govern one project, prompt from your IDE.

Use this when you want your first green path without starting Kafka, Spark, or Docker. The checked-in example inventory service is Python's standard library. Aegis governs it on http://127.0.0.1:8080/mcp.

Step 1 - Build Aegis

JDK 17+ and Maven 3.9+. From the repository root:

mvn -B -DskipTests install

That produces aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar. Use mvn -B -Preal-engines -DskipTests install when you later start a typed source such as Kafka or Spark Connect.

Step 2 - Generate development credentials

Three people: ana reads, oscar operates, petra approves. Generate fresh random values in the terminal you will use for every step below. The configuration names the variables and does not contain the secrets.

# PowerShell
Set-Location .\adopters\tutorials\hello-world
$env:AEGIS_SIGNING_KEY = [guid]::NewGuid().ToString('N') + [guid]::NewGuid().ToString('N')
$env:ANALYST_TOKEN = [guid]::NewGuid().ToString('N')
$env:OPERATOR_TOKEN = [guid]::NewGuid().ToString('N')
$env:APPROVER_TOKEN = [guid]::NewGuid().ToString('N')

Step 3 - Start the service and Aegis

.\start-hello.ps1
# if port 8080 is already in use: .\start-hello.ps1 -Port 18080
# Aegis is ready on http://127.0.0.1:8080/mcp (governing the inventory service on 127.0.0.1:9109).

The script starts adopters/clients/example_inventory_service.py on 127.0.0.1:9109 and the gateway in the background, then returns, so the same terminal keeps the variables. On another port, add -Url http://127.0.0.1:18080/mcp to every .\mcp.ps1 call in step 4 and change the $admin URL to that same port. Bash: start-hello.sh and stop-hello.sh in the same folder. A missing variable or a busy port stops the script with a message that names it. Do not copy examples/adopters/existing-mcp-server/aegis/own-host.yaml as this starter: it binds a random port and requires a downstream MCP server from the machine that recorded the run.

Step 4 - See governance work, from the command line

# ana sees one tool; oscar sees two
.\mcp.ps1 -Token $env:ANALYST_TOKEN  -Method tools/list
.\mcp.ps1 -Token $env:OPERATOR_TOKEN -Method tools/list
# a read is allowed
.\mcp.ps1 -Token $env:ANALYST_TOKEN -Name inventory_list_things
# a reader cannot delete: READONLY_CALLER (step 1)
.\mcp.ps1 -Token $env:ANALYST_TOKEN -Name inventory_delete_thing -Arguments @{id='t-1'}
# an operator needs an approval: APPROVAL_REQUIRED (step 4)
.\mcp.ps1 -Token $env:OPERATOR_TOKEN -Name inventory_delete_thing -Arguments @{id='t-1'}

# preview, approve, run
$A = 'io.github.vaquarkhan.aegis/'
$dry = .\mcp.ps1 -Token $env:OPERATOR_TOKEN -Name inventory_delete_thing -Arguments @{id='t-1'} -Meta @{"${A}dryRun"=$true} -PassThru
$d = $dry.result._meta."${A}decision"
$admin = 'http://127.0.0.1:8080/aegis/v1/approvals'
Invoke-RestMethod -Method Post "$admin/$($d.approvalRequestId)/approve" -Headers @{Authorization="Bearer $env:APPROVER_TOKEN"}
$token = (Invoke-RestMethod "$admin/$($d.approvalRequestId)" -Headers @{Authorization="Bearer $env:OPERATOR_TOKEN"}).token
.\mcp.ps1 -Token $env:OPERATOR_TOKEN -Name inventory_delete_thing -Arguments @{id='t-1'} -Meta @{"${A}approvalToken"=$token; "${A}dryRunReceipt"=$d.dryRunReceipt}
# the same approval cannot be used twice
.\mcp.ps1 -Token $env:OPERATOR_TOKEN -Name inventory_delete_thing -Arguments @{id='t-1'} -Meta @{"${A}approvalToken"=$token; "${A}dryRunReceipt"=$d.dryRunReceipt}

Each denied call is refused before the service sees it. curl.exe -s http://127.0.0.1:9109/_received lists the requests that reached the service, and the only DELETE in it is the approved one. If oscar posts the approve call himself, the admin API answers HTTP 403. In bash, ./mcp.sh sends the same MCP calls.

Step 5 - Point Cursor or Kiro at Aegis

Copy this into the project the editor has open. Cursor: .cursor/mcp.json. Kiro: .kiro/settings/mcp.json. Replace the token with the value of ANALYST_TOKEN (the person ana, who can read).

{
  "mcpServers": {
    "aegis-hello-world": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer REPLACE_WITH_ANALYST_TOKEN" }
    }
  }
}

Reload MCP. You are ready to instruct the agent when the editor lists aegis-hello-world and its tools. Ask it to list the inventory. A delete is DESTRUCTIVE and needs petra to approve. The agent calls Aegis, not port 9109.

Step 6 - Verify the audit journal and stop

.\stop-hello.ps1
java -jar ..\..\..\aegis-gateway\target\aegis-gateway-2.0.0-SNAPSHOT-all.jar --verify-audit work\audit\aegis-hello-world.jsonl
# OK records=... head=sha256:...

stop-hello stops only the two processes start-hello started. work/ is gitignored.

Later - an Apache engine

Recorded existing-MCP scenario (two downstream MCP servers, both front doors, and assertions):

# PowerShell, from the repository root
.\examples\adopters\existing-mcp-server\setup.ps1 -Destination C:\aegis-engines
# Set AEGIS_MCP_PYTHON, AEGIS_NODE, and AEGIS_MCP_FILESYSTEM_JS to the paths printed above.
$env:AEGIS_KNOX_HOME = 'C:\knox\knox-3.0.0'   # only needed for the Knox door
.\examples\adopters\run-example.ps1 existing-mcp-server -Keep

# bash, from the repository root
examples/adopters/existing-mcp-server/setup.sh /opt/aegis-engines
# Export AEGIS_MCP_PYTHON, AEGIS_NODE, and AEGIS_MCP_FILESYSTEM_JS as printed above.
export AEGIS_KNOX_HOME=/opt/knox/knox-3.0.0     # only needed for the Knox door
examples/adopters/run-example.sh existing-mcp-server --keep

The setup scripts install pinned downstream servers outside the repository and print the three required paths. Set all three variables before running the example; without them the test is skipped, never passed. Omit AEGIS_KNOX_HOME only when you do not run the Knox door. -Keep copies that run over the retained evidence files. The test stops the processes it started, so this command does not leave a gateway for the IDE.

Or pick your Apache project name (kafka, airflow, spark-connect, …) from the tutorial index. Each tutorial lists the engine command, own-host YAML, and Knox flavor.

Leave a gateway listening on port 8080 (Spark and Iceberg own host). Generate the four values. The configuration names the variables and does not contain the secrets. Spark Connect and the Iceberg catalog from that tutorial must already be up, because this gateway calls them.

# PowerShell, from the repository root
$env:AEGIS_SIGNING_KEY = [guid]::NewGuid().ToString('N') + [guid]::NewGuid().ToString('N')
$env:READER_TOKEN = [guid]::NewGuid().ToString('N')
$env:ENGINEER_TOKEN = [guid]::NewGuid().ToString('N')
$env:APPROVER_TOKEN = [guid]::NewGuid().ToString('N')
.\adopters\tutorials\spark-iceberg\start-gateway.ps1

Bash uses the same four variables and adopters/tutorials/spark-iceberg/start-gateway.sh. The script listens on http://127.0.0.1:8080/mcp. Do not copy examples/adopters/existing-mcp-server/aegis/own-host.yaml as a starter: it binds a random port, requires ENGINE_MCP_TOKEN plus the validation token variables, and its downstream URL and stdio command are paths from the machine that recorded the run. Do not start from adopters/configurations/existing-mcp-server/existing-mcp-server.yaml either: that file has no host section.

IDE files for an Apache project

Ready-made files live under adopters/tutorials/<project>/ide/. Example for Cursor (own host):

{
  "mcpServers": {
    "aegis-existing-mcp-server": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_YOUR_TOKEN"
      }
    }
  }
}
IDEWhere the file goes
CursorCopy ide/cursor/mcp.json to .cursor/mcp.json. The generated Cursor file is own-host only.
VS Code / CopilotCopy ide/vscode/mcp.json to .vscode/mcp.json for own host, or copy ide/vscode/mcp.knox.json to the same destination for Knox.
KiroCopy ide/kiro/mcp.json to .kiro/settings/mcp.json. It includes own host enabled and a Knox entry present but disabled.
Claude Desktopdesktop config (see Spark+Iceberg tutorial)

Replace the placeholder with the value supplied to the selected own-host identity token environment variable, or answer the IDE prompt where supported. The generated files name inputs or placeholders; they do not contain usable token values. Until Aegis is listening on that URL, the IDE shows an empty or failing MCP server; start the gateway first.

Prompt an Apache project

Use a prompt the tutorial lists under “Prompts to try” (for example list jobs, list topics, list DAGs). Expect one of:

Full IDE-and-dataset walkthrough: Spark and Iceberg from your IDE. Plain-language IDE folder guide: adopters/tutorials/README.md.

DAY-TO-DAY WORKFLOW

How Aegis sits in an existing development cycle

1. LocalDeveloper runs engine + Aegis on loopback; IDE MCP points at 127.0.0.1:8080/mcp.
2. SharedTeam deploys one Aegis (own host or Knox) with reviewed YAML; CI can run contract tests and Keep profiles.
3. ChangeNew tools = YAML (or OpenAPI draft) + classification + resources + egress. No agent SDK rewrite.
4. EvidenceApprovals and denies land in the hash-chained audit journal; verify with --verify-audit.

What you keep doing

Write product code, operate Kafka/Spark/Airflow, use IDE agents for exploration and change requests. Backend APIs and MCP servers stay yours.

What you add once

One Aegis configuration per governed surface; host identity (JWT or static tokens); approver groups; egress allow list; IDE MCP entry that targets Aegis.

Container and cluster options: Dockerfile and Helm chart. Operator details: developer guide and configuration reference.

APACHE PROJECTS

How to put secure MCP in front of an Apache project

Aegis is built so the Apache project itself changes nothing: no new dependency, no fork, no rebuild. You choose the source type that matches the product’s real API.

Project has…Aegis sourceStart from
Its own MCP servertype: mcpexisting MCP server tutorial
A documented REST / HTTP Admin APItype: http declarative toolsShipped adapter under adopters/configurations/adapters/<name>/
SQL over JDBC (Hive, Calcite/Avatica, …)type: jdbcHive / Calcite profiles + JDBC converter
ZooKeeper data tree / AdminServerZooKeeper converter + HTTP Admin commandsZooKeeper tutorial
Spark Connecttyped Spark Connect pluginSpark Connect tutorial
Kafka Admin / Connect RESTkafka-admin + HTTP Connect toolsKafka tutorial

Operator checklist for a new Apache surface

  1. Find the closest profile in adopters/configurations (or generate an OpenAPI draft for a REST API).
  2. Classify every tool: READ, MUTATE, or DESTRUCTIVE. Unlisted tools default to DESTRUCTIVE (or use unlistedTools: HIDE).
  3. Name typed resources with JSON pointers (for example kafka:topic from /topic) so policy can constrain objects, not only tool names.
  4. Set egress.allowCidrs (or hosts) to the engine’s real addresses only.
  5. Wire groups: readers, operators, approvers. Separate people who request from people who approve.
  6. Run the matching tutorial Keep (or contract test) before you call the path “verified” for a release.

Twenty-eight profiles already have retained own-host and Knox Keep runs with IDE tutorials. Four more (Atlas, Cassandra, Impala, Paimon) are contract-supported until a full product stack Keep lands. What each still needs is on the future roadmap.

Deep adoption narrative (MCP vs HTTP vs typed source): Adoption guide. Security reviewers: security and threat-model guide.

NEXT

After Hello World

Learn the control model

Tool classes, approvals, receipts, and fail-closed deny codes.

User handbook

Harden the deployment

Threat zones, OWASP MCP mapping, S1 to S31 promises and limits.

Security guide

Extend Aegis

Sources, hooks, state, and secret providers without moving policy into plugins.

Developer guide

Check evidence

What is proven on this tree versus what still needs a target Keep.

Validation report