AGA - Attested Governance Artifacts 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 (a command-by-command self-service path), REPRODUCIBILITY.md, and the step-by-step 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 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": "<your-64-hex-seed>" }
    }
  }
}

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)

Category	Tools
Identity	get_server_info, get_portal_state
Lifecycle	init_chain, attest_subject, revoke_artifact
Measurement & decision	measure_integrity, measure_behavior, verify_chain
Evidence	generate_evidence_bundle, verify_bundle_offline
Privacy	request_claim, list_claims
Delegation	delegate_to_subagent
Audit	get_receipts, get_chain_events

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 authenticate the expected key outside the bundle before running.
npx -y @attested-intelligence/aga-verify@2.2.3 evidence-bundle.json --pubkey <gateway-public-key>

# Or, from a clone of this repo, the zero-dependency reference verifier (Node 18+) checks its supported profile; parser/pin behavior can differ:
node aga-receipt-spec/verify/verify-sep.mjs evidence-bundle.json --pubkey <gateway-public-key>

The published @attested-intelligence/aga-verify CLI is the shipped path (the older forgeable 1.0.0 is deprecated); the reference verify-sep.mjs provides another implementation from a repo clone; verdict agreement is scoped to tested cases, not all input bytes. Without --pubkey you get an integrity-only result (issuerVerified=false); supply a nonempty expected key from a separate trusted channel to authenticate that signing key; the mapping to an organization depends on that channel. Version 2.2.3 refuses missing or malformed supplied keys, repeated or unknown options and ambiguous file/sample selection with a usage error, exit 2. Versions through 2.2.2 treated a trailing --pubkey as absent. The 2.2.3 library API refuses malformed supplied expected keys; runtime 3.6.5 separately adopts fail-closed malformed expected-key handling in its embedded verifier. See THREAT_BOUNDARY.md, Known residual risks. A hosted browser verifier is linked under Links.

The reference §6 algorithm is implemented in three languages: JavaScript (aga-receipt-spec/verify/verify-sep.mjs), Go (verify.go, stdlib crypto/ed25519), and Python (verify.py, pure-stdlib RFC-8032 Ed25519). A cross-stack harness (npm run conformance:cross-stack; first: npm run build && npm --prefix independent-verifier run build) proves all three, plus the in-server engine and aga-verify, agree on the published canonical cases as the harness feeds them (object cases are re-serialized; raw-byte cases are separate). Outside that corpus, the implementations differ, including some parser and pin semantics. The v2 composite profile (ML-DSA-65+Ed25519-SHA256-JCS) is held to the same bar by a second harness (npm run conformance:cross-stack-v2): a @noble/JavaScript engine and a CIRCL/Go oracle, two genuinely independent toolchains, render identical verdicts on the pinned v2 corpus, and the reference v1 verifier (verify-sep.mjs/verify.py/verify.go) returns UNSUPPORTED_PROFILE (exit 3) on a v2 bundle, signalling "profile not implemented" rather than a misleading "invalid". (The published aga-verify CLI does not implement this profile trichotomy: on a v2 bundle it returns FAILED (exit 1). Use exit 3 as the unsupported-profile signal only with the reference verifiers.)

Check-name mapping across implementations

The JS reference verifier and the Python SDK (aga-governance) decompose the same seven-check verification differently. Overall verdicts and exit codes agree on all 61 conformance-corpus cases as the cross-stack harness feeds them (object-level cases re-serialized, so float spellings arrive as integers; measured on aga-governance 0.3.2 on 2026-09-25) and on the 10 cells re-proven 2026-07-01 (pristine and tampered bundles with unpinned, correct and wrong keys). On the literal file bytes of the corpus's float-spelled leaf_index case (0.0), aga-governance 0.3.2 reports FAILED where the JS reference, aga-verify, Go and Python reference verifiers report VERIFIED; see https://attestedintelligence.com/spec. The sub-check that reports a given tamper can differ:

JS reference check	Python result field	What it covers
structural	algorithm_valid + parts of bundle_consistent	algorithm id, key well-formedness, receipt/proof counts
receipt_signatures	receipt_signatures_valid	Ed25519 over canonical receipt bytes
chain_and_ordering	chain_integrity_valid	prev-leaf linkage, canonical non-decreasing timestamps (ids are not ordering fields and are not checked)
merkle_and_bijection	merkle_proofs_valid	leaf recompute, single-root walk, index bijection
signed_checkpoint	checkpoint_valid	gateway-signed root + count + chain-head binding
envelope_consistency	envelope_consistent	envelope gateway_id, generated_at, merkle_root vs signed content (bundle_id, schema_version, the envelope policy_reference and offline_capable are unsigned and unchecked)
gateway_key_match (with --pubkey)	gateway_key_match / provenance	pinned issuer key

