FPE Demo MCP — FF3 Format Preserving Encryption Server

FPE Demo MCP is a lightweight MCP (Model Context Protocol) server that demonstrates authentication and format‑preserving encryption (FF3 FPE) in a clean, readable implementation. MCP is a JSON-RPC protocol that enables LLMs to securely call external tools and services.

• ✅ FF3 FPE over digits (radix‑10)
• 🔐 Auth modes: authless, debug, test (shared secret or JWT), production (JWT only)
• 🏷️ ENC_FPE: prefix so encrypted values are obvious in logs/demos
• 🌐 Both stdio (local) and HTTP (web) transports

Demo Implementation: This shows how FF3 FPE + MCP authentication work together. Great for learning, prototyping, and understanding the concepts.

🚀 Quick Deploy

What this does: Deploys the MCP server to DigitalOcean App Platform with HTTPS, giving you a public URL for testing with web-based LLMs like ChatGPT or Claude web connectors.

Remote MCP URL: https://<your-app>.ondigitalocean.app/mcp

Auth modes:

• AUTH_MODE=authless for quick tests
• AUTH_MODE=test + header Authorization: Bearer <AUTH_TOKEN>
• AUTH_MODE=production + Bearer JWT

Note: App Platform terminates HTTPS; your app runs plain HTTP. Set HOST=0.0.0.0 and DO injects PORT.

Local Testing

MCP stdio (for LLM clients)

npm install
npm run build

# Start MCP server (stdio transport)
npm start
# or: AUTH_MODE=debug npm start

Perfect for: Claude Desktop, Claude Code, any local MCP-compatible tool.

HTTP server (for web testing)

# Basic HTTP server (no CORS)
npm run start:http

# With CORS for browser playground testing
CORS_ORIGIN=https://playground.ai.cloudflare.com npm run start:http

Server runs at http://127.0.0.1:8765/mcp using MCP Streamable HTTP protocol.

Both servers expose the same two tools:

• fpe_encrypt — encrypts a digit-domain string and returns ENC_FPE:...
• fpe_decrypt — decrypts a prior ENC_FPE:... payload

Try it (copy‑paste examples)

MCP stdio testing

Encrypt

echo '{
  "jsonrpc":"2.0","id":1,"method":"tools/call",
  "params":{"name":"fpe_encrypt","arguments":{"value":"123-45-6789"}}
}' | node dist/src/stdio-server.js

Decrypt

echo '{
  "jsonrpc":"2.0","id":2,"method":"tools/call",
  "params":{"name":"fpe_decrypt","arguments":{"value":"ENC_FPE:096616337"}}
}' | node dist/src/stdio-server.js

HTTP MCP testing

Initialize connection

curl -i http://127.0.0.1:8765/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

List tools (use MCP-Session-ID from previous response)

curl -s http://127.0.0.1:8765/mcp \
  -H 'Content-Type: application/json' \
  -H 'MCP-Session-ID: <session-id>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Encrypt

curl -s http://127.0.0.1:8765/mcp \
  -H 'Content-Type: application/json' \
  -H 'MCP-Session-ID: <session-id>' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fpe_encrypt","arguments":{"value":"123-45-6789"}}}'

Both servers normalize input to digits for radix‑10 before encryption.

Auth & Config

• AUTH_MODE: authless (default) | debug | test | production
• Shared secret (test mode): AUTH_TOKEN="demo-secret" → pass as {"user_token":"demo-secret"}
• JWT (test/production): Pass as {"user_token":"Bearer <jwt>"} or Authorization header
  • JWT Secret: Uses demo-secret by default, or set AUTH_JWT_SECRET for different signing key
  • JWT Algorithm: HS256 (symmetric key)
  • Optional Claims: Set AUTH_JWT_ISS for issuer validation, AUTH_JWT_AUD for audience validation

FPE Configuration (defaults provided):

export FPE_KEY=00112233445566778899aabbccddeeff    # 32-char hex key
export FPE_TWEAK=abcdef12345678                    # 14-char hex tweak

How it works (short version)

• MCP server: exposes fpe_encrypt / fpe_decrypt tools via stdio JSON-RPC.
• Auth:
  • authless/debug → skip
  • test → shared secret or JWT (HS256)
  • production → JWT only (for testing stricter auth)
• FPE (FF3):
  • Radix-10 cipher (digits only) using AES key + tweak.
  • Input normalized to digits (e.g., SSN 123-45-6789 → 123456789) before encryption.
  • Ciphertext returned as ENC_FPE:<digits> to be visually obvious in the demo.

Beyond this demo

This demo shows the core concepts. For real-world usage, you'd need:

• Key Management: KMS integration (AWS KMS, GCP KMS, HashiCorp Vault)
• Per-record tweaks: Unique tweaks per user/record to prevent pattern analysis
• Audit trails: Comprehensive logging for compliance (PCI, SOX, GDPR)
• Input validation: Schema enforcement and rate limiting
• Metadata tracking: Database fields to track encryption state, not string prefixes
• Infrastructure: Load balancing, monitoring, backup/recovery
• Compliance: Security reviews, penetration testing, certifications

FAQ

Why the ENC_ prefix?
It's a teaching aid — newcomers can see that a value is encrypted. In real systems, you'd likely omit it.

Why only digits?
FF3 operates over a radix. We start with radix-10 because it’s the clearest demo (SSNs, phones). You can extend to radix-36 (0-9a-z) if your library/config supports it.

Can I switch to RS256 JWT?
Yes — load a PEM public key and set the algorithm to RS256. The verification call stays the same.

Browser vs Remote Usage

For browser playground testing (like Cloudflare AI Playground), use the HTTP server with CORS:

CORS_ORIGIN=https://playground.ai.cloudflare.com npm run start:http

For remote server-to-server usage (ChatGPT, Claude via API, or production integrations), CORS is not needed:

npm run start:http

The MCP HTTP transport works with both browser-based and server-to-server clients. Browser clients require CORS headers, while server-to-server clients (like ChatGPT Actions or Claude's server integrations) don't need CORS.

For production deployment with web-based LLMs, see our Deployment Guide which covers DigitalOcean App Platform and other hosting options.

Docs

• Deployment Guide → docs/DEPLOYMENT.md
• Using with Claude/ChatGPT/others → docs/USAGE-LLMS.md
• Architecture → docs/ARCHITECTURE.md
• JSON Schemas → docs/SCHEMAS.md
• FF3 limitations → docs/LIMITATIONS.md

BSL 1.1 — see LICENSE.md.