MCP Server Operators — Complete Guide

What Operators Are

When you call anonym_legal_anonymize_text, PII in your text gets detected and replaced. By default, all detected entities are replaced with positional tokens: <PERSON_1>, <EMAIL_1>, etc.

The operators parameter overrides this per entity type. You pass a JSON object where the key is an entity type (e.g., "PERSON") and the value is an operator configuration. The 6 available operators are: replace, redact, hash, encrypt, mask, and keep.

"operators": {
  "ENTITY_TYPE_1": { "type": "operator_name", ...params },
  "ENTITY_TYPE_2": { "type": "operator_name", ...params },
  ...
}

// Entity types not in operators use the default (tokenize/replace)
// All 285+ entity type names are valid keys

Replaces the detected entity with a static string you provide via new_value. If new_value is omitted, the entity is replaced with a type-labeled placeholder token like <PERSON>.

"PERSON": { "type": "replace", "new_value": "[CLIENT]" }
"LOCATION": { "type": "replace", "new_value": "[LOCATION]" }
"EMAIL_ADDRESS": { "type": "replace" }  // uses <EMAIL_ADDRESS>

// Input:  "Send contract to John Smith at john@acme.com, Berlin office"
// Output: "Send contract to [CLIENT] at <EMAIL_ADDRESS>, [LOCATION] office"

Removes the entity from the text completely. No token, no placeholder — the value is gone. The text around it is preserved. Use with mode: "redact" globally for permanent removal, or selectively per entity type.

"US_SSN": { "type": "redact" }
"CREDIT_CARD": { "type": "redact" }

// Input:  "SSN 123-45-6789, card 4532015112830366"
// Output: "SSN , card "

Replaces the entity with a SHA-256 or SHA-512 hex digest. The same input always produces the same hash — making it useful for deduplication and linking records without storing original values. Hashing is one-way: you cannot recover the original from the hash.

"PERSON": { "type": "hash", "hash_type": "SHA256" }
"EMAIL_ADDRESS": { "type": "hash", "hash_type": "SHA256" }

// Input:  "Patient: John Smith, john@clinic.org"
// Output: "Patient: a8f5f167f44f4964e6c99..., 5d41402abc4b2a76b9719d..."
// Same inputs → same hashes every time (deterministic)

Encrypts the entity value with AES-256 using a key you provide. The key is 16, 24, or 32 characters. anonym.legal does not store or log the key. Anyone with the key can decrypt the value. Unlike tokenization, no server-side session is needed — decryption is self-contained.

"IBAN_CODE": { "type": "encrypt", "key": "my-32-char-encryption-key-here-!" }
"CREDIT_CARD": { "type": "encrypt", "key": "my-32-char-encryption-key-here-!" }

// Input:  "Transfer to IBAN DE89370400440532013000"
// Output: "Transfer to IBAN ENC:base64encodedciphertext..."
// Decrypt: AES-256-GCM decrypt with your key

Replaces a portion of the entity with a masking character (default: *). You control how many characters to mask and whether to mask from the start or end. The remaining visible characters provide enough context for the AI to reason about the type without seeing the full value.

// Phone: show first digits, mask last 6
"PHONE_NUMBER": { "type": "mask", "chars_to_mask": 6, "from_end": true }
// "+1-555-867-5309" → "+1-555-******"

// SSN: show last 4, mask first 7
"US_SSN": { "type": "mask", "chars_to_mask": 7, "from_end": false }
// "123-45-6789" → "*******6789"

// Card: mask first 12, show last 4
"CREDIT_CARD": { "type": "mask", "chars_to_mask": 12, "masking_char": "X", "from_end": false }
// "4532015112830366" → "XXXXXXXXXXXX0366"

Detects the entity type but leaves the original value in place. This is the opt-out operator — useful when you want to analyze what types exist (or get detection counts) while selectively preserving certain values that are acceptable to share with the AI.

"DATE_TIME": { "type": "keep" }
"LOCATION": { "type": "keep" }
"PERSON": { "type": "redact" }

// Input:  "John filed the report in Berlin on March 15"
// Output: "  filed the report in Berlin on March 15"
// PERSON redacted, DATE_TIME and LOCATION kept

Operator Decision Table

Pick the right operator for each situation:

Combined Operator Examples

Real-world scenarios mixing operators in a single call:

{
  "text": "The contract between ACME Corp and John Smith (SSN 123-45-6789)\n  for property at 123 Main St, IBAN DE89370400440532013000...",
  "entity_groups": ["UNIVERSAL", "FINANCIAL", "NORTH_AMERICA", "LEGAL"],
  "operators": {
    "PERSON": { "type": "replace", "new_value": "[PARTY]" },
    "LOCATION": { "type": "replace", "new_value": "[ADDRESS]" },
    "US_SSN": { "type": "redact" },
    "IBAN_CODE": { "type": "encrypt", "key": "legal-vault-32char-key---------!" },
    "DATE_TIME": { "type": "keep" }
  },
  "persistence": "persistent"
}

{
  "text": "Patient Jane Doe (MRN: MR-8842156, DOB: 1985-03-15)\n  prescribed metformin 500mg, US Medicare 1EG4-TE5-MK72",
  "entity_groups": ["UNIVERSAL", "HEALTHCARE", "NORTH_AMERICA"],
  "operators": {
    "PERSON": { "type": "hash", "hash_type": "SHA256" },
    "DATE_TIME": { "type": "replace", "new_value": "[DATE]" },
    "MEDICAL_RECORD_NUMBER": { "type": "hash", "hash_type": "SHA256" },
    "US_MEDICARE": { "type": "redact" }
  }
}

{
  "text": "Transaction from account 4532015112830366 (John Smith)\n  IBAN DE89370400440532013000, amount €4,250.00",
  "entity_groups": ["UNIVERSAL", "FINANCIAL", "DACH"],
  "operators": {
    "CREDIT_CARD": { "type": "mask", "chars_to_mask": 12, "from_end": false },
    "IBAN_CODE": { "type": "mask", "chars_to_mask": 14, "from_end": true },
    "PERSON": { "type": "hash", "hash_type": "SHA256" }
  }
}

Summary

• replace — human-readable label, non-reversible without session
• redact — permanent removal, no trace
• hash — deterministic one-way, enables deduplication
• encrypt — AES-256, reversible with your key only
• mask — partial visibility, configurable from start or end
• keep — detect but pass through unchanged

The default (no operator specified for an entity type) is equivalent to replace with a positional token like <PERSON_1>, which is reversible via anonym_legal_detokenize_text using the returned session_id.