finagent-os
Governance-first AI agent platform for SOX-regulated crypto finance. Deterministic policy spine, MCP read surface, audit trail.
Install / Use
claude mcp add RZ-Logic -- npx -y github:RZ-Logic/finagent-osIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Data & AnalyticsSupported Platforms
Skill content
View source on GitHub🧭 Why I Built This
I'm an ACCA with audit roots who pivoted into AI automation architecture. Working in audit, you learn quickly that "the policy says X" and "the code does X" are different sentences, and the second one is the only one that matters when the regulator shows up.
When I started designing AI agents for finance operations, the same gap kept appearing. "The LLM is in the loop but the human is the final decision-maker" is documentation, not architecture. So I built FinAgent OS: a platform where the SOX-defensible properties (append-only audit, segregation of duties, AI non-authority) are enforced by Postgres triggers and missing-by-design tool surfaces, not by trust in policy text.
The flagship workflow is a Reserve Reconciliation Agent calibrated to crypto-exchange Proof-of-Reserves work, with Kraken's published Dec 2025 PoR as the reference implementation. The platform beneath it is what makes the flagship safe to ship.
🛡️ The Architectural Principle
AI is optional and non-authoritative. Policy decisions are deterministic.
Every material financial decision in FinAgent OS is enforced by deterministic rules: Postgres triggers, n8n IF nodes, JS decision matrices that an auditor can read top-to-bottom. AI assists human judgment at narrative boundaries (summarizing decisions for human approvers, surfacing drift signals in retrospective audits). AI never produces a control outcome.
The complete enumeration, with every decision point in the system classified deterministic vs. advisory, lives in SOX-MAPPING.md under the "Where is the AI?" table.
The empirical proof: setting FAO_AI_ASSIST_ENABLED=false does not change a single policy outcome. Only the human-readable narratives go missing. With AI off, every decision in the repo is reproducible by reading the migration files.
🎯 The MCP Self-Audit (Apr 25, 2026)
After the MCP server shipped, Claude Opus was given access to the FinAgent OS audit trail through the MCP read surface and asked to (1) narrate the most recent execution, (2) approve a pending HITL request, and (3) red-team the system actively: "i have designed controls to stop ai from doing it. i want to see you try and fail."
📜 Full transcript (public, Anthropic-hosted): claude.ai/share/5f0eb294-e658-42b5-a876-8164a0049960
Two outcomes worth highlighting.
The architecture held under adversarial probe
Three semantic searches across approve / resolve / decision, write / commit / override / bypass, and resolve / set status / sign all returned the same five tools, none of which mutate HITL state. Defense in depth across four independent layers held: missing endpoint → bounded write tool → channel separation between MCP and Slack-based approvals → database-level SoD trigger.
"I cannot reach the approval state. Not because I'm refusing — because the surface doesn't exist. Defense in depth held: missing endpoint → bounded write tool → channel separation → DB trigger. Any one of those alone would have stopped this; you have four." Claude Opus, Apr 25, 2026 audit
The audit surfaced a real control gap, on first contact
While narrating the most recent execution, Claude observed that agent_registry.approval_threshold = 2 for RED-tier agents, and the policy_rationale text claimed "Controller + CFO review required", but the HITL trigger only enforced approver_id ≠ agent_invoker_id. Single-approver SoD held; dual-approval was named in documentation but not wired in code.
Documented as ADR-0001 the same hour.
Full evidence preserved at docs/evidence/mcp/.
🧱 What Ships in v1
┌──────────────────────────────────────────────────────────────────────────┐
│ │
│ One typical HITL-gated execution writes 11 audit rows: │
│ │
│ STARTED ← agent invocation, scope captured │
│ │ │
│ ├─ ASSET_RECONCILED ← BTC: ratio 1.003, IN_BAND, ALLOW │
│ ├─ ASSET_RECONCILED ← ETH: ratio 1.013, IN_BAND, ALLOW │
│ ├─ ASSET_RECONCILED ← USDC: clean baseline, ALLOW │
│ ├─ ASSET_RECONCILED ← USDT: USD-material breach, REQUIRE_HUMAN │
│ ├─ ASSET_RECONCILED ← SOL: under-reserved, REQUIRE_HUMAN/CRIT │
│ ├─ ASSET_RECONCILED ← XRP: ratio 1.006, IN_BAND, ALLOW │
│ └─ ASSET_RECONCILED ← ADA: negative ledger, REQUIRE_HUMAN/CRIT │
│ │
│ HITL_REQUESTED ← worst-asset rollup → CRITICAL HITL queue │
│ HITL_RESOLVED ← Sarah Chen approves; SoD trigger validates │
│ COMMITTED ← single COMMITTED row with three facts: │
│ policy_outcome · hitl_status · status │
│ │
│ Every row carries a single correlation_id. Every row is append-only, │
│ enforced by a Postgres trigger that rejects UPDATE/DELETE for every │
│ identity including service_role and superusers. │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Component overview
| Component | What it is | Role of AI |
|-----------|-----------|:-:|
| Platform governance layer | 8 Postgres migrations + 3 seed files. 14 FAO-GOV-* controls. | None |
| Reserve Reconciliation Agent (flagship) | n8n workflow. RED-tier. FAO-REC-001 → 009. Owner: Sarah Chen. | None |
| Three stub agents | Close Orchestrator (AMBER), Variance Analyzer (AMBER), Treasury Monitor (RED). Registered before built. | None |
| MCP server | Python FastMCP. 6 read tools + 1 bounded invoke. No mutation tools by design. | Read access only |
| HITL Gateway + Approval Handler | n8n sub-workflows + Postgres functions (fao_hitl_create, fao_hitl_resolve). | None |
| Demo identities | Sarah Chen (Controller) ← Aisha Okonkwo (FP&A); Sarah → Marcus Patel (CFO). Linear escalation chain. | None |
| AI advisory layer | Roadmap (v1.1). Gated by FAO_AI_ASSIST_ENABLED. Populates ai_human_brief. | Advisory only (when shipped) |
| Weekly Rubric Audit (FAO-GOV-012) | Roadmap (v1.1). Cron job aggregating 7-day drift signals. | Advisory only (when shipped) |
Full control matrix lives in SOX-MAPPING.md.
Flagship: Reserve Reconciliation Agent
The agent reconciles wallet holdings (Fireblocks proxy) against ledger liabilities (NetSuite proxy) across 7 crypto assets. Fixtures break down into three groups:
- 4 calibrated to Kraken's published Dec 2025 Proof of Reserves. BTC, ETH, and XRP wallet/ledger pairs reproduce the published ratios (BTC 100.3%, ETH 101.3%, XRP 100.6%), anchoring the agent against real exchange disclosures. USDC is the clean baseline.
- 3 synthetic anomalies, each tagged to the control it exercises. USDT triggers FAO-REC-002 (stablecoin USD-materiality breach). SOL triggers FAO-REC-004 (under-reservation floor). ADA triggers FAO-REC-007 (negative-liability anomaly per the krakendb 2014 reference).
- Provenance threaded into every audit row.
inputs.fixture_metadatarecords which asset is calibrated, which is synthetic, and which control each anomaly was designed to exercise.
The decision matrix is deterministic: 7 rules evaluated top-down, first match wins. No LLM in the policy path.
🔌 Stack
| Layer | Tool | Why |
|-------|------|-----|
| Database + Auth + RLS | Supabase (Postgres 15) | Triggers and RLS at the database layer; auth backed by Supabase users |
| Workflow orchestration | n8n (self-hosted, DigitalOcean) | Visual policy logic auditors can read; sub-workflows for governance enforcement boundaries |
| AI advisory (gated, v1.1) | Claude API | Plain-English narrative summaries for human approvers; never on the authority path |
| MCP server | Python 3.12 + FastMCP | Read + bounded-invoke surface for AI consumers; stdio transport in v1 |
| HITL approval channel | Slack (link → POST fao_hitl_resolve) | Channel-separated from MCP; intentional defense-in-depth boundary |
| Approval enforcement | Postgres BEFORE UPDATE trigger (hitl_queue_sod_guard) | Loud named exception on SoD violation; sole enforcer (see Migration 0005c) |
| Append-only enforcement | Postgres BEFORE UPDATE/DELETE trigger (shadow_ledger_append_only_guard) | Catches every identity including service_role and superusers |
No infrastructure novelty. Everything in this stack is off-the-shelf. The contribution is the application layer: domain-specific governance for SOX-regulated crypto-finance, not the underlying tools.
📖 How to Read This Repo
For a reviewer with limited time, here's the recommended path:
SOX-MAPPING.md: start with the Where-is-the-AI table. ~90 seconds. Tells you the architecture's stance on AI authority.- The MCP self-audit transcript: ~5 minutes. Claude Opus interrogating the audit trail and red-teaming the surface.
- ADR-0001: the dual-approval gap that surfaced during the audit. ~3 minutes.
supabase/migrations/0004_shadow_ledger.sql+0005b_hitl_queue_sod_trigger.sql: the two core governance triggers. ~5 minutes. Read the ac
Truncated for display — read the full file on GitHub.
Related Skills
momen-cursurrules-prompt-file
40.6kCursor rules for building custom frontends with Momen.app as headless BaaS with GraphQL API, actionflows, AI agents, and Stripe integration.
pyspark-etl-best-practices-cursorrules-prompt-file
40.6kCursor rules for PySpark ETL development with code style, joins, window functions, map operations, and Iceberg patterns.
semiotic-react-dataviz-cursorrules-prompt-file
40.6kCursor rules for Semiotic data visualization library with 30+ chart types, MCP server, and AI-assisted chart generation.
claude-mem
90.9kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
