MCP Server: FF3 FPE with Authentication Patterns

Overview

This MCP (Model Context Protocol) server provides a lightweight service to protect sensitive data in LLM and AI workflows by combining Format-Preserving Encryption (FF3 FPE) with pattern-based authentication and masking. It lets you define authentication patterns (rules that describe what parts of input are sensitive and how they should be handled) and apply FF3 FPE to those fields so that structured data retains its format and length while becoming cryptographically protected.

Using an MCP server in front of a model or downstream service reduces risk of leaking PII, credentials, and other sensitive tokens during prompt engineering, logging, or 3rd-party integrations. Because FF3 FPE preserves format (digits remain digits, fixed-length IDs remain fixed-length), downstream systems and UI components that expect a particular format generally continue to work without schema changes.

Features

• FF3 Format-Preserving Encryption (FPE) for numeric and alphanumeric fields
• Pattern-based authentication/masking rules to select which tokens or fields to protect
• Tokenization-style transforms that can be reversed with proper authorization
• REST API for integrating with apps, agents, and LLM pipelines
• Docker-friendly for local testing and deployment
• Keys and tweaks configurable via environment variables or secrets manager
• Audit-friendly: supports non-destructive masking and reversible encryption for authorized consumers

Installation / Configuration

Prerequisites: Docker (recommended) or a compatible runtime for the service. You will also need to provision an FF3 key and (optionally) a tweak strategy.

Clone the repository and build with Docker:

git clone https://github.com/Horizon-Digital-Engineering/fpe-demo-mcp.git
cd fpe-demo-mcp

# Build Docker image
docker build -t fpe-mcp .

Run the server with environment variables (example):

docker run -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e FPE_KEY="0123456789ABCDEF0123456789ABCDEF" \
  -e FPE_TWEAK_STRATEGY="fixed" \
  -e MCP_SIGNING_KEY="supersecret-signing-key" \
  fpe-mcp

Typical environment variables

Configuration can also be provided via a config file or secrets manager depending on your deployment hygiene requirements. Always store FPE keys in a secure secrets store and rotate them periodically.

Available Resources

• GitHub repository: https://github.com/Horizon-Digital-Engineering/fpe-demo-mcp
• FF3 specification and guidance: refer to NIST SP 800-38G and RFCs for format-preserving encryption
• MCP (Model Context Protocol) spec: review MCP docs to align request/response shapes for your LLM orchestration
• Example Postman/HTTP snippets (in repo) for quick testing
• Dockerfile and example compose for local evaluation

Example API Usage

Below are illustrative examples showing how a client might interact with the MCP server. Endpoint paths are provided as examples — consult the repo/docs for exact paths for your build.

Encrypt selected fields according to an authentication pattern:

curl -X POST https://localhost:8080/api/v1/transform \
  -H "Authorization: Bearer <mcp-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": {
      "name": "email-and-cc",
      "rules": [
        {"field": "email", "action": "fpe"},
        {"field": "credit_card.number", "action": "fpe", "radix": 10}
      ]
    },
    "payload": {
      "name": "Alice Example",
      "email": "[email protected]",
      "credit_card": {"number": "4111111111111111", "exp":"12/25"}
    }
  }'

Response (example): transformed payload with FPE applied to configured fields while preserving format:

{
  "payload": {
    "name": "Alice Example",
    "email": "g3nH2@[email protected]",
    "credit_card": {"number": "5738291029384756", "exp": "12/25"}
  },
  "meta": {"pattern": "email-and-cc", "encrypted": ["email","credit_card.number"]}
}

Reversal (authorized consumers only):

curl -X POST https://localhost:8080/api/v1/reverse \
  -H "Authorization: Bearer <mcp-reveal-token>" \
  -H "Content-Type: application/json" \
  -d '{ "payload": { "email": "g3nH2@[email protected]" } }'

Use Cases

• Protect PII in prompts: Before sending user data to an LLM, route content through the MCP server to mask or FPE-encrypt names, emails, and IDs. This prevents accidental memorization or leakage while retaining usable formats for downstream extraction.
• Secure observability and logging: Apply field-level FPE to logs and telemetry that contain customer identifiers so logs remain useful for debugging but no longer expose raw sensitive values.
• Shared model access: When different services or teams can call the same model, use the MCP to enforce per-team reveal policies. Teams can submit data encrypted with FPE; only authorized services can reverse it.
• Payment or financial