mirror-vectax-mcp-server

A Model Context Protocol (MCP) implementation for secure text embeddings with privacy-preserving features using the Mirror SDK.

The Secure Embedding MCP Server provides a robust interface for processing text data with various security levels while generating embeddings for semantic search and analysis. It leverages the Mirror SDK to provide advanced security features including:

• Format-preserving encryption (FPE) for sensitive entities
• Vector encryption for secure embeddings
• Role-based access control (RBAC) for fine-grained security policies
• Entity detection for PII and sensitive information

• Unified Text Processing: Single entry point for various text operations with appropriate security measures

• Multiple Operation Modes:

• embed: Generate text embeddings

• secure: Apply security measures to text and embeddings

• analyze: Detect and analyze sensitive information

• mask: Anonymize sensitive entities

• auto: Automatically determine the appropriate operation

• Configurable Security Levels:

• none: No security measures

• low: Basic vector encryption

• medium: Entity encryption with FPE

• high: Full encryption with RBAC

• auto: Automatically determine security level based on content

• Natural Language Interface: Process requests in natural language

• Batch Processing: Handle multiple texts efficiently

• Semantic Search: Search across documents using embeddings

• Python 3.10+
• Mirror SDK
• LangChain with Hugging Face integration
• MCP Server framework
• Claude Desktop (for integration)

1. Visit the Mirror Platform
2. Click on "Sign Up" or "Register"
3. Fill in your details and create an account
4. Verify your email address

1. Log in to your Mirror Platform account
2. Navigate to the "API Keys" section in your dashboard
3. Click "Generate New Key"
4. Save both the API Key and Secret securely
5. These keys will be used in your environment variables or configuration file

This implementation demonstrates a subset of Mirror's capabilities. For full enterprise features including:

• Advanced encryption algorithms
• Custom security policies
• Enterprise-grade RBAC
• Advanced entity detection
• Custom model integration
• Dedicated support

Please contact our team at hello@mirrorsecurity.io or https://mirrorsecurity.io/

• Mirror Platform Documentation
• Mirror SDK Guide
• API Reference
• VectaX Intigrations

uv is a fast Python package installer and resolver that we'll use for our environment setup.

Screenshot1

Screenshot2

MacOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

# Using PowerShell
irm https://astral.sh/uv/install.ps1 | iex

Make sure to restart your terminal afterwards to ensure that the uv command gets picked up.

We provide two automatic installation scripts for different operating systems:

Run the following command in PowerShell or Command Prompt:

.\setup_claude_config.bat

This script will:

• Install uv if not present
• Set up the virtual environment
• Install required dependencies
• Configure Claude Desktop integration
• Create necessary configuration files

Run the following command in your terminal:

chmod +x setup_claude_config.sh
./setup_claude_config.sh

This script will:

• Check for required dependencies
• Install uv if not present
• Set up the virtual environment
• Install required dependencies
• Configure Claude Desktop integration
• Create necessary configuration files

Both scripts will create a log file (setup_log.txt) in the project directory for troubleshooting purposes.

If you prefer to install manually or if you already have the project cloned:

1. Clone the repository:

git clone https://github.com/yourusername/mirror-vectax-mcp-server.git
cd mirror-vectax-mcp-server

2. Set up virtual environment with uv:

uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate

3. Install mcp cli

uv add mcp[cli] httpx

4. Install dependencies:

uv add -r requirements.txt

5. Install Mirror SDK

Download Mirror SDK from platform and copy whl files into dist folder. Replace <version> with download version.

uv add .\dist\mirror_sdk-<version>.whl
uv add .\dist\mirror_enc-<version>.whl

6. Set up environment variables:

export MIRROR_API_KEY="your-mirror-api-key"
export MIRROR_SECRET="your-mirror-secret"
export MIRROR_SERVER_URL="https://your-mirror-server-url/v1"
export EMBEDDING_MODEL="nomic-ai/nomic-embed-text-v1.5" # Optional
export EMBEDDING_DEVICE="cpu" # Or "cuda" for GPU acceleration

7. Alternatively, create a configuration file secure_search_config.json with the following content:

{
"api_key": "your-mirror-api-key",
"secret": "your-mirror-secret",
"server_url": "https://your-mirror-server-url/v1",
"policy_eval_enabled": false,
"app_policy": {
"roles": ["admin", "researcher", "user", "analyst"],
"groups": ["ai_team", "ml_team", "nlp_team"],
"departments": ["research", "engineering", "IT"]
}
}

1. Download Claude Desktop from Anthropic's website
2. Install and launch Claude Desktop
3. Sign in with your Anthropic account

1. Create a claude_desktop_config.json file in your Claude Desktop configuration directory:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2. Add the following configuration (adjust paths as needed):

{
"mcpServers": {
"secure-embedding": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/YOUR/PROJECT/mirror-vectax-mcp-server",
"run",
"mirror_vectax_server.py"
]
}
}
}

3. Find the full path to the uv executable:

• macOS/Linux:

which uv

• Windows:

where uv

4. Update the command field in the config with the full path if needed
5. Save the file and restart Claude Desktop
6. Look for the hammer icon in Claude Desktop to confirm the MCP tools are available

1. Open Claude Desktop
2. Look for the hammer icon in the interface
3. Try a simple test:

Can you create an embedding for this sentence: "Machine learning models can process large amounts of data efficiently."

You can start the server using one of the following methods:

