io.github.PiQrypt/audit-trail
Cryptographic audit trail for AI agents. Sign, verify, export. GDPR/HIPAA/EU AI Act.
Ask AI about io.github.PiQrypt/audit-trail
Powered by Claude Β· Grounded in docs
I know everything about io.github.PiQrypt/audit-trail. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
PiQrypt MCP Server
Cryptographic Audit Trail for AI Agents via Model Context Protocol
π What is PiQrypt MCP?
PiQrypt MCP Server provides Model Context Protocol access to PiQrypt β the post-quantum cryptographic audit trail for AI agents.
Use cases:
- π€ AI Agents: Sign every decision with cryptographic proof
- π n8n Workflows: Add audit trail to automation workflows
- π¦ Trading Bots: SEC/FINRA compliance for automated trading
- π₯ HR Automation: GDPR-compliant AI hiring decisions
- π₯ Healthcare AI: HIPAA audit trail for medical decisions
π¦ Installation
Prerequisites
1. Install piqrypt (required β Python 3.8+)
pip install piqrypt
The MCP server delegates all cryptographic operations to the piqrypt Python package.
If it is not installed, the server will return a clear error on every tool call.
2. Install the MCP server (Node.js 18+)
npm install -g @piqrypt/mcp-server
Install via npx (no global install)
npx @piqrypt/mcp-server
Build from source
git clone https://github.com/piqrypt/piqrypt-mcp-server
cd piqrypt-mcp-server
npm install
npm run build
PIQRYPT_PYTHON β custom Python environment
By default the server uses python3 (Linux/Mac) or python (Windows).
If piqrypt is installed in a virtual environment, set this variable to point to the right interpreter:
Windows
set PIQRYPT_PYTHON=C:\path\to\venv\Scripts\python.exe
Linux / Mac
export PIQRYPT_PYTHON=/path/to/venv/bin/python
To make it persistent, add it to your MCP client configuration:
{
"mcpServers": {
"piqrypt": {
"command": "piqrypt-mcp-server",
"args": [],
"env": {
"PIQRYPT_PYTHON": "/path/to/venv/bin/python"
}
}
}
}
βοΈ Configuration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"piqrypt": {
"command": "piqrypt-mcp-server",
"args": []
}
}
}
n8n (v1.88+)
- Install n8n MCP integration
- Add PiQrypt MCP server to configuration
- Use in workflows via MCP node
Compatible with
MCP clients
| Client | Version | Notes |
|---|---|---|
| Any MCP-compatible client | MCP spec 2024-11+ | stdio transport |
| n8n | 1.88+ | via MCP node |
| Cursor | any | add to mcp settings |
| VS Code | any | add to mcp settings |
| Continue | any | add to mcp settings |
| Windsurf | any | add to mcp settings |
Automation platforms (via MCP node)
| Platform | Integration | Use case |
|---|---|---|
| n8n | MCP node (native) | No-code audit trail |
| Make.com | HTTP module | Webhook-triggered stamping |
| Zapier | Webhooks + HTTP | Basic event recording |
What you can audit with PiQrypt MCP
Every tool call goes through the same 4 operations β stamp, verify, export, search. Here is what that means in practice depending on your context:
Automated trading / finance Any agent that submits orders, rebalances portfolios, or triggers transactions can stamp each decision before execution. The signed chain is exportable for SEC/FINRA audit without any additional infrastructure.
HR and hiring automation Any workflow that evaluates candidates, scores CVs, or routes applicants can stamp each decision. Provides a GDPR Art.22 compliant audit trail for AI-assisted hiring β who decided what, when, and what data was used (hashed, never stored raw).
Content and publishing pipelines Any agent that drafts, approves, or publishes content can stamp each step. Useful when multiple AI agents collaborate and you need to prove attribution β which agent wrote what, in what order.
DevOps and CI/CD Any agent that triggers deployments, merges branches, or rotates secrets can stamp each action. Provides a tamper-evident record of infrastructure changes made by autonomous agents.
Healthcare and medical AI Any diagnostic or triage agent can stamp each recommendation. Provides a HIPAA-compliant audit trail linking each AI output to a verifiable agent identity.
The common pattern in all cases:
[Agent makes decision]
β
piqrypt_stamp_event β sign + chain
β
[Agent executes action]
β
piqrypt_export_audit β portable proof, verifiable
without PiQrypt installed
π οΈ Available Tools
1. piqrypt_stamp_event
Sign an AI decision with cryptographic proof.
Parameters:
agent_id(string, required): Agent identifierpayload(object, required): Decision dataprevious_hash(string, optional): Previous event hash for chaining
Example:
const event = await mcp.call('piqrypt_stamp_event', {
agent_id: 'trading_bot_v1',
payload: {
action: 'buy',
symbol: 'AAPL',
quantity: 100,
price: 150.25
}
});
Returns:
{
"version": "AISS-1.0",
"agent_id": "trading_bot_v1",
"timestamp": 1739382400,
"nonce": "uuid-...",
"payload": { ... },
"previous_hash": "sha256:...",
"signature": "base64:..."
}
2. piqrypt_verify_chain
Verify integrity of event chain.
Parameters:
events(array, required): Events to verify
Example:
const result = await mcp.call('piqrypt_verify_chain', {
events: [event1, event2, event3]
});
Returns:
{
"valid": true,
"events_count": 3,
"chain_hash": "sha256:...",
"errors": []
}
3. piqrypt_export_audit
Export audit trail for compliance.
Parameters:
agent_id(string, required): Agent to exportcertified(boolean): Request PiQrypt certificationoutput_format(string):jsonorpqz
Example:
const audit = await mcp.call('piqrypt_export_audit', {
agent_id: 'trading_bot_v1',
certified: true,
output_format: 'json'
});
4. piqrypt_search_events
Fast search via SQLite index.
Parameters:
event_type(string, optional): Filter by typefrom_timestamp(number, optional): Start timeto_timestamp(number, optional): End timelimit(number): Max results (default: 100)
Example:
const trades = await mcp.call('piqrypt_search_events', {
event_type: 'trade_executed',
from_timestamp: 1739300000,
limit: 50
});
π Vigil Dashboard (optional, free)
Every stamped event is visible in Vigil β PiQrypt's local monitoring dashboard.
Note: Vigil is not launched automatically by the MCP server. You must start it separately before opening the dashboard.
piqrypt vigil
# β http://localhost:8421
Free tier includes: chain health, VRS risk score, 7-day history, CRITICAL alerts. Upgrade to Pro for 90-day history, TrustGate governance, and post-quantum signatures.
ποΈ Managing Agents
Agents are created automatically on first stamp. To view and delete agents:
- Start Vigil:
piqrypt vigil - Open http://localhost:8421
- Go to All Agents view
- Check the agents to delete β click β Delete selected
- Confirm β Vigil returns to the welcome screen when no agents remain
Agents are stored in
~/.piqrypt/agents/on your machine. Deleting an agent removes its keys and event history permanently.
π Security Model
Process Isolation
βββββββββββββββββββββββββββββββββββββββ
β MCP Client (any MCP-compatible client) β
β β JSON-RPC over stdio β
βββββββββββββββββββββββββββββββββββββββ€
β MCP Server (TypeScript/Node.js) β β No crypto here
β β subprocess call β
βββββββββββββββββββββββββββββββββββββββ€
β Python Bridge (bridge.py) β
β β invokes CLI β
βββββββββββββββββββββββββββββββββββββββ€
β PiQrypt CLI (Python) β
β β uses β
βββββββββββββββββββββββββββββββββββββββ€
β Core Crypto (aiss package) β β All crypto here
β β’ Ed25519 / Dilithium3 β
β β’ RFC 8785 canonical JSON β
β β’ Hash chains β
βββββββββββββββββββββββββββββββββββββββ
Guarantees
β
Private keys never exposed to MCP layer
β
All crypto in Python (Ed25519, Dilithium3)
β
Same security as CLI (process isolation)
β
RFC AISS-1.1 compliant (identical output)
β
Input validation before subprocess call
π Examples
Trading Bot (n8n)
[Webhook: price alert]
β
[AI Decision: buy/sell?]
β
[PiQrypt MCP: stamp decision] β Audit trail
β
[Execute trade API]
β
[Database: store proof]
HR Automation
[Upload CV]
β
[AI Agent: evaluate candidate]
β
[PiQrypt MCP: stamp evaluation] β GDPR compliance
β
[Email HR team]
π§ͺ Testing
# Build
npm run build
# Test bridge
python3 src/python/bridge.py stamp '{"agent_id":"test","payload":{"action":"test"}}'
# Test MCP server (manual)
node dist/index.js
# Then send MCP request via stdin
π§ Troubleshooting
Error: piqrypt is not installed in this Python environment
The Python interpreter used by the MCP server cannot find the piqrypt package.
Fix:
pip install piqrypt
If piqrypt is installed in a virtual environment and not the system Python, set PIQRYPT_PYTHON to point to the correct interpreter:
# Linux / Mac
export PIQRYPT_PYTHON=/path/to/venv/bin/python
# Windows
set PIQRYPT_PYTHON=C:\path\to\venv\Scripts\python.exe
To verify which Python the server will use:
# Linux / Mac
$PIQRYPT_PYTHON -c "import aiss; print('ok')"
# Windows
%PIQRYPT_PYTHON% -c "import aiss; print('ok')"
π Documentation
π€ Contributing
We welcome contributions! See CONTRIBUTING.md.
π License
MCP Server β MIT License - see LICENSE PiQrypt Core β free tier + commercial tiers
π Links
- PiQrypt Core: https://github.com/piqrypt/piqrypt
- MCP Protocol: https://modelcontextprotocol.io
- n8n: https://n8n.io
- Documentation: https://docs.piqrypt.com
Built with β€οΈ by PiQrypt Inc.