Known decomposition difference: the JS reference recomputes every Merkle leaf from full receipt content, so a receipt-signature tamper also fails merkle_and_bijection; the Python verifier surfaces the same tamper in receipt_signatures_valid, chain_integrity_valid, and bundle_consistent while its merkle_proofs_valid can remain true. Neither is looser: the bundle fails in both stacks, exit 1. A --pubkey KEY that is not 64 lowercase hex characters is a usage error (exit 2) in the JS reference, aga-verify and the Python SDK, and a 64-hex pin that is not a valid curve point is honored, fails to match, and fails the bundle (exit 1). In the September 25 measurements, --pubkey=KEY was ignored by the JS reference, aga-verify through 2.2.2, verify.go and v2/verify-v2.go, and by verify.py when it follows the bundle path (integrity only, exit 0), and read by the Python SDK. Other verifiers differ as well. Through runtime 3.6.4, the in-server engine (the package's ./verify export, which verify_bundle_offline calls) treats a pin that is not a well-formed key for the bundle's profile (for a v1 bundle, a small-order point or a non-canonical encoding) as no pin, and returns VERIFIED with pinned: false. v2/verify-v2.go does the same and prints integrity only; no key pinned (exit 0). A 64-hex value that is not a curve point counts as well-formed, so both take it as a pin and the bundle fails. The Go and Python reference verifiers in aga-receipt-spec/verify/ treat a pin that is not 64 lowercase hex the same way and print integrity only; no key pinned (exit 0). Read pinned before taking a VERIFIED as provenance; in CI, pass the key after a space and check that the output says provenance verified. A --pubkey given with no value is also treated as no pin (exit 0, integrity only) by aga-verify through 2.2.2, verify-sep.mjs, verify.py, verify.go and v2/verify-v2.go, and is a usage error in the Python SDK. Other differences concern the bundle rather than the pin, and https://attestedintelligence.com/security lists the ones measured, including which algorithm labels each verifier leaves unchecked; outside the conformance corpus the verifiers differ in both directions. Two examples, where the failing side fails closed: a proof leaf_index spelled as an integral float (1.0) reports FAILED in aga-governance 0.3.2 and VERIFIED in the others, and object keys outside the Basic Multilingual Plane (possible only in a non-string field value, which no shipped producer emits) sort differently in verify.py, verify.go, v2/verify-v2.go and aga-governance than in the JavaScript verifiers, so such a bundle reports VERIFIED in JavaScript and FAILED in Go and Python. These parser and cross-language differences remain. Standalone verifier 2.2.3 separately fixes expected-key handling: equals-form options are refused rather than ignored, missing values are usage errors, and malformed supplied API keys fail verification.

How It Works

AI Agent                  AGA Proxy                      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]

MCP Governance Proxy

Run AGA as a proxy in front of an MCP server that it starts as a stdio child process (the default stdio transport), or one it reaches with a plain JSON-RPC POST (--upstream-url; no Streamable HTTP session or SSE handling). The proxy's agent port speaks newline-delimited JSON-RPC 2.0 over raw TCP, not stdio or Streamable HTTP. A stdio MCP client needs a relay you provide (a few lines that pipe stdin to the port and the port to stdout); none ships. A scripted client can speak that framing directly. Every tools/call request with a non-empty string tool name and arguments the proxy can canonicalize is evaluated against the policy and produces a signed receipt, except the calls that known issue 7 below describes as refused without one. Other methods that are not benign are forwarded with a signed passthrough receipt and are not policy-evaluated, and benign protocol methods (initialize, initialized, ping, tools/list, prompts/list, resources/list, resources/templates/list, logging/setLevel, completion/complete and notifications/*) produce no receipt (THREAT_BOUNDARY.md, Known residual risks). Read the known issues below before you expose the port.

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

permissive records each tools/call it evaluates (known issue 7 describes the exceptions) and denies nothing on policy grounds. standard and restrictive allow only generic example tool names, so they deny every tool this example server exposes; to permit some of your server's tools and deny the rest, pass a --policy file that names them.

Exporting the evidence bundle from a running proxy

The proxy records receipts in its own process and keeps the SEP ledger in memory. To make that live ledger reachable from a separate shell, aga-proxy start opens a loopback-only control channel: an HTTP listener bound to 127.0.0.1 (never a routable interface), on its own port (default 18801, 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. It does not check a request's Host or Origin header, so a web page in a browser on the same host can read its responses through DNS rebinding unless the browser blocks it (known issue 12). The proxy writes the chosen control port to ~/.aga-proxy/control.json alongside proxy.pid.

A separate aga-proxy export invocation 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@3.6.6 aga-proxy start \
  --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp/test" --profile permissive

# (First, drive at least one tools/call through the proxy from your MCP client; an empty
#  ledger has no receipts to checkpoint, and the export reports there is nothing to export.)