audit-ledger-mcp

audit-ledger-mcp

Claude、Cursor、LangGraph、または独自のエージェントをAI Audit Ledgerに接続しましょう。 この MCP サーバーは、設定を1行追加するだけで、改ざんを検知できるログに意思決定を記録、確認、一覧表示するツールをエージェントに提供します。

AI の意思決定を明確に記録する必要があるチーム向けに構築されています。EU AI Act 第12条のログ記録、FCA SS1/23 のモデルリスクに関する証拠、GDPR のデータ最小化に対応します。個人データの生データは送信前にローカルでハッシュ化されるため、台帳に保存されるのはフィンガープリントのみです。

AI Audit Ledger ファミリー。 この MCP サーバーは意思決定を 台帳に書き込み、何が起きたのか、 また記録が変更されたかどうかを証明します。 AI Decision Evidence Hubは 台帳の上位に位置し、読み取り専用です。各軽量な意思決定記録を、どの証拠が存在し、 何が不足しているか、各不足項目の担当者は誰か、現在の準備状況スコアはいくつかを 示すことで、監査ケースファイルに変換します。ファミリー： audit-ledger · audit-ledger-mcp · evidence-hub。

ライブダッシュボードを試す →  ·  この MCP サーバー経由で書き込まれた30件の合成意思決定を検索・検証できます。

LangGraph のワークフローでは、各エージェントのステップ後に record_decision を呼び出します。ライブ台帳に3件の監査イベントが書き込まれ、それぞれを個別に検証できます。

---

概要

MCP 互換のエージェントに4つのツールを公開します。

ツール	機能
record_decision	AI の意思決定を記録します。入力をローカルでハッシュ化してから、台帳に書き込みます。イベント ID を返します。
verify_decision	保存済みの記録を、変更不可能な S3 Object Lock のコピーと照合します。integrity_verified: true/false を返します。
verify_completeness	削除または欠落した記録を検出します。テナントごとの台帳カウンターと実際に存在する行を比較し、欠落しているシーケンス番号を返します。「ログが完全であることを証明できますか？」への回答です。
list_decisions	最近の意思決定を検索します。期間での絞り込みも可能です。API キーによってテナントの範囲に限定されます。

各呼び出しは、デプロイ済み台帳に規制当局の要件を満たす監査記録として保存されます。検索には DynamoDB、変更不可能なコピーには S3 Object Lock の COMPLIANCE モードを使用し、デフォルトの保持期間は7年間です。

---

クイックスタート — 設定不要

npx -y audit-ledger-mcp

これで完了です。環境変数を設定しない場合、サーバーはサンドボックスモードで起動し、ホスト型台帳の共有公開テナントに記録を書き込みます。何もプロビジョニングせずに、record_decision、verify_decision、verify_completeness、list_decisions のすべてのツールを試せます。

サンドボックスモードが有効な場合、stderr に次のバナーが表示されます。

[audit-ledger-mcp] ─────────────── SANDBOX MODE ───────────────
[audit-ledger-mcp] No AUDIT_API_URL configured.
[audit-ledger-mcp] Using the public sandbox at sandbox-public.
[audit-ledger-mcp]   View: https://d2pfirb2397ixy.cloudfront.net
[audit-ledger-mcp] Do NOT write real personal data...

サンドボックスの特性

ホスト	github.com/shahidh68/audit-ledger（同じ AWS デプロイメント）
テナント	sandbox-public（共有、公開）
レート制限	IP ごとに毎分100リクエスト
保持期間	7年間（記録は削除できません）
対象ユーザー	お試し利用者、統合テスト、フレームワークのデモ
対象外	本番データ、顧客の PII、実際のコンプライアンス記録

Claude Desktop に設定なしで接続する

{
  "mcpServers": {
    "audit-ledger-sandbox": {
      "command": "npx",
      "args": ["-y", "audit-ledger-mcp"]
    }
  }
}

Claude Desktop を再起動します。MCP メニューに4つのツールがすぐに表示されます。Claude に「この意思決定を記録して：X を承認すべきですか？」と尋ねて、サンドボックスのダッシュボードに記録が追加される様子を確認してみてください。

