piqrypt-mcp-server

PiQrypt MCP Server

<!-- mcp-name: io.github.PiQrypt/audit-trail -->

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 ``cmd set PIQRYPT_PYTHON=C:\path\to\venv\Scripts\python.exe ``

Linux / Mac ``bash 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+)

1. Install n8n MCP integration
2. Add PiQrypt MCP server to configuration
3. 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 identifier
• payload (object, required): Decision data
• previous_hash (string, optional): Previous event hash for chaining

Example: ``typescript const event = await mcp.call('piqrypt_stamp_event', { agent_id: 'trading_bot_v1', payload: { action: 'buy', symbol: 'AAPL', quantity: 100, price: 150.25 } }); ``

Returns: ``json { "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: ``typescript const result = await mcp.call('piqrypt_verify_chain', { events: [event1, event2, event3] }); ``

Returns: ``json { "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 export
• certified (boolean): Request PiQrypt certification
• output_format (string): json or pqz

Example: ``typescript 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 type
• from_timestamp (number, optional): Start time
• to_timestamp (number, optional): End time
• limit (number): Max results (default: 100)

Example: ``typescript 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:

1. Start Vigil: piqrypt vigil
2. Open http://localhost:8421
3. Go to All Agents view
4. Check the agents to delete → click ✕ Delete selected
5. 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: ``bash 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: ```bash

Linux / Mac

$PIQRYPT_PYTHON -c "import aiss; print('ok')"

Windows

%PIQRYPT_PYTHON% -c "import aiss; print('ok')" ```

---

📖 Documentation

• MCP Setup Guide
• Tools Reference
• n8n Integration
• Security Model
• RFC Compliance

---

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