audit-ledger-mcp

Tamper-evident audit logging for AI decisions. Three tools (record_decision, verify_decision, list_decisions) write to a regulator-grade ledger built on AWS S3 Object Lock with 7-year retention. Designed for EU AI Act Article 12 and FCA SS1/23 evidence requirements. Try zero-config: `npx audit-ledger-mcp` boots in sandbox mode against a public hosted tenant.

GitHub

Experimente este MCPPatrocinado

Documentação

audit-ledger-mcp

Conecte o Claude, Cursor, LangGraph ou seu próprio agente ao AI Audit Ledger. Este servidor MCP dá a um agente as ferramentas para registrar, verificar e listar decisões em um log à prova de adulteração com uma linha de configuração.

Ele é construído para equipes que precisam de um registro claro das decisões de IA: registro do Artigo 12 da Lei de IA da UE, evidências de risco de modelo FCA SS1/23 e minimização de dados GDPR. Dados pessoais brutos são hashados localmente antes de qualquer envio, então o ledger só vê impressões digitais.

A família AI Audit Ledger. Este servidor MCP escreve decisões no ledger, que prova o que aconteceu e se o registro foi alterado. O AI Decision Evidence Hub fica acima do ledger, somente leitura. Ele transforma cada registro de decisão leve em um arquivo de caso de auditoria, mostrando quais evidências estão presentes, o que ainda está faltando, quem é responsável por cada lacuna e a pontuação atual de prontidão. Família: audit-ledger · audit-ledger-mcp · evidence-hub.

Experimente o dashboard ao vivo → · 30 decisões sintéticas escritas via este servidor MCP, consultáveis e verificáveis.

LangGraph agents using audit-ledger-mcp — triage, risk, and human-in-the-loop each calling record_decision

Um fluxo de trabalho LangGraph chama record_decision após cada etapa do agente. Três eventos de auditoria escritos no ledger ao vivo; cada um verificável de forma independente.

O que ele faz

Expõe quatro ferramentas para qualquer agente compatível com MCP:

Ferramenta	O que faz
`record_decision`	Registra uma decisão de IA. Faz hash das entradas localmente e depois grava no ledger. Retorna um ID de evento.
`verify_decision`	Verifica um registro armazenado contra a cópia imutável do S3 Object Lock. Retorna `integrity_verified: true/false`.
`verify_completeness`	Detecta registros excluídos ou ausentes. Compara o contador por locatário do ledger com as linhas realmente presentes e retorna os números de sequência que estão faltando. A resposta para "você consegue provar que o log está completo?"
`list_decisions`	Consulta decisões recentes, opcionalmente filtradas por janela de tempo. Escopo por locatário via chave de API.

Cada chamada termina como um registro de auditoria de nível regulatório no seu ledger implantado — DynamoDB para consulta, S3 Object Lock em modo COMPLIANCE para a cópia imutável, retenção de 7 anos por padrão.

Início rápido — configuração zero

npx -y audit-ledger-mcp

É isso. Sem variáveis de ambiente, o servidor inicia em modo sandbox e grava registros em um locatário público compartilhado em um ledger hospedado. Você pode experimentar todas as ferramentas — record_decision, verify_decision, verify_completeness, list_decisions — sem provisionar nada.

Quando o modo sandbox está ativo, você verá um banner no 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...

Propriedades do sandbox


Hospedado por	github.com/shahidh68/audit-ledger (mesma implantação AWS)
Locatário	`sandbox-public` (compartilhado, público)
Limite de taxa	100 requisições/minuto por IP
Retenção	7 anos (registros não podem ser excluídos)
Público-alvo	Curiosos, testes de integração, demonstrações de frameworks
NÃO para	Dados de produção, PII de clientes, registros reais de conformidade

Conecte ao Claude Desktop com configuração zero

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

Reinicie o Claude Desktop. As quatro ferramentas aparecem no menu MCP imediatamente. Tente pedir ao Claude para "registrar esta decisão: X deve ser aprovado?" e veja um registro chegar no dashboard do sandbox.

Instalação em produção

Para cargas de trabalho reais, implante seu próprio ledger de auditoria e aponte o servidor MCP para ele:

npm install -g audit-ledger-mcp

Configure com a URL da API e suas chaves de locatário (qualquer uma delas definida desativa o modo sandbox). AUDIT_HMAC_KEY é tecnicamente opcional para compatibilidade reversa, mas fortemente recomendado — veja a nota acima do valor abaixo:

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

O modelo completo está em .env.example.

Conecte a um agente

Claude Desktop

Edite seu 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 é o segredo do locatário usado para hash com chave de PII localmente antes que qualquer carga útil saia do processo do servidor MCP. Gere uma vez com node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" e armazene o resultado no bloco env acima. O MCP nunca transmite esse valor, apenas o lê.

Reinicie o Claude Desktop. Você verá "audit-ledger" no menu de ferramentas MCP. Peça ao Claude algo como "Registre esta decisão: recusei a aplicação porque…" e veja-o chamar record_decision automaticamente.

Cursor

Nas configurações do Cursor → MCP → adicionar servidor:

{
  "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)

Usando 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…"}]
})

Cliente personalizado (MCP bruto)

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

O servidor fala MCP via stdio. Envie requisições initialize, tools/list e tools/call de acordo com a especificação MCP.

Como um fluxo de chamada `record_decision` funciona

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                 |                                 |

O armazenamento no lado AWS acontece de forma assíncrona via SQS → Processor Lambda → DynamoDB + S3 Object Lock. Veja o ARCHITECTURE.md do repositório principal para o caminho completo.

Referência de ferramentas

`record_decision`

Registra uma decisão de IA no ledger.

Parâmetro	Tipo	Obrigatório	Notas
`model_version`	string	Sim	ex.: `"claude-sonnet-4-7-20251022"`
`raw_system_prompt`	string	Sim	Hash local
`raw_user_input`	string	Sim	Hash local
`ai_decision_output`	objeto	Sim	Armazenado literalmente — não deve conter PII bruto
`human_in_loop`	booleano	Sim	Crítico para o Artigo 14 da Lei de IA da UE
`event_id`	uuid v4	Não	Gerado automaticamente se omitido
`timestamp`	ISO 8601	Não	Padrão: agora

`verify_decision`

Verificação de adulteração de um registro armazenado.

Parâmetro	Tipo	Obrigatório	Notas
`event_id`	uuid v4	Sim	O ID do registro a verificar

Retorna o registro do DynamoDB, o registro do S3 e integrity_verified: true/false.

`verify_completeness`

Detecta registros ausentes. Ferramenta irmã do verify_decision: este prova que um registro existente não foi alterado; este prova que nenhum registro foi excluído.

Parâmetro	Tipo	Obrigatório	Notas
`from`	inteiro	Não	Limite inferior inclusivo em sequence_no. Padrão: 1.
`to`	inteiro	Não	Limite superior inclusivo em sequence_no. Padrão: contador atual do locatário.
`tenant_id`	string	Não	Obrigatório apenas com a chave de leitura de administrador; ignorado caso contrário.

Retorna o intervalo solicitado, a contagem esperada vs. encontrada, a lista de números de sequência ausentes e uma nota legível.

{
  "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`

Lista decisões recentes para o locatário chamador.

Parâmetro	Tipo	Obrigatório	Notas
`from`	ISO 8601	Não	Padrão: 7 dias atrás
`to`	ISO 8601	Não	Padrão: agora
`limit`	inteiro 1–500	Não	Padrão: 100

Segurança

O hash de PII acontece neste processo, não no ledger. HMAC-SHA256 sobre UTF-8, com chave baseada no AUDIT_HMAC_KEY que você define no seu ambiente. A chave nunca sai do seu processo; apenas o digest hex de 64 caracteres é enviado. SHA-256 simples de valores de baixa entropia (nomes, e-mails) é quebrável por força bruta em segundos e, sob a orientação ICO/EDPB, ainda conta como dados pessoais — é por isso que a versão com chave é o padrão para novas instalações. Para compatibilidade reversa, se AUDIT_HMAC_KEY não estiver definido, o MCP usa SHA-256 simples e registra um aviso único de depreciação no stderr; configurações existentes continuam funcionando sem alterações.
Chaves de API nunca são registradas. Elas vêm de variáveis de ambiente, são passadas no cabeçalho x-api-key e nunca são ecoadas de volta ao agente ou gravadas em disco.
Dois namespaces de chaves. Chaves de escrita não podem ler; chaves de leitura não podem escrever. Uma chave de escrita vazada não pode exfiltrar dados; uma chave de leitura vazada não pode inserir registros falsos.
Erros são propagados com passagem de status HTTP. Limite de taxa, chave inválida e erros de validação aparecem para o agente para que ele possa reagir adequadamente em vez de tentar novamente às cegas.

O que isto não é

Não é aconselhamento jurídico. É infraestrutura que produz evidências de auditoria. Se essa evidência satisfaz qualquer obrigação regulatória específica é uma questão para sua equipe jurídica.
Não substitui uma auditoria de risco de modelo. Registra o que a IA fez, não se estava certa.
Não é uma ferramenta de teste de viés ou justiça. É a camada de auditoria abaixo de qualquer teste que você já faz.

Complemento: AI Decision Evidence Hub

Este servidor MCP escreve decisões no ledger — o registro imutável do que aconteceu. O AI Decision Evidence Hub é a bancada somente leitura acima do ledger. Ele responde à próxima pergunta que um auditor faz: a decisão está registrada, mas a evidência está completa o suficiente para revisão?

Para cada decisão registrada, ele produz:

uma pontuação de prontidão de auditoria (0–100) em nove categorias de evidência (modelo, dados, política, revisão humana, monitoramento, prompt, integridade, retenção, decisão);
exatamente quais evidências estão presentes vs. ausentes, e quem é responsável por cada lacuna esperada;
um pacote de auditoria por decisão que pode ser impresso, salvo como PDF ou baixado como JSON;
um dashboard (com links cruzados com o do ledger), além de um resolvedor baseado em manifesto que preenche automaticamente evidências estáticas.

Lacunas abertas são normais. O ledger mantém o registro de decisão pequeno e à prova de adulteração; o Evidence Hub mostra as evidências de acompanhamento necessárias para tornar essa decisão pronta para auditoria. Ele lê o ledger via API e nunca modifica um registro. Serverless na AWS (Lambda + DynamoDB). Veja o Guia do Cliente e o Runbook de Administração.

A família: audit-ledger (o que aconteceu) · audit-ledger-mcp (este servidor — como agentes escrevem decisões) · evidence-hub (prontidão de auditoria).

Desenvolvimento

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

O servidor é TypeScript em Node 20+, ESM, transporte stdio, usando @modelcontextprotocol/sdk.

Relacionados

shahidh68/audit-ledger — a infraestrutura AWS com a qual este servidor fala. Stack CDK, SDKs Python e Node, dashboard de conformidade, documentação completa de arquitetura.
shahidh68/evidence-hub — a bancada de auditoria acima do ledger. Ele pontua as evidências de cada decisão, trata lacunas abertas como trabalho de acompanhamento esperado e gera pacotes de auditoria imprimíveis/baixáveis. (Guia do Cliente · Runbook de Administração)

Licença

Apache License 2.0 — veja LICENSE.

A concessão de patente é intencional. Infraestrutura de conformidade fica adjacente à revisão jurídica empresarial, e a concessão explícita importa nesse contexto.

Autor

Construído por Shahid. Disponível para funções de Principal AI Engineering e Head of AI Engineering, além de consultorias fracionadas, em fintech regulada no Reino Unido.

audit-ledger-mcp

Documentação

audit-ledger-mcp

O que ele faz

Início rápido — configuração zero

Propriedades do sandbox

Conecte ao Claude Desktop com configuração zero

Instalação em produção

Conecte a um agente

Claude Desktop

Cursor

LangGraph (Python)

Cliente personalizado (MCP bruto)

Como um fluxo de chamada record_decision funciona

Referência de ferramentas

record_decision

verify_decision

verify_completeness

list_decisions

Segurança

O que isto não é

Complemento: AI Decision Evidence Hub

Desenvolvimento

Relacionados

Licença

Autor

Como um fluxo de chamada `record_decision` funciona

`record_decision`

`verify_decision`

`verify_completeness`

`list_decisions`