---

本番環境へのインストール

実際のワークロードでは、独自の監査台帳をデプロイし、MCP サーバーからその台帳を参照するよう設定してください。

npm install -g audit-ledger-mcp

API URL とテナントキーを設定します（いずれかを設定すると、サンドボックスモードがオフになります）。AUDIT_HMAC_KEY は後方互換性のため技術的には省略可能ですが、強く推奨します。以下の値の上にある注記を参照してください。

export AUDIT_API_URL="https://<api-id>.execute-api.<region>.amazonaws.com/prod"
export AUDIT_WRITE_KEY="<your-tenant-write-key>"
export AUDIT_READ_KEY="<your-tenant-read-key>"

# Strongly recommended. Tenant-held secret used to HMAC PII and prompts
# locally before sending. Generate once, store next to AUDIT_WRITE_KEY:
#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# If unset, the MCP falls back to plain SHA-256 and warns once (back-compat).
export AUDIT_HMAC_KEY="<your-tenant-hmac-secret>"

# Optional
export AUDIT_TIMEOUT_MS=5000        # default 5000
export AUDIT_RETRY_ATTEMPTS=3       # default 3

完全なテンプレートは .env.example にあります。

---

エージェントに接続する

Claude Desktop

claude_desktop_config.json を編集します（macOS：~/Library/Application Support/Claude/claude_desktop_config.json、Windows：%APPDATA%\Claude\claude_desktop_config.json）。

{
  "mcpServers": {
    "audit-ledger": {
      "command": "npx",
      "args": ["-y", "audit-ledger-mcp"],
      "env": {
        "AUDIT_API_URL": "https://<api-id>.execute-api.<region>.amazonaws.com/prod",
        "AUDIT_WRITE_KEY": "<your-tenant-write-key>",
        "AUDIT_READ_KEY": "<your-tenant-read-key>",
        "AUDIT_HMAC_KEY": "<your-tenant-hmac-secret>"
      }
    }
  }
}

AUDIT_HMAC_KEY はテナントのシークレットです。ペイロードが MCP サーバープロセスから送信される前に、PII をローカルでキー付きハッシュにするために使われます。node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" を一度実行して生成し、結果を上記の env ブロックに保存してください。MCP がこの値を送信することはなく、読み取るだけです。

Claude Desktop を再起動します。MCP ツールメニューに「audit-ledger」が表示されます。Claude に 「この決定を記録してください。申請を却下した理由は……」 のように尋ねると、自動的に record_decision が呼び出されます。

Cursor

Cursor の設定 → MCP → サーバーを追加：

{
  "mcpServers": {
    "audit-ledger": {
      "command": "npx",
      "args": ["-y", "audit-ledger-mcp"],
      "env": {
        "AUDIT_API_URL": "https://<api-id>.execute-api.<region>.amazonaws.com/prod",
        "AUDIT_WRITE_KEY": "<your-tenant-write-key>",
        "AUDIT_READ_KEY": "<your-tenant-read-key>",
        "AUDIT_HMAC_KEY": "<your-tenant-hmac-secret>"
      }
    }
  }
}

LangGraph（Python）

langchain-mcp-adapters を使用します。

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_anthropic import ChatAnthropic
import os

client = MultiServerMCPClient({
    "audit-ledger": {
        "command": "npx",
        "args": ["-y", "audit-ledger-mcp"],
        "transport": "stdio",
        "env": {
            "AUDIT_API_URL":   os.environ["AUDIT_API_URL"],
            "AUDIT_WRITE_KEY": os.environ["AUDIT_WRITE_KEY"],
            "AUDIT_READ_KEY":  os.environ["AUDIT_READ_KEY"],
            "AUDIT_HMAC_KEY":  os.environ["AUDIT_HMAC_KEY"],
        },
    }
})

tools = await client.get_tools()
agent = create_react_agent(
    ChatAnthropic(model="claude-sonnet-4-7-20251022"),
    tools,
)

# The agent can now call record_decision, verify_decision, verify_completeness, list_decisions
result = await agent.ainvoke({
    "messages": [{"role": "user", "content": "Triage this loan application…"}]
})

