Aga MCP Server

AGA - Attested Governance Artifacts

Verifiable decision records for AI agents: each recorded tool-call decision is a signed, hash-chained receipt, exported in evidence bundles a reviewer can verify offline against the published format. Verification establishes the integrity of the receipts present, not that every action was recorded.

Status: published reference implementation, before independent pilot validation. Version 3.6.6 reuses one Merkle tree during export and retains the 3.6.5 transport, policy and trust-input hardening; deployment limits remain explicit below. The gateway emits classical Ed25519-SHA256-JCS bundles. The published @attested-intelligence/aga-verify@2.2.3 CLI checks that classical profile; on a v2/hybrid bundle it reports FAILED because it does not implement that profile. The package also exposes an ML-DSA-65 + Ed25519 composite as a library profile, and aga-proxy verify can check it. Reference verifiers have their own unsupported-profile behavior. These are different components, not one interchangeable verifier. Build provenance concerns the published build; it is not runtime correctness or an external security audit.

Runtime status. Since 3.5.0, a measurement requested after the active artifact's TTL expires moves it to TERMINATE; delegate_to_subagent also refuses after expiry. Nothing checks the TTL on a schedule, and the exported bundle does not record that transition. Do not downgrade to deprecated 3.3.3 as the evaluation path. Since 3.6.0, aga-proxy honors AGA_GATEWAY_KEY / AGA_GATEWAY_KEY_FILE; through 3.6.4 the stdio upstream could inherit those variables. Version 3.6.5 uses an explicit environment without implicit gateway-key inheritance. Read the known issues and THREAT_BOUNDARY.md before any runtime evaluation.

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

Reference runtime 3.6.6

Version 3.6.5 hardens the reference proxy: loopback by default, an explicit --host option, immutable validated policy snapshots, per-proxy rate limits, request ownership and stdio ID remapping, fatal UTF-8 framing, bounded transport work and disconnect cancellation. Protocol JSON refuses repeated decoded member names. The stdio child receives a small explicit environment without implicit gateway-key variables. The read-only control channel rejects a foreign Host or any browser Origin. The embedded verifier now fails a supplied malformed expected key; only omission selects integrity-only verification.

Version 3.6.6 constructs all export proofs from shared tree levels instead of rebuilding the tree for each receipt. The signed format and checkpoint are unchanged. Proof output still grows with the number of receipts and tree depth. Historical issue 9 below records the earlier quadratic implementation and its measured delays.

These controls do not provide authenticated clients, a filesystem sandbox, privileged key custody or complete MCP session/notification/server-request support. Export remains synchronous and the ledger remains volatile. A PERMITTED receipt records a policy decision, not confirmed execution. Use synthetic inputs in disposable isolation. DEPLOYMENT.md and THREAT_BOUNDARY.md give the current behavior; the thirteen cases below retain their historical observations through 3.6.4. Other verifier implementations retain their separately documented behavior.

Verify a retained record

