pc2e-pii-shield
It is a secure MCP server for running read-only PostgreSQL queries with automatic PII masking, plus tools to restore masked values and manage PII detection.
Run read-only SELECT queries via
run_secure_query; results are automatically masked for names, emails, phones, and IDs.Restore original PII values from masked text using
unmask_textfor placeholders cached during the session.Add custom names to the detection roster with
add_to_rosterto improve local name-matching.Supports concurrent clients over SSE with API-key authentication, and local/stdio execution via
npx.Provides a
/statsendpoint for telemetry on connections, unique clients, and query execution.Uses in-memory, TTL-based pseudonymization so masked PII leaves no persistent disk footprint.
Provides secure, read-only PostgreSQL query execution with automatic PII masking, pseudonymization, and restoration capabilities for AI agents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pc2e-pii-shield Get the last 10 orders with customer names but replace PII with placeholders"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pc2e-pii-shield
A secure, production-grade Model Context Protocol (MCP) server providing read-only PostgreSQL query execution with automatic, client-side, and edge Personally Identifiable Information (PII) masking. It allows LLM agents (e.g., Cursor, Cline, Claude Code) to execute SQL queries on databases while ensuring strict compliance with GDPR, PDPA, and data privacy principles.
Designed and engineered as a reusable security middleware product, this server intercepts database query results to prevent sensitive data egress.
Technical Architecture
flowchart TD
Client["AI Agent / Client (Cursor/Cline)"]
Proxy["Nginx Reverse Proxy"]
App["pc2e-pii-shield (Express)"]
DB["Postgres Database (Tailscale-Only)"]
Client ==>|HTTPS / SSE Request| Proxy
Proxy ==>|x-api-key Authentication| App
App ==>|Regex Read-Only Validation| DB
DB ==>|Raw SQL Results| App
App ==>|PII Tokenization & Masking| Proxy
Proxy ==>|Sanitized Event Stream| ClientCore Components
Auto-Masking Interceptor (
masking.ts): Dynamically scans SQL result sets. It utilizes a hybrid approach: column schema matching (e.g., fields containingname,email,phone) combined with regex-based content scanning to detect and mask sensitive identifiers before data leaves the server.Pseudonymization Cache (
cache.ts): An in-memory, TTL-backed cache (default: 30 minutes) that maps raw values to temporary placeholders (e.g.,__PERSON_A__,__EMAIL_1__). This allows bi-directional restoration while preventing unbounded memory consumption.AST-Level Mutation Guard (
db.ts): A strict regex validator that intercepts raw SQL inputs. It blocks any non-SELECT commands and rejects queries containing forbidden keywords such asDROP,ALTER,DELETE,TRUNCATE,CREATE, orGRANT, ensuring a strict read-only boundary at the application layer.Concurrent Session Manager (
index.ts): Unlike basic single-connection templates, this server maintains an active map ofSSEServerTransportinstances keyed by connectionsessionId, allowing multiple remote developers or agents to connect and stream concurrently without state collisions.Telemetry & Metrics Endpoint (
/stats): Exposes connection counts, unique client IP tracking, and aggregate query execution statistics to monitor installation and active usage in real-time.
Related MCP server: PostgreSQL MCP Server
Security Model & Threat Mitigation
Zero-Trust Database Connectivity: Designed to prevent credential exposure. The database runs on an isolated Tailscale-only network interface (e.g.,
100.92.174.76), ensuring the database port is never exposed to the public internet.Encrypted Transport & API Key Security: The server is fronted by Nginx over HTTPS (port 443) using wildcard SSL certificates, enforcing a secure API key authentication gate (
x-api-key) before forwarding requests.In-Memory Lifecycle: Pseudonymization mappings are stored in memory with strict TTLs, leaving no persistent disk footprints of the masked PII.
Installation & Deployment
1. Prerequisite Environment Setup
Copy the environment template:
cp .env.example .envConfigure your database credentials and generate a secure API key inside .env.
2. Native Build
Ensure Node.js (v18+) is installed:
npm install
npm run build
npm start3. Containerized Deployment
Deploy using Docker Compose:
docker compose up -d --buildThis maps host port 3088 to the container's internal port 3000, running the SSE server automatically.
4. Direct Execution (NPX)
You can run the server instantly over Stdio transport without downloading the code manually:
npx -y mcp-pii-shield --db-uri "postgresql://username:password@localhost:5432/your_database"Or run the server over SSE transport:
npx -y mcp-pii-shield --sse --port 3000 --db-uri "postgresql://username:password@localhost:5432/your_database" --api-key "your_secret_key"Client Integration
A. Local Client Integration (via NPX over Stdio)
Configure your local AI client to launch the server directly using npx.
Claude Desktop (config.json)
Add the following block to your ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"pc2e-pii-shield": {
"command": "npx",
"args": [
"-y",
"mcp-pii-shield",
"--db-uri",
"postgresql://username:password@localhost:5432/your_database"
]
}
}
}Cursor (Settings → Features → MCP)
Click + Add New MCP Server.
Set Name to
pc2e-pii-shield.Set Type to
command.Set Command to:
npx -y mcp-pii-shield --db-uri "postgresql://username:password@localhost:5432/your_database"
VS Code (Cline / Roo Code)
Add the following to your client settings JSON:
{
"mcpServers": {
"pc2e-pii-shield": {
"command": "npx",
"args": [
"-y",
"mcp-pii-shield",
"--db-uri",
"postgresql://username:password@localhost:5432/your_database"
]
}
}
}B. Remote Client Integration (via HTTPS over SSE)
If you are connecting to a hosted server (e.g., your public NAS instance), connect via the SSE transport URL.
VS Code (Cline / Roo Code)
{
"mcpServers": {
"pc2e-pii-shield": {
"sseUrl": "https://pii-shield.thegeekybeng.com/sse?api_key=your_api_key_here"
}
}
}Cursor
Click + Add New MCP Server.
Set Name to
pc2e-pii-shield.Set Type to
SSE.Set URL to:
https://pii-shield.thegeekybeng.com/sse?api_key=your_api_key_here
Project Context & Technical Lead
This project was architected, built, and open-sourced by Andrew Yeo.
About the Lead Architect
Andrew is a Senior Systems Architect and AI Engineer based in Singapore, offering:
25 years of professional experience in APAC, managing program delivery, client onboarding, and technical vendor management.
16+ years of systems architecture and technology leadership, designing and deploying robust enterprise infrastructures and microservice platforms.
2+ years of dedicated hands-on AI/ML engineering, specializing in AI safety, LLM metrics, and secure agentic workflows.
Verified Proof-of-Work
Secure Civic Platforms: Architected and deployed MPS-Connect (a civic constituency casework platform) and Case-Writer-Intelligence (CWI), integrating a 3-stage causality engine with 7 human-in-the-loop approval gates, reducing document triage time by 40%.
AI Metrology & Testing: Designed the Portable Continuous Context Engine (PC2E), running a systematic, empirical evaluation of 50,000 cases across six LLM providers to benchmark model alignment and compliance.
Technical Focus: Expert in CI/CD & DevSecOps (GitHub Actions, Docker), containerized deployments, zero-trust network topologies, and local/edge SLM orchestrations.
Available Tools
3 toolsadd_to_rosterA
Register new names to the active regex scan roster for local name-matching detection.
Inputs: names (required).
run_secure_queryA
Execute a read-only SELECT database query. All PII values (names, emails, phones, NRIC/IDs) in the results will be automatically masked before being returned.
Inputs: sql_query (required).
unmask_textA
Restore the original raw PII values in a text payload by replacing placeholders (e.g. PERSON_A, EMAIL_1) with their original values cached during this session.
Inputs: masked_text (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool addresses a distinct concern: one unmask text, one manage the name roster, and one execute queries with automatic masking. There is no overlap that would cause an agent to misselect.
Most tools follow a verb_noun pattern (unmask_text, run_secure_query), but add_to_roster breaks the pattern with an intervening preposition. This is a minor deviation and the intent remains clear.
Three tools is a reasonable, focused set for a PII-shielding server. It is slightly lean but each tool serves a clear purpose without unnecessary bloat.
The core masking lifecycle is covered—query masking, unmasking, and roster management—but obvious gaps exist: no tool for masking non-query text, no roster removal or listing, and no way to manage the cached placeholders beyond unmasking. These gaps could force workarounds.
Related MCP Connectors
Guard AI agents' PostgreSQL/MySQL access via MCP: SQL audit, auth, masking, write approval
Paid remote MCP for governed database query review, SQL simulation, approvals, and audits.
Governed SQL access to your databases: redaction, query review and an audit log.
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA secure MCP server that enables querying PostgreSQL databases through an SSH tunnel with enforced read-only access, connection pooling, and comprehensive data exploration tools.ISC
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server that enables safe, read-only SQL SELECT queries against PostgreSQL databases with built-in security validation. It features connection pooling, automatic row limits, and structured logging to ensure secure and reliable database interactions.MIT
- AlicenseNot gradedqualityDmaintenanceRead-only PostgreSQL MCP server that enables running SELECT queries, listing tables and schemas, and describing columns, with built-in protection against writes and malicious SQL attacks.MIT
- AlicenseAqualityDmaintenanceA secure, read-only PostgreSQL MCP server that provides safe database introspection and querying capabilities.1420 npmMIT