カスタムクライアント（生の MCP）

AUDIT_API_URL=... AUDIT_WRITE_KEY=... AUDIT_READ_KEY=... AUDIT_HMAC_KEY=... npx -y audit-ledger-mcp

サーバーは stdio 経由で MCP を通信します。MCP 仕様に従って、initialize、tools/list、tools/call リクエストを送信してください。

---

record_decision 呼び出しの流れ

Agent                  audit-ledger-mcp                  AWS (your ledger)
  |                          |                                 |
  |--- record_decision ----->|                                 |
  |   raw_user_input         | (hash locally — no PII over     |
  |   raw_system_prompt      |  the wire from this point)      |
  |   decision_output        |                                 |
  |   human_in_loop          |                                 |
  |                          |--- HTTPS POST /audit/events --->|
  |                          |    {hashes + decision +         |
  |                          |     x-api-key}                  |
  |                          |                                 |
  |                          |<--- 202 Accepted ---------------|
  |                          |    { event_id, ... }            |
  |<--- event_id ------------|                                 |
  |     recorded_at          |                                 |
  |     note                 |                                 |

AWS 側でのストレージへの保存は、SQS → Processor Lambda → DynamoDB + S3 Object Lock を通じて非同期に行われます。全体の流れについては、メインリポジトリの ARCHITECTURE.md を参照してください。

---

ツールリファレンス

record_decision

AI の決定を台帳に記録します。

パラメーター	型	必須	備考
model_version	string	はい	例："claude-sonnet-4-7-20251022"
raw_system_prompt	string	はい	ローカルでハッシュ化されます
raw_user_input	string	はい	ローカルでハッシュ化されます
ai_decision_output	object	はい	そのまま保存されます。生の PII を含めてはいけません
human_in_loop	boolean	はい	EU AI Act 第 14 条で重要です
event_id	uuid v4	いいえ	省略した場合は自動生成されます
timestamp	ISO 8601	いいえ	既定値は現在時刻です

verify_decision

保存済みレコードが改ざんされていないか確認します。

パラメーター	型	必須	備考
event_id	uuid v4	はい	検証するレコードの ID

DynamoDB レコード、S3 レコード、および integrity_verified: true/false を返します。

verify_completeness

レコードの欠落を検出します。verify_decision と対になるツールです。前者は存在するレコードが改ざんされていないことを証明し、こちらはレコードが削除されていないことを証明します。

パラメーター	型	必須	備考
from	integer	いいえ	sequence_no の下限（この値を含みます）。既定値は 1 です。
to	integer	いいえ	sequence_no の上限（この値を含みます）。既定値はテナントの現在のカウンターです。
tenant_id	string	いいえ	管理者読み取りキーを使う場合にのみ必須です。それ以外の場合は無視されます。

指定した範囲、予想件数と検出件数、欠落しているシーケンス番号の一覧、および人が読める形式の注記を返します。

{
  "tenant_id": "acme-prod",
  "range": { "from": 1, "to": 142 },
  "expected_count": 142,
  "found_count": 140,
  "missing": [47, 91],
  "note": "Found 2 missing sequence number(s) in range. Each gap represents a deleted, lost, or never-written record. Cross-check against burned_sequence log entries before treating as a deletion."
}

list_decisions

呼び出し元のテナントの最近の決定を一覧表示します。

パラメーター	型	必須	備考
from	ISO 8601	いいえ	既定値は 7 日前です
to	ISO 8601	いいえ	既定値は現在時刻です
limit	integer 1–500	いいえ	既定値は 100 です

---

セキュリティ

• PII のハッシュ化は台帳ではなく、このプロセス内で行われます。 UTF-8 に対する HMAC-SHA256 を使用し、環境に設定した AUDIT_HMAC_KEY を鍵として使います。鍵がプロセスの外に出ることはなく、送信されるのは 64 文字の 16 進ダイジェストのみです。エントロピーの低い値（氏名、メールアドレス）に対する通常の SHA-256 は数秒で総当たり攻撃でき、ICO／EDPB のガイダンスでは依然として個人データに該当するため、新規インストールでは鍵付きの方式がデフォルトです。後方互換性のため、AUDIT_HMAC_KEY が設定されていない場合、MCP は通常の SHA-256 にフォールバックし、stderr に一度だけ非推奨警告を出力します。既存のセットアップは変更なく動作し続けます。
• API キーがログに記録されることはありません。 API キーは環境変数から取得され、x-api-key ヘッダーで渡されます。エージェントに返されたり、ディスクに書き込まれたりすることはありません。
• キーの名前空間は 2 種類です。 書き込みキーでは読み取りできず、読み取りキーでは書き込みできません。書き込みキーが漏えいしてもデータを持ち出すことはできず、読み取りキーが漏えいしても偽のレコードを仕込むことはできません。
• エラーは HTTP ステータスをそのまま保持して伝達されます。 レート制限、無効なキー、検証エラーはエージェントに通知されるため、盲目的に再試行せず、適切に対応できます。

---

これは何ではないか

• 法律上の助言ではありません。 これは監査証拠を生成するインフラストラクチャです。その証拠が特定の規制上の義務を満たすかどうかは、法務チームに確認してください。
• モデルリスク監査の代わりにはなりません。 AI が何をしたかを記録しますが、それが正しかったかどうかは記録しません。
• バイアスや公平性のテストツールではありません。 すでに行っているテストの基盤となる監査レイヤーです。

---

関連プロジェクト：AI Decision Evidence Hub

この MCP サーバーは、決定を台帳（何が起きたかを記録する改ざん不可能な記録）に書き込みます。台帳の上位にある読み取り専用の作業環境が AI Decision Evidence Hub です。監査人が次に尋ねる問い、つまり「決定は記録されていますが、レビューするのに十分な証拠がそろっていますか？」に答えます。

記録された決定ごとに、次の情報を生成します。

• 9 つの証拠カテゴリ（モデル、データ、ポリシー、人間によるレビュー、監視、プロンプト、整合性、保持、決定）にわたる監査対応度スコア（0～100）；
• 存在する証拠と不足している証拠の正確な内容、および想定される各ギャップの担当者；
• 印刷、PDF としての保存、または JSON としてのダウンロードが可能な、決定ごとの監査パック；
• ダッシュボード（台帳のダッシュボードと相互リンク）に加え、静的な証拠を自動入力するマニフェストベースのリゾルバー。

未解決のギャップがあるのは正常です。台帳は決定の記録を小さく保ち、改ざんを検知できるようにします。Evidence Hub は、その決定を監査可能な状態にするために必要な追加証拠を示します。API 経由で台帳を読み取り、レコードを変更することはありません。AWS 上のサーバーレス構成です（Lambda + DynamoDB）。Customer Guide と Admin Runbook をご覧ください。

関連プロジェクト： audit-ledger（何が起きたか） · audit-ledger-mcp（このサーバー — エージェントが決定を書き込む方法） · evidence-hub（監査対応度）。

---

開発

git clone https://github.com/shahidh68/audit-ledger-mcp.git
cd audit-ledger-mcp
npm install
npm run build
npm test

このサーバーは TypeScript で実装されており、Node 20 以降、ESM、stdio トランスポートを使用し、@modelcontextprotocol/sdk を利用しています。

---

関連項目

• shahidh68/audit-ledger — このサーバーが接続する AWS インフラストラクチャです。CDK スタック、Python および Node の SDK、コンプライアンスダッシュボード、アーキテクチャの全ドキュメントが含まれます。
• shahidh68/evidence-hub — 台帳の上位にある監査作業環境です。各決定の証拠を評価し、未解決のギャップを想定される追加作業として扱い、印刷・ダウンロード可能な監査パックを生成します。(Customer Guide · Admin Runbook)

---

ライセンス

Apache License 2.0 — LICENSE をご覧ください。

特許の許諾は意図的に含めています。コンプライアンスインフラは企業の法務審査に隣接する領域であり、明示的な許諾が重要です。

---

作者

Shahid が開発しました。英国の規制対象フィンテック企業におけるプリンシパルAIエンジニアおよびAIエンジニアリング責任者の役職、ならびにパートタイムのアドバイザリー業務に対応しています。