Content
# Secure Embedding MCP Server
A Model Context Protocol (MCP) implementation for secure text embeddings with privacy-preserving features using the Mirror SDK.
## Overview
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
## Features
- **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
## Prerequisites
- Python 3.10+
- Mirror SDK
- LangChain with Hugging Face integration
- MCP Server framework
- Claude Desktop (for integration)
## Mirror Platform Setup
### 1. Registration
1. Visit the [Mirror Platform](https://platform.mirrorsecurity.io)
2. Click on "Sign Up" or "Register"
3. Fill in your details and create an account
4. Verify your email address
### 2. Getting Your API Keys
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
### 3. Additional Capabilities
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](mailto:hello@mirrorsecurity.io)
or [https://mirrorsecurity.io/](https://mirrorsecurity.io/#schedulecall)
### 4. Reference Documentation
- [Mirror Platform Documentation](https://docs.mirrorsecurity.io/docs/getting-started/quick-start-guide)
- [Mirror SDK Guide](https://docs.mirrorsecurity.io/docs/mirror-vectax-sdk/overview)
- [API Reference](https://docs.mirrorsecurity.io/docs/mirror-vectax-sdk/API-Reference/sdk-configuration)
- [VectaX Intigrations](https://docs.mirrorsecurity.io/docs/mirror-vectax-sdk/integrations/VectorDB)
## Development Environment Setup
### Install uv
[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver that we'll use for our environment setup.
### Available MCP Servers:
**Screenshot1**
**Screenshot2**
**MacOS/Linux**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
**Windows**
```bash
# 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.
## Installation
### Automatic Installation (Recommended)
We provide two automatic installation scripts for different operating systems:
#### Windows
Run the following command in PowerShell or Command Prompt:
```bash
.\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
#### macOS/Linux
Run the following command in your terminal:
```bash
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.
### Manual Installation
If you prefer to install manually or if you already have the project cloned:
1. Clone the repository:
```bash
git clone https://github.com/yourusername/mirror-vectax-mcp-server.git
cd mirror-vectax-mcp-server
```
2. Set up virtual environment with uv:
```bash
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
3. Install mcp cli
```bash
uv add mcp[cli] httpx
```
4. Install dependencies:
```bash
uv add -r requirements.txt
```
5. Install Mirror SDK
Download Mirror SDK from [platform](htttps://platform.mirrrorsecurity.io) and copy whl files into `dist` folder.
Replace `<version>` with download version.
```bash
uv add .\dist\mirror_sdk-<version>.whl
uv add .\dist\mirror_enc-<version>.whl
```
6. Set up environment variables:
```bash
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:
```json
{
"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"]
}
}
```
## Claude Desktop Integration
### 1. Install Claude Desktop
1. Download Claude Desktop from [Anthropic's website](https://claude.ai/desktop)
2. Install and launch Claude Desktop
3. Sign in with your Anthropic account
### 2. Configure Claude Desktop
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):
```json
{
"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:**
```bash
which uv
```
- **Windows:**
```cmd
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
### 3. Testing the Integration
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."
```
## Usage
### Starting the Server
You can start the server using one of the following methods:
#### Method 1: Using the run_mcp_server.sh Script (Recommended)
1. Make the script executable:
```bash
chmod +x run_mcp_server.sh
```
2. Run the server:
```bash
./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
#### Method 2: Using uv
```bash
uv run mirror_vectax_server.py
```
#### Method 3: Using MCP CLI
```bash
mcp run mirror_vectax_server.py
```
### Testing the Server
To verify the server is running correctly, you can use the MCP CLI to list available tools:
```bash
mcp list-tools --transport stdio --binary "python mirror_vectax_server.py"
```
This should output a list of all the tools provided by the server.
### Testing with MCP Inspector
We can use mcp inspector to test the tools:
```bash
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
### Customizing run_mcp_server.sh
If you need to modify the server startup configuration, you can edit the `run_mcp_server.sh` script. Here's what each line does:
```bash
#!/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
## Watch Video
[](./imgs/Mirror_MCP_Demo.mp4)
## Architecture
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.
## Test Prompts for Secure Embedding MCP Server
## Basic Functionality Tests
### 1. Test Basic Embedding
> 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._
### 2. Test Entity Detection
> 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._
### 3. Test Secure Processing
> 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._
### 4. Test Natural Language Processing
> 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._
## Advanced Functionality Tests
### 5. Test Batch Processing
> 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._
### 6. Test RBAC Functionality
> 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._
### 7. Test Search Functionality
> 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._
## Edge Cases and Error Testing
### 8. Test with Empty/Short Text
> Can you analyze this text: ""
_Expected outcome: Should handle empty input gracefully, possibly returning an error message or minimal analysis._
### 9. Test with Very Long Text
> 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._
### 10. Test with Multilingual Text
> 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._
## Complex Integration Tests
### 11. End-to-End Workflow Test
> 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._
### 12. Auto-Detection Test
> 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](Mirror_VectaX_MCP_func.md)
## Troubleshooting
### Common Issues
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
### Getting Help
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