Obtain the repository or the website's static sample kit while online. Once the verifier, sample and expected public key are local, the verification command itself needs no network or callback to us. Repository cloning and package installation require network access unless their inputs are already cached:

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-verify CLI agrees on the tested classical corpus as the harness supplies it. npm run conformance:cross-stack (first: npm run build && npm --prefix independent-verifier run build) proves that six v1 verifier configurations, spanning three independent toolchains (JavaScript, Go, and Python, including a pure-stdlib, no-third-party-crypto path), agree on the 54 object-level cases. The five file-parsing verifiers also agree on the 7 raw-byte/file-parse cases (61 total). The in-server engine is library-only, receiving parsed objects rather than raw file bytes, so it does not run the file-parse cases; six configurations do not agree on all 61 and this no longer claims they do. npm run conformance:cross-stack-v2 proves two genuinely independent-language oracles (@noble/JS and CIRCL/Go) agree on the v2 composite corpus. For a source-and-build reproduction (build the package yourself, reproduce the published tarball byte-for-byte, re-run every gate), see the [REVIEWER_GUIDE.md](https://github.com/attestedintelligence/aga-mcp-server/blob/main/REVIEWER_GUIDE.md) (a command-by-command self-service path), [REPRODUCIBILITY.md](https://github.com/attestedintelligence/aga-mcp-server/blob/main/REPRODUCIBILITY.md), and the step-by-step [SKEPTICAL_AUDITOR.md](https://github.com/attestedintelligence/aga-mcp-server/blob/main/SKEPTICAL_AUDITOR.md). Check build provenance for the exact version: registry signatures and SLSA build attestations are different. The documentation-only 3.6.3 release has registry signatures but no SLSA build attestation. See REPRODUCIBILITY.md for the version-specific record.

What This Does

This is built for teams shipping agentic-AI products into financial services and insurance, at the moment a customer's vendor-risk, model-risk, or internal-audit review asks what your agent did and how anyone would know.

Covered tool calls routed through aga-proxy are evaluated against its configured policy. Each recorded decision (PERMITTED or DENIED) takes the form of a signed, hash-linked governance receipt; known issue 7 below describes calls refused without a receipt. aga-proxy also signs the SHA-256 of its policy's canonical JSON into every receipt; see KNOWN_LIMITATIONS.md for what that field binds. Receipts are collected into evidence bundles that anyone holding the published format and the public key can verify offline, with no callback to us.

Signed decisions. Independent verification. Explicit limits.

Scope: a verified bundle proves the *integrity of the receipts present*: each is authentic, correctly ordered, Merkle-included, and (when a key is pinned) provenance-bound. It does not prove 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. See [KNOWN_LIMITATIONS.md](https://github.com/attestedintelligence/aga-mcp-server/blob/main/KNOWN_LIMITATIONS.md) for the full honest boundary, and THREAT_BOUNDARY.md for the per-field detail.

Optional runtime evaluation

Runtime examples identify reference runtime 3.6.6. They are not a production recommendation. Review all known issues and use approved isolation with synthetic inputs before starting a gateway. For a first check, use the static sample and verifier above. Do not start these examples on a workstation containing production credentials or customer data.

# Runtime example only, after the isolation and known-issue review.

npx -y @attested-intelligence/aga-mcp-server@3.6.6

Use with Claude Desktop in the approved evaluation environment

Add to that environment's Claude Desktop MCP config (claude_desktop_config.json):

{

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

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

Persist a synthetic evaluation key before testing restarts

By default the gateway signs with an ephemeral key 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:

Since 3.6.0 this applies to both binaries. aga-proxy reads the same two variables through the same resolver and prints the active public key at startup so you can pin it out of band; --ephemeral makes a throwaway key a stated choice. In 3.5.0 and earlier `aga-proxy` ignored both variables silently; a key you set had no effect and no warning was printed, so evidence from such a proxy is integrity-verifiable but not provenance-pinnable across restarts. See DEPLOYMENT.md, Key custody and verification.

# generate a seed once (32 random bytes, hex)

node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

Provide it via AGA_GATEWAY_KEY, or AGA_GATEWAY_KEY_FILE (a path to the seed). In Claude Desktop, add an env block:

{

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

Keep the seed secret and out of version control; see DEPLOYMENT.md for key handling. A seed in an agent client's environment is not a separate trust domain, and through 3.6.4 the stdio upstream could inherit the key-related variables (historical issue 3). Environment filtering in 3.6.5 does not separate filesystem or host privileges. Same-key restarts do not preserve the in-memory ledger: export and verify before stopping.

MCP Tools (15)

`measure_behavior` is detective-only by default: it observes tool-usage patterns and records a *signed, provable* drift finding, but does not block. Enforcement (drift → quarantine) is opt-in via enforce=true and off by default. Hard governance decisions (PERMITTED/DENIED) are made by the portal/PEP, not the behavioral monitor.

Quick Start: verify a bundle offline

The MCP tool exports a canonical SEP bundle. Acquire the pinned verifier while online, then run the local verifier with a nonempty expected key obtained through a separate trusted channel. The npx command below may contact npm to obtain the package; it is not an air-gapped acquisition command. The downloadable sample kit provides a dependency-free local alternative after download, using Node.js:

# Published verifier CLI. Obtain and aut