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

Prueba este MCPPatrocinado

Documentación

audit-ledger-mcp

Conecta Claude, Cursor, LangGraph o tu propio agente al AI Audit Ledger. Este servidor MCP le da a un agente las herramientas para registrar, verificar y listar decisiones en un registro a prueba de manipulaciones con una línea de configuración.

Está construido para equipos que necesitan un registro claro de las decisiones de IA: registro del Artículo 12 de la Ley de IA de la UE, evidencia de riesgo de modelos FCA SS1/23 y minimización de datos GDPR. Los datos personales en bruto se someten a hash localmente antes de enviar nada, por lo que el registro solo ve huellas digitales.

La familia AI Audit Ledger. Este servidor MCP escribe decisiones en el registro, que demuestra qué ocurrió y si el registro fue modificado. El AI Decision Evidence Hub se sitúa por encima del registro, de solo lectura. Convierte cada registro de decisión ligero en un expediente de auditoría mostrando qué evidencia está presente, qué falta todavía, quién es responsable de cada vacío y la puntuación de preparación actual. Familia: audit-ledger · audit-ledger-mcp · evidence-hub.

Prueba el panel en vivo → · 30 decisiones sintéticas escritas mediante este servidor MCP, consultables y verificables.

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

Un flujo de trabajo de LangGraph llama a record_decision después de cada paso del agente. Tres eventos de auditoría escritos en el registro en vivo; cada uno verificable de forma independiente.

Qué hace

Expone cuatro herramientas a cualquier agente compatible con MCP:

Herramienta	Qué hace
`record_decision`	Registra una decisión de IA. Aplica hash a las entradas localmente y luego escribe en el registro. Devuelve un ID de evento.
`verify_decision`	Verifica de forma cruzada un registro almacenado contra la copia inmutable de S3 Object Lock. Devuelve `integrity_verified: true/false`.
`verify_completeness`	Detecta registros eliminados o faltantes. Compara el contador por inquilino del registro con las filas realmente presentes y devuelve los números de secuencia que faltan. La respuesta a "¿puedes demostrar que el registro está completo?"
`list_decisions`	Consulta decisiones recientes, opcionalmente filtradas por ventana de tiempo. Limitado por inquilino mediante clave API.

Cada llamada termina como un registro de auditoría de nivel regulatorio en tu registro desplegado: DynamoDB para consultas, S3 Object Lock en modo COMPLIANCE para la copia inmutable, retención de 7 años por defecto.

Inicio rápido — configuración cero

npx -y audit-ledger-mcp

Eso es todo. Sin variables de entorno, el servidor arranca en modo sandbox y escribe registros en un inquilino público compartido en un registro alojado. Puedes probar todas las herramientas — record_decision, verify_decision, verify_completeness, list_decisions — sin aprovisionar nada.

Cuando el modo sandbox está activo, verás un banner en 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...

Propiedades del sandbox


Alojado por	github.com/shahidh68/audit-ledger (mismo despliegue de AWS)
Inquilino	`sandbox-public` (compartido, público)
Límite de tasa	100 solicitudes/minuto por IP
Retención	7 años (los registros no se pueden eliminar)
Audiencia	Curiosos, pruebas de integración, demostraciones de frameworks
NO para	Datos de producción, PII de clientes, registros de cumplimiento reales

Conéctalo a Claude Desktop con configuración cero

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

Reinicia Claude Desktop. Las cuatro herramientas aparecen en el menú MCP inmediatamente. Prueba a pedirle a Claude que "registre esta decisión: ¿debería aprobarse X?" y observa cómo un registro aterriza en el panel del sandbox.

Instalación en producción

Para cargas de trabajo reales, despliega tu propio registro de auditoría y apunta el servidor MCP hacia él:

npm install -g audit-ledger-mcp

Configúralo con la URL de la API más tus claves de inquilino (que cualquiera de ellas esté definida desactiva el modo sandbox). AUDIT_HMAC_KEY es técnicamente opcional por compatibilidad hacia atrás, pero muy recomendado — consulta la nota sobre el valor a continuación:

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