1. Make the script executable:

chmod +x run_mcp_server.sh

2. Run the server:

./run_mcp_server.sh

This script sets up the environment variables and runs the server with proper Python settings:

• Adds local bin to PATH
• Sets Python to unbuffered mode
• Enables Python debug mode
• Changes to the correct directory
• Runs the server with Python 3

uv run mirror_vectax_server.py

mcp run mirror_vectax_server.py

To verify the server is running correctly, you can use the MCP CLI to list available tools:

mcp list-tools --transport stdio --binary "python mirror_vectax_server.py"

This should output a list of all the tools provided by the server.

We can use mcp inspector to test the tools:

npx @modelcontextprotocol/inspector \
uv \
--directory /ABSOLUTE/PATH/TO/YOUR/PROJECT/mirror-vectax-mcp-server \
run \
mirror_vectax_server.py

After running mcp inspector, we can test tool, for example

If you need to modify the server startup configuration, you can edit the run_mcp_server.sh script. Here's what each line does:

#!/bin/bash
# Add local bin to PATH
export PATH="$PATH:/Users/Yourname/.local/bin"
# Enable Python debug mode
export PYTHONUNBUFFERED=1
export PYTHONDEBUG=1
# Change to project directory
cd /Users/your_downloaded_path/mirror-vectax-mcp-server-main
# Run the server with Python 3
exec python3 -u mirror_vectax_server.py

Make sure to:

1. Update the paths to match your system
2. Keep the script executable (chmod +x run_mcp_server.sh)
3. Run it from the project directory

The server consists of two main services:

1. EmbeddingService: Creates and manages text embeddings using HuggingFace models.
2. EncryptionService: Provides encryption capabilities using the Mirror SDK.

These services are initialized during server startup and made available to the MCP tools.

Can you create an embedding for this sentence: "Machine learning models can process large amounts of data efficiently."

Expected outcome: Should use the process tool with "embed" operation and return embedding information.

Can you analyze this text for sensitive information? "My social security number is 123-45-6789 and my email is test@example.com"

Expected outcome: Should use the process tool with "analyze" operation, detect SSN and email entities, and return analysis details.

Please securely process this text: "My credit card is 4111-1111-1111-1111 and my phone number is (555) 123-4567."

Expected outcome: Should use the process tool with "secure" operation at medium/high security level, encrypt sensitive entities, and potentially encrypt the embedding.

I need to encrypt and protect this confidential medical information: "Patient John Doe (DOB: 01/15/1980) has been diagnosed with hypertension."

Expected outcome: Should use the natural-language-process tool to determine intent (secure/mask) and apply appropriate security measures.

I need embeddings for the following phrases:

1. "Artificial intelligence is transforming industries."
2. "Data privacy is an important concern for organizations."
3. "Secure embeddings protect sensitive information during processing."

Expected outcome: Should use the batch-process tool to create embeddings for all three phrases.

Generate a user key for a data analyst who belongs to the research department and has user-level access.

Expected outcome: Should use the generate-user-key tool with appropriate roles, groups, and departments.

First, create embeddings for these phrases:

1. "Security is a top priority for financial institutions."
2. "Privacy regulations impact how companies handle data."
3. "Machine learning models require careful validation." Then search these documents for information about "data privacy".

Expected outcome: Should first use the batch-process tool to create embeddings, then use the search tool to find relevant documents, with the second phrase likely scoring highest.

Can you analyze this text: ""

Expected outcome: Should handle empty input gracefully, possibly returning an error message or minimal analysis.

Please secure this document: [Insert 1000+ word document about sensitive financial information]

Expected outcome: Should handle large input without issues, possibly detecting multiple entities and recommending high security level.

Analyze this text for sensitive information: "Mi número de pasaporte es AB123456 y mi dirección es Calle Principal 123, Madrid, España."

Expected outcome: Should detect entities in non-English text if the underlying entity detection supports it.

1. First, create secure embeddings for a set of medical records that contain patient information.
2. Generate a user key for a doctor in the cardiology department.
3. Search the embeddings for information about "heart conditions" using the doctor's access key.

Expected outcome: Should demonstrate a full workflow involving multiple tools - process for secure embeddings, generate-user-key for RBAC, and search with the key.

Process this text and determine the appropriate security measures automatically: "This quarterly financial report contains projections for Q3 2025 and includes account numbers for our top clients."

Expected outcome: Should use the process tool with "auto" operation and security level, detect sensitive content, and apply appropriate security measures based on the content.

Refer to the this doc for all the functionality tests with Mirror_VectaX

1. Claude Desktop Not Recognizing Tools

   • Ensure the claude_desktop_config.json file is in the correct location
   • Verify the paths in the configuration are absolute and correct
   • Restart Claude Desktop after making changes

2. Server Connection Issues

   • Check if the server is running (uv run mirror_vectax_server.py)
   • Verify environment variables are set correctly
   • Check the logs for any error messages

3. Memory Issues with Batch Processing

   • The server processes texts one at a time to prevent memory issues
   • If you experience disconnections, try processing fewer texts at once
   • Monitor system memory usage during processing

4. Model Loading Issues

   • Ensure you have sufficient disk space for model caching
   • Check internet connectivity for initial model download
   • Verify the model cache directory is writable

If you encounter issues:

1. Check the logs in Claude Desktop
2. Review the server logs
3. Ensure all prerequisites are installed correctly
4. Contact support if issues persist