MCP Integration Guide

Last Updated: January 30, 2026 MCP Server Version: 2.2.0

What is MCP?#

MCP stands for Model Context Protocol. It allows AI assistants (like Claude) to connect directly to anonym.legal and perform PII anonymization tasks on your behalf.

Instead of copying and pasting text between applications, the AI can:

1. Analyze text for personal information
2. Anonymize or tokenize sensitive data
3. Restore tokenized data when needed
4. Manage your sessions and check your balance

Who Can Use MCP?#

MCP is available for:

• Pro plan subscribers
• Business plan subscribers

You need an API key from anonym.legal. Your API key authenticates requests and tracks token usage against your account.

Quick Start#

Step 1: Get Your API Key#

1. Log in to anonym.legal
2. Go to Settings > Developer or API
3. Click Generate New API Key
4. Copy and save your key securely

Important: Keep your API key secret. Anyone with your key can use your tokens.

Step 2: Configure Claude Desktop#

Add anonym.legal to your Claude Desktop configuration:

{
  "mcpServers": {
    "anonym-legal": {
      "command": "npx",
      "args": ["-y", "anonym-legal-mcp"],
      "env": {
        "ANONYM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Save and restart Claude Desktop. The AI can now use anonym.legal tools.

Available Tools#

The MCP server provides 7 tools for PII management:

Tool Reference#

1. Analyze Text#

Scans text for PII without modifying it. Returns detected entities with positions and confidence scores.

Parameters:

Example:

"Analyze this text for PII: John Smith called from 555-123-4567"

Response includes:

• entities: Array of detected entities with type, text, position, and score
• entities_found: Total count
• language: Detected language
• tokens_charged: Cost deducted

2. Anonymize Text#

Replaces PII with tokens or redactions. Supports two modes:

Modes:

• Tokenize (reversible): Creates session with mappings like <PERSON_1>, <EMAIL_1>
• Redact (permanent): Replaces with [PERSON], [EMAIL] - cannot be reversed

Parameters:

Example (Tokenize):

"Anonymize this email in tokenize mode so I can restore it later:
Dear John Smith, your order #12345 has shipped to 123 Main St."

Response includes:

• anonymized_text: Text with replacements
• session_id: ID for detokenization (tokenize mode only)
• entities_found: Count of entities replaced

3. Detokenize Text#

Restores original values in tokenized text using a session ID.

Parameters:

Example:

"Restore this text using session abc-123:
Dear <PERSON_1>, your order #12345 has shipped to <LOCATION_1>."

4. Get Balance#

Check your current token balance and billing cycle.

Parameters:

Response includes:

• balance: Remaining tokens
• used: Tokens used this cycle
• total: Monthly quota
• plan: Your subscription plan
• cycle_start / cycle_end: Billing period

5. Estimate Cost#

Preview token cost before processing.

Parameters:

Options:

• entityTypes: Number of entity types
• estimatedEntities: Expected entity count
• useEncryption: Whether encryption will be used
• tokenCount: Tokens to restore (detokenize)

6. List Sessions#

View your active tokenization sessions.

Parameters:

7. Delete Session#

Permanently delete a tokenization session. This is irreversible - all token mappings will be lost.

Parameters:

Entity Types#

Supported Entity Types#

The analyzer detects 50+ entity types across these categories:

Universal (all languages):

• PERSON - Names of people
• EMAIL_ADDRESS - Email addresses
• PHONE_NUMBER - Phone numbers
• LOCATION - Addresses, cities, countries
• DATE_TIME - Dates and times
• AGE - Age references
• URL - Web addresses
• IP_ADDRESS - IPv4 and IPv6 addresses
• MAC_ADDRESS - Hardware addresses
• DOMAIN_NAME - Domain names

Financial:

• CREDIT_CARD - Credit/debit card numbers
• IBAN_CODE - International bank account numbers
• SWIFT_CODE - Bank identifier codes
• CRYPTO - Cryptocurrency addresses

Regional Identifiers:

• DE_TAX_ID, DE_PASSPORT - Germany
• AT_SSN - Austria
• CH_AHV - Switzerland
• FR_NIR, FR_CNI, FR_PASSPORT - France
• ES_NIF, ES_NIE - Spain
• IT_FISCAL_CODE, IT_PASSPORT - Italy
• UK_NHS, UK_NIN - United Kingdom
• US_SSN, US_DRIVER_LICENSE, US_PASSPORT - United States
• And many more...

Entity Groups#

Use entity groups to detect multiple related types at once:

Custom Entities (Ad-Hoc Recognizers)#

Create custom entity types with pattern matching for domain-specific data like employee IDs, order numbers, or internal codes.

Structure:

{
  "ad_hoc_recognizers": [{
    "entity_type": "EMPLOYEE_ID",
    "patterns": [
      { "regex": "EMP-\\d{6}", "score": 0.95 },
      { "regex": "\\bID:\\s*\\d{6}\\b", "score": 0.85 }
    ],
    "context": ["employee", "staff", "worker"],
    "languages": ["en"]
  }]
}

Fields:

• entity_type: Name for your custom type (e.g., "ORDER_NUMBER")
• patterns: Array of regex patterns with optional confidence scores
• context: Words that increase detection confidence when nearby
• languages: Limit to specific languages

Example request:

"Analyze this text for employee IDs matching pattern EMP-XXXXXX:
Contact EMP-123456 or EMP-789012 for assistance."

Custom Operators#

Control how each entity type is anonymized with custom operators.

Available Operators:

Example:

{
  "operators": {
    "PERSON": {
      "type": "replace",
      "new_value": "[REDACTED NAME]"
    },
    "EMAIL_ADDRESS": {
      "type": "mask",
      "chars_to_mask": 5,
      "masking_char": "*",
      "from_end": false
    },
    "PHONE_NUMBER": {
      "type": "hash",
      "hash_type": "SHA256"
    }
  }
}

User Presets#

Presets are saved configurations for entity detection and operators. Use presets to apply consistent anonymization settings.

Built-in Presets:

• default - Standard PII detection
• personal - Your personal saved presets
• private - Maximum privacy settings

Using Presets:

"Anonymize this text using my 'legal-documents' preset"

Creating Presets:

Create presets in the anonym.legal web app under Settings > Presets. Each preset can include:

• Entity types to detect
• Per-entity operators
• Confidence thresholds
• Custom descriptions and tags

Encryption Keys#

End-to-End (E2E) Encryption Mode#

For maximum privacy, enable E2E mode. In this mode:

1. The server detects entities and returns their positions
2. Your client extracts and encrypts original values locally
3. The server never sees the token-to-value mapping
4. Only you can decrypt and restore the original text

Enabling E2E Mode:

{
  "e2e_mode": true,
  "mode": "redact"
}

Response includes:

• e2e_token_positions: Array of positions for client-side mapping
• Each position includes: token, entity_type, original_start, original_end, score

Client-Side Processing:

Use the provided E2E utilities:

• buildE2ETokenMappings() - Extract original values
• detokenizeLocally() - Restore without server
• serializeMappings() - Compact format for storage
• deserializeMappings() - Restore from storage

Managing Encryption Keys#

Manage your encryption keys in the anonym.legal web app under Settings > Encryption Keys:

• Create named encryption keys
• View key metadata (name, created date, last used)
• Rotate keys periodically
• Delete unused keys

Note: Key values are stored securely on your device, not on our servers.

Session Management#

Tokenization Sessions#

When you anonymize with mode='tokenize', a session is created to store token mappings.

Session Types:

• Session (default): Expires after 24 hours
• Persistent: Expires after 30 days

Session Lifecycle:

1. Created during tokenize anonymization
2. Stores mappings like <PERSON_1> -> "John Smith"
3. Used for detokenization
4. Automatically expires based on type
5. Can be manually deleted

Naming Sessions:

Give sessions meaningful names for easy identification:

"Anonymize this contract in tokenize mode, name the session 'contract-review-jan'"

Listing Sessions:

"Show me my active anonymization sessions"

Deleting Sessions:

"Delete session abc-123-def-456"

Warning: Deleting a session is permanent. You will not be able to restore tokenized text after deletion.

Token Costs#

Cost Formulas#

Analyze:

Base: 2 tokens
+ 0.5 per KB of text
+ 0.2 per entity type filter
+ 0.1 per entity found

Anonymize:

Base: 3 tokens
+ 0.5 per KB of text
+ 0.3 per unique entity type processed
+ 50% extra if encryption used

Detokenize:

Base: 2 tokens
+ 0.3 per token restored

Free Operations:

• Get balance
• Estimate cost
• List sessions
• Delete session

Estimating Costs#

Always estimate before processing large texts:

"Estimate the cost to anonymize this 50KB document"

Supported Languages#

The MCP server supports 48 languages:

Error Handling#

Common Errors#

Troubleshooting#

"Cannot connect to server"

• Verify your API key is correct and complete
• Check your internet connection
• Restart Claude Desktop after configuration changes

"Session not found"

• Sessions expire: 24 hours (session) or 30 days (persistent)
• Check session ID is correct
• Use list_sessions to see active sessions

"Insufficient tokens"

• Check your balance with get_balance
• Top up tokens in your account settings
• Use estimate_cost before large operations

Security Best Practices#

1. Keep your API key secret - Never share or commit to version control
2. Use E2E mode for sensitive data - Server never sees original values
3. Delete sessions when done - Remove token mappings you no longer need
4. Rotate API keys periodically - Generate new keys and revoke old ones
5. Monitor your balance - Watch for unexpected usage

Technical Specifications#

Limits#

Transport#

• Protocol: Streamable HTTP (MCP March 2025 spec)
• Authentication: Bearer token (API key)
• Content-Type: application/json
• CORS: Configured for anonym.legal

Endpoints#

Example Workflows#

Workflow 1: Analyze and Anonymize Email#

User: "Check this email for PII and anonymize it:
Dear John Smith, your invoice #INV-2024-001 for $5,000 is ready.
Please contact billing@company.com or call 555-123-4567."

AI: [Analyzes text, finds: PERSON, EMAIL, PHONE, custom patterns]
    [Anonymizes with tokenize mode]

Response: "Dear <PERSON_1>, your invoice #INV-2024-001 for $5,000 is ready.
Please contact <EMAIL_1> or call <PHONE_1>.
Session ID: abc-123 (valid for 24 hours)"

Workflow 2: Batch Process with Preset#

User: "Anonymize these customer records using my 'customer-data' preset"

AI: [Loads preset configuration]
    [Applies preset entity types and operators]
    [Processes each record]

Response: "Processed 5 records. All customer names masked, emails hashed."

Workflow 3: Restore for Review#

User: "Restore the anonymized text from session abc-123 for final review"

AI: [Retrieves session mappings]
    [Replaces tokens with original values]

Response: "Dear John Smith, your invoice #INV-2024-001..."

Need Help?#

• Documentation: anonym.legal/docs
• Support: anonym.legal/support
• FAQ: anonym.legal/docs/guides/faq

Available on: Pro and Business plans MCP Server Version: 2.2.0 Last Updated: January 30, 2026