La plantilla completa está en .env.example.

Conéctalo a un agente

Claude Desktop

Edita tu 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 es el secreto de inquilino que se usa para aplicar hash con clave a la PII localmente antes de que cualquier carga útil salga del proceso del servidor MCP. Genéralo una vez con node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" y guarda el resultado en el bloque env de arriba. El MCP nunca transmite este valor, solo lo lee.

Reinicia Claude Desktop. Verás "audit-ledger" en el menú de herramientas MCP. Pídele a Claude algo como "Registra esta decisión: rechacé la solicitud porque…" y observa cómo llama a record_decision automáticamente.

Cursor

En la configuración de Cursor → MCP → añadir 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 en bruto)

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

El servidor habla MCP sobre stdio. Envía solicitudes initialize, tools/list y tools/call según la especificación MCP.

Cómo fluye una llamada a `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                 |                                 |

El almacenamiento en el lado de AWS ocurre de forma asíncrona a través de SQS → Processor Lambda → DynamoDB + S3 Object Lock. Consulta el ARCHITECTURE.md del repositorio principal para ver la ruta completa.

Referencia de herramientas

`record_decision`

Registra una decisión de IA en el registro.

Parámetro	Tipo	Obligatorio	Notas
`model_version`	string	Sí	p. ej. `"claude-sonnet-4-7-20251022"`
`raw_system_prompt`	string	Sí	Se aplica hash localmente
`raw_user_input`	string	Sí	Se aplica hash localmente
`ai_decision_output`	object	Sí	Se almacena tal cual — no debe contener PII en bruto
`human_in_loop`	boolean	Sí	Crítico para el Artículo 14 de la Ley de IA de la UE
`event_id`	uuid v4	No	Se genera automáticamente si se omite
`timestamp`	ISO 8601	No	Por defecto, ahora

`verify_decision`

Verifica la integridad de un registro almacenado.

Parámetro	Tipo	Obligatorio	Notas
`event_id`	uuid v4	Sí	El ID del registro a verificar

Devuelve el registro de DynamoDB, el registro de S3 y integrity_verified: true/false.

`verify_completeness`

Detecta registros faltantes. Herramienta hermana de verify_decision: esa demuestra que un registro existente no ha sido alterado; esta demuestra que no se han eliminado registros.

Parámetro	Tipo	Obligatorio	Notas
`from`	integer	No	Límite inferior inclusivo de sequence_no. Por defecto, 1.
`to`	integer	No	Límite superior inclusivo de sequence_no. Por defecto, el contador actual del inquilino.
`tenant_id`	string	No	Solo se requiere con la clave de lectura de administrador; se ignora en caso contrario.

Devuelve el rango solicitado, el recuento esperado frente al encontrado, la lista de números de secuencia faltantes y una nota legible.

{
  "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 las decisiones recientes del inquilino que llama.

Parámetro	Tipo	Obligatorio	Notas
`from`	ISO 8601	No	Por defecto, hace 7 días
`to`	ISO 8601	No	Por defecto, ahora
`limit`	integer 1–500	No	Por defecto, 100

Seguridad

El hash de PII ocurre en este proceso, no en el registro. HMAC-SHA256 sobre UTF-8, con clave derivada del AUDIT_HMAC_KEY que configuras en tu entorno. La clave nunca sale de tu proceso; solo se envía el digesto hexadecimal de 64 caracteres. El SHA-256 simple de valores de baja entropía (nombres, correos) se puede forzar por fuerza bruta en segundos y, según la orientación de ICO/EDPB, sigue contando como dato personal, por lo que la versión con clave es la predeterminada para instalaciones nuevas. Por compatibilidad hacia atrás, si AUDIT_HMAC_KEY no está definido, el MCP recurre a SHA-256 simple y registra una advertencia de obsolescencia única en stderr; las configuraciones existentes siguen funcionando sin cambios.
Las claves API nunca se registran. Provienen de variables de entorno, se pasan en el encabezado x-api-key y nunca se devuelven al agente ni se escriben en disco.
Dos espacios de nombres de claves. Las claves de escritura no pueden leer; las claves de lectura no pueden escribir. Una clave de escritura filtrada no puede exfiltrar datos; una clave de lectura filtrada no puede plantar registros falsos.
Los errores se propagan con transferencia del estado HTTP. Los límites de tasa, las claves no válidas y los errores de validación se muestran al agente para que pueda reaccionar adecuadamente en lugar de reintentar a ciegas.

Qué no es esto

No es asesoramiento legal. Es infraestructura que produce evidencia de auditoría. Si esa evidencia satisface alguna obligación regulatoria específica es una cuestión para tu equipo legal.
No es un sustituto de una auditoría de riesgo de modelos. Registra lo que hizo la IA, no si lo hizo correctamente.
No es una herramienta de pruebas de sesgo o equidad. Es la capa de auditoría debajo de cualquier prueba que ya hagas.

Complemento: AI Decision Evidence Hub

Este servidor MCP escribe decisiones en el registro — el registro inmutable de lo que ocurrió. El AI Decision Evidence Hub es el banco de trabajo de solo lectura sobre el registro. Responde a la siguiente pregunta que un auditor plantea: la decisión está registrada, pero ¿la evidencia es suficientemente completa para revisarla?

Para cada decisión registrada produce:

una puntuación de preparación para auditoría (0–100) en nueve categorías de evidencia (modelo, datos, política, revisión humana, monitoreo, prompt, integridad, retención, decisión);
exactamente qué evidencia está presente frente a la que falta, y quién es responsable de cada vacío esperado;
un paquete de auditoría por decisión que se puede imprimir, guardar como PDF o descargar como JSON;
un panel (con enlaces cruzados con el del registro), además de un resolvedor basado en manifiestos que autocompleta evidencia estática.

Los vacíos abiertos son normales. El registro mantiene el registro de decisión pequeño y a prueba de manipulaciones; Evidence Hub muestra la evidencia de seguimiento necesaria para que esa decisión esté lista para auditoría. Lee el registro a través de su API y nunca modifica un registro. Serverless en AWS (Lambda + DynamoDB). Consulta su Guía del cliente y Manual de administración.

La familia: audit-ledger (qué ocurrió) · audit-ledger-mcp (este servidor — cómo los agentes escriben decisiones) · evidence-hub (preparación para auditoría).

Desarrollo

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

El servidor es TypeScript en Node 20+, ESM, transporte stdio, usando @modelcontextprotocol/sdk.

Relacionados

shahidh68/audit-ledger — la infraestructura de AWS con la que habla este servidor. Stack de CDK, SDKs de Python y Node, panel de cumplimiento, documentación completa de arquitectura.
shahidh68/evidence-hub — el banco de trabajo de auditoría sobre el registro. Puntúa la evidencia de cada decisión, trata los vacíos abiertos como trabajo de seguimiento esperado y genera paquetes de auditoría imprimibles/descargables. (Guía del cliente · Manual de administración)

Licencia

Apache License 2.0 — consulta LICENSE.

La concesión de patente es intencional. La infraestructura de cumplimiento se sitúa junto a la revisión legal empresarial y la concesión explícita importa allí.

Autor

Construido por Shahid. Disponible para roles de Principal AI Engineering y Head of AI Engineering, y compromisos de asesoría fraccionada, en fintech regulada del Reino Unido.

audit-ledger-mcp

Documentación

audit-ledger-mcp

Qué hace

Inicio rápido — configuración cero

Propiedades del sandbox

Conéctalo a Claude Desktop con configuración cero

Instalación en producción

Conéctalo a un agente

Claude Desktop

Cursor

LangGraph (Python)

Cliente personalizado (MCP en bruto)

Cómo fluye una llamada a record_decision

Referencia de herramientas

record_decision

verify_decision

verify_completeness

list_decisions

Seguridad

Qué no es esto

Complemento: AI Decision Evidence Hub

Desarrollo

Relacionados

Licencia

Autor

Cómo fluye una llamada a `record_decision`

`record_decision`

`verify_decision`

`verify_completeness`

`list_decisions`