AGA MCP Server

Cryptographic runtime governance for AI agents and autonomous systems.

Status: published to npm; this release carries SLSA build provenance (check it:npm audit signatures).The server tools and theaga-proxyemit thecanonical SEP evidence bundle, verifiable offline by the published@attested-intelligence/aga-verifyand the reference verifieraga-receipt-spec/verify/verify-sep.mjs.Since 3.2.0 the verifier is algorithm-agile and ships a post-quantum profile:v1Ed25519-SHA256-JCS(the default the gateway emits) and v2ML-DSA-65+Ed25519-SHA256-JCS(a NIST FIPS-204 ML-DSA-65 + RFC-8032 Ed25519composite, both must verify), selected per-bundle by thealgorithmfield with aVERIFIED / FAILED / UNSUPPORTED_PROFILEtrichotomy. Pre-3.0 releases (a legacy continuity-chain bundle that doesnotverify under the SEP verifier) are deprecated; use^3.0.0. Claim scope and residual attack surface are documented honestly inTHREAT_BOUNDARY.md.

# This package IS the AGA MCP server (TypeScript, runs over stdio). Use it from any MCP client: npx -y @attested-intelligence/aga-mcp-server

A Python companion SDK (aga-governance) is documented in the Python SDK section below.

Verify this yourself (don't take our word)

You do not have to take any of this on faith. The repo ships the reference verifier, the canonical vectors, and sample bundles, so you can check one offline right now, with no network and no callback to us:

git clone https://github.com/attestedintelligence/aga-mcp-server cd aga-mcp-server # A canonical SEP bundle verifies; a one-byte-tampered copy is rejected. node aga-receipt-spec/verify/verify-sep.mjs fixtures/valid_minimal.json # OVERALL: VERIFIED (integrity only; no key pinned) node aga-receipt-spec/verify/verify-sep.mjs fixtures/tampered.json # OVERALL: FAILED

The published@attested-intelligence/aga-verifyCLI renders the identical verdict, andnpm run conformance:cross-stack(first:npm run build && npm --prefix independent-verifier run build) proves six v1 verifier configurations, spanningthree independent toolchains (JavaScript, Go, and Python, including a pure-stdlib, no-third-party-crypto path), agree on all57cross-stack cases;npm run conformance:cross-stack-v2provestwo genuinely independent-language oracles (@noble/JS and CIRCL/Go)agree on the v2 composite corpus. For a full trust-free reproduction (build the package yourself, reproduce the published tarball byte-for-byte, re-run every gate), see theREVIEWER_GUIDE.md(a command-by-command self-service path),REPRODUCIBILITY.md, and the step-by-stepSKEPTICAL_AUDITOR.md. This release carries SLSA build provenance, checkable withnpm audit signatures.

Scope:a verified bundle proves theintegrity of the receipts present: each is authentic, correctly ordered, Merkle-included, and (when a key is pinned) provenance-bound. It doesnotprove non-omission (that every action the agent took was logged); completeness is bounded by the tamper-evidence of the interception point, which is outside the bundle. SeeKNOWN_LIMITATIONS.mdfor the full honest boundary, andTHREAT_BOUNDARY.mdfor the per-field detail.

{ "mcpServers": { "aga": { "command": "npx", "args": ["-y", "@attested-intelligence/aga-mcp-server"] } } }

Claude can then seal artifacts, measure integrity, generate evidence bundles, and verify compliance through natural language.

By default the gateway signs with anephemeralkey that rotates on every restart. That is fine for a first look, but evidence-bundle provenance cannot be pinned across restarts (and the server warns about it on stderr). Set one stable 64-hex Ed25519 seed so provenance stays pinnable:

# generate a seed once (32 random bytes, hex) node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

Provide it viaAGA_GATEWAY_KEY, orAGA_GATEWAY_KEY_FILE(a path to the seed). In Claude Desktop, add anenvblock:

{ "mcpServers": { "aga": { "command": "npx", "args": ["-y", "@attested-intelligence/aga-mcp-server"], "env": { "AGA_GATEWAY_KEY": "<your-64-hex-seed>" } } } }

Keep the seed secret and out of version control; seeDEPLOYMENT.mdfor key handling.

measure_behavioris detective-only by default: it observes tool-usage patterns and records asigned, provabledrift finding, but does not block. Enforcement (drift → quarantine) is opt-in viaenforce=trueand off by default. Hard governance decisions (PERMITTED/DENIED) are made by the portal/PEP, not the behavioral monitor.

A bundle this package emits (via thegenerate_evidence_bundleMCP tool) is acanonical SEP bundle. Verify it offline, with no network and no callback to us:

# Published verifier CLI — ships on npm, nothing to clone. Pin the gateway key (from get_server_info) to prove provenance. npx -y @attested-intelligence/aga-verify evidence-bundle.json --pubkey <gateway-public-key> # Or, from a clone of this repo, the zero-dep reference verifier (Node 18+) renders the identical verdict: node aga-receipt-spec/verify/verify-sep.mjs evidence-bundle.json --pubkey <gateway-public-key>

The published@attested-intelligence/aga-verifyCLI is the shipped path (the older forgeable 1.0.0 is deprecated); the referenceverify-sep.mjsrenders the identical verdict from a repo clone. Without--pubkeyyou get anintegrity-onlyresult (issuerVerified=false); pin the key to also provewhoissued it. SeeTHREAT_BOUNDARY.md§3.7. A hosted browser verifier is linked underLinks.

AI Agent AGA Gateway Verifier | | | |-- tools/call ----------->| | | [Evaluate Policy] | | [Sign Receipt] | | [Chain to Previous] | |<-- PERMITTED/DENIED -----| | | | | | [Export Bundle] | | |--------- evidence.json ----->| | | [Verify Signatures] | | [Verify Chain + Order] | | [Verify Merkle Tree] | | [Verify Signed Checkpoint] | | [PASS / FAIL]

Run AGA as a transparent proxy between any MCP client and any MCP server. Every tool call gets evaluated against policy and produces a signed receipt.

# Start the proxy (the aga-proxy bin) in front of an upstream MCP server. # stdio upstream = the hardened default (the upstream is a child process, not network-reachable). npx -p @attested-intelligence/aga-mcp-server aga-proxy start \ --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp/test" --profile standard

Exporting the evidence bundle from a running proxy

The proxy records receipts in its own process and keeps the SEP ledgerin memory. To make that live ledger reachable from a separate shell,aga-proxy startopens aloopback-only control channel— an HTTP listener bound to127.0.0.1(never a routable interface), on its own port (default18801, override with--control-port), distinct from the agent-facing proxy port (18800). It exposes only read routes (/export,/status,/receipts); nothing on it mutates policy or state, and it is unreachable off-host by construction (the loopback bind is the guarantee). The proxy writes the chosen control port to~/.aga-proxy/control.jsonalongsideproxy.pid.

Aseparateaga-proxy exportinvocation reads that file and fetches the same signed bundle the running proxy would emit:

# Terminal A — start the proxy in front of an upstream MCP server npx -p @attested-intelligence/aga-mcp-server aga-proxy start \ --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp/test" --profile standard # Terminal B — export the live ledger from a different shell, then verify it offline npx -p @attested-intelligence/aga-mcp-server aga-proxy export -o evidence.json npx -y @attested-intelligence/aga-verify evidence.json --pubkey <gateway-public-key>

If no proxy is running,aga-proxy exportprintsno running proxy found; start it first, or export from within the sessionand exits non-zero — it never emits an empty or placeholder bundle. Within the MCPserversession you can also call thegenerate_evidence_bundletool and save the returned JSON.

In-memory ledger:the exported bundle is the durable cryptographic record, but the live in-process chain doesnotsurvive a proxy restart. This flow makes theliveledger reachable from another process; it doesnotadd cross-restart persistence, which needs the persistent (SQLite) backend and remains roadmap (seeKNOWN_LIMITATIONS.md).

# Check status curl https://aga-mcp-gateway.attested-intelligence.workers.dev/health # Export evidence bundle curl https://aga-mcp-gateway.attested-intelligence.workers.dev/bundle -o evidence-bundle.json

from aga import AgentSession with AgentSession(gateway_id="my-gateway") as session: session.record_tool_call( tool_name="search_web", decision="PERMITTED", reason="tool in allowlist", request_id="req-1", ) bundle = session.export_bundle() result = session.verify() assert result["overall_valid"]

Automated tests across TypeScript and Python, plus a conformance corpus:

- TypeScript MCP server:384 automated tests (vitest), including provable-denial and behavioral-monitor regressions
- SEP conformance corpus:npm run test:conformance(valid → VERIFIED, negatives → FAILED)
- Python companion SDK:the separately-publishedaga-governancePyPI package (install + smoke-checked here; its full pytest suite runs from the source tree)

npm test # TypeScript tests (vitest) npm run test:conformance # SEP conformance corpus pip install aga-governance && python -c "import aga; print(aga.__version__)" # Python SDK smoke check

Receipt-format determinism is reproducible here:npm testruns the cross-language vectors, andnpm run conformance:cross-stack(first:npm run build && npm --prefix independent-verifier run build) shows the six v1 verifier configurations (across three independent toolchains: JS, Go, Python) agree on the canonical 57-case corpus, whilenpm run conformance:cross-stack-v2shows the two independent-language v2 oracles agree on the composite corpus.

src/ sep/ # Canonical SEP evidence engine: single source of truth (canon, merkle, receipt, checkpoint, bundle, verify) core/ # Governance primitives (portal, artifact, attestation, disclosure, delegation, behavioral) + internal continuity-chain profile crypto/ # Internal continuity-chain crypto: Ed25519 (node:crypto), SHA-256/blake2b, salt proxy/ # MCP governance proxy (transparent interception + policy enforcement; emits SEP bundles) middleware/ # Governance PEP wrapper (records a signed PERMITTED/DENIED receipt per governed call) independent-verifier/ # @attested-intelligence/aga-verify: standalone SEP verifier, zero AGA imports scenarios/ # Demo scenarios (SCADA, autonomous vehicle, AI agent) that emit SEP bundles tests/ # TypeScript test suite (384 automated tests)

- Website
- Technology
- Live Verifier
- Trust and Scope
- Diligence Materials
- MCP Server (npm)
- Python SDK (PyPI)

SeeSECURITY.mdfor vulnerability reporting.

SeeCONTRIBUTING.mdfor development setup and guidelines.

NIST AI Risk Management Framework compliance — risk profiling, govern/map/measure/manage functions by MEOK AI Labs