Appearance
MCP Server
GhostAI provides a Model Context Protocol (MCP) server that exposes PII protection capabilities as tools for AI assistants and automation platforms.
Overview
The GhostAI MCP server enables AI assistants like Cursor, Claude Desktop, and automation tools like n8n to:
- Detect PII in text before processing
- Sanitize sensitive data by replacing PII with tokens
- Restore original values after external processing
- Protected Chat with automatic end-to-end PII protection
- Scan Files for PII in documents, images, and code
Quick Start
Installation
bash
pip install ghostai-mcpOr from source:
bash
cd securechat/mcp
pip install -e .Configuration
Set environment variables:
bash
export GHOSTAI_BASE_URL=http://localhost:8000
export GHOSTAI_API_KEY=gst_your_api_key_here # Optional for local useRunning the Server
bash
ghostai-mcp
# or
python -m ghostai_mcpMCP Data Protection Gateway
The MCP Data Protection Gateway extends GhostAI's MCP server into an inline proxy that wraps upstream MCP servers with PII and secrets scanning.
Architecture
Agents connect to the GhostAI gateway instead of directly to upstream MCP servers. The gateway intercepts every tool call, scans for PII in both directions (outbound arguments and inbound responses), tokenizes sensitive data, and logs all transformations.
Agent (Cursor, Claude, CrewAI)
|
v
[GhostAI MCP Gateway]
| |
| PII scan | PII scan
| (outbound) | (inbound)
v v
[Upstream MCP Server 1] [Upstream MCP Server 2]
(filesystem) (database)Adding Upstream Servers
Upstream servers are added through the admin UI or API. GhostAI supports two connection modes:
URL mode — Paste a server URL. GhostAI auto-generates the mcp-remote bridge command:
bash
curl -X POST "$GHOSTAI_BASE_URL/api/mcp/servers" \
-H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Granola",
"endpoint": "https://mcp.granola.ai/mcp",
"classification": "internal"
}'Command mode — Specify the command and arguments directly:
bash
curl -X POST "$GHOSTAI_BASE_URL/api/mcp/servers" \
-H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Filesystem",
"endpoint": "stdio://npx",
"classification": "internal",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
}'Server Authentication
Many MCP servers (e.g., Granola, Notion) require authentication. GhostAI supports two methods:
Bearer token passthrough — If you have a pre-obtained API key or token, include it when adding the server:
bash
curl -X POST "$GHOSTAI_BASE_URL/api/mcp/servers" \
-H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Granola",
"endpoint": "https://mcp.granola.ai/mcp",
"classification": "internal",
"auth_token": "your-bearer-token"
}'The token is encrypted at rest (AES-256-GCM) and injected as --header Authorization:Bearer <token> when connecting. Raw tokens are never returned by the API; only has_auth_token: true/false is exposed.
Interactive OAuth — When a server requires OAuth and you don't have a pre-obtained token, GhostAI detects this automatically during the connection test. The test returns status: "auth_required" with the discovered OAuth server URL. The admin UI shows an "Authorize" button that opens a browser popup for the OAuth consent flow (PKCE + Dynamic Client Registration).
POST /api/mcp/servers/{server_name}/authorize
→ { "authorize_url": "https://mcp-auth.example.com/authorize?client_id=...&code_challenge=..." }After consent, the callback at /api/mcp/oauth/callback exchanges the authorization code for tokens, encrypts them, and stores them with the server.
Testing Connections
After adding a server, test the connection to verify tool discovery:
bash
curl -X POST "$GHOSTAI_BASE_URL/api/mcp/servers/{server_name}/test" \
-H "Authorization: Bearer $GHOSTAI_API_KEY"Returns one of three statuses:
connected— tools discovered successfullyauth_required— server requires OAuth authenticationerror— connection failed (timeout, command not found, etc.)
Editing Servers
Update an existing server's endpoint, data sensitivity, or authentication token:
bash
curl -X PUT "$GHOSTAI_BASE_URL/api/mcp/servers/{server_name}" \
-H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"endpoint": "https://mcp.granola.ai/mcp",
"classification": "confidential",
"auth_token": "new-bearer-token"
}'All fields are optional — include only the ones you want to change. When the endpoint changes on a URL-mode server, the mcp-remote bridge command and args are regenerated automatically.
Toggling Individual Tools
Enable or disable a specific tool on a connected server:
bash
curl -X PUT "$GHOSTAI_BASE_URL/api/mcp/servers/{server_name}/tools/{tool_name}/enabled" \
-H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "enabled": false }'Disabled tools are excluded from the LLM's available tools and will not appear in the chat toolbar.
DataIntel Scanning Profiles
List auto-seeded scanning profiles for all discovered MCP tools:
bash
curl "$GHOSTAI_BASE_URL/api/mcp/profiles" \
-H "Authorization: Bearer $GHOSTAI_API_KEY"Returns an array of profiles:
json
[
{
"id": "profile_abc123",
"tool_name": "get_meetings",
"server_name": "Granola",
"auto_risk": "medium",
"override_risk": null,
"enabled": true
}
]Update a profile's risk level override:
bash
curl -X PUT "$GHOSTAI_BASE_URL/api/mcp/profiles/{profile_id}" \
-H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "override_risk": "high" }'Gateway Configuration (File-Based)
For self-hosted deployments, you can also configure the gateway via a gateway.json file:
json
{
"upstream_servers": [
{
"name": "Patient DB",
"command": "npx",
"args": ["@mcp/server-postgres", "postgresql://..."],
"classification": "regulated"
},
{
"name": "Filesystem",
"command": "npx",
"args": ["@modelcontextprotocol/server-filesystem", "/data"],
"classification": "internal"
}
],
"default_scan_depth": "standard"
}bash
GHOSTAI_GATEWAY_CONFIG=gateway.json ghostai-mcp-gatewayDataIntel Context-Aware Scanning
DataIntel adjusts PII detection depth per tool call based on three signals:
| Signal | Description | Effect |
|---|---|---|
| Tool risk profile | Auto-classified from tool name (low/medium/high/critical) | Higher risk = deeper scan |
| Data source classification | Upstream server tag (public/internal/confidential/regulated) | Regulated sources get maximum scanning |
| Admin override | Per-tool manual risk assignment | Overrides auto-classification |
Scan depth levels:
| Depth | Latency | Detectors |
|---|---|---|
| Light | <5ms | Pattern matching only |
| Standard | 10-30ms | Patterns + NER |
| Deep | 30-80ms | Patterns + NER + AI verification |
| Maximum | 80-200ms | All detectors + vertical-specific + anti-exfiltration |
Gateway Audit Trail
Every tool call produces an audit entry:
json
{
"timestamp": "2026-03-12T12:34:56Z",
"tool_name": "query_patients",
"upstream_server": "Patient DB",
"direction": "inbound",
"pii_detected": 3,
"pii_types": ["SSN", "PERSON_NAME", "DATE_OF_BIRTH"],
"action": "tokenized",
"scan_depth": "maximum",
"scan_duration_ms": 45
}The action field reflects the enforcement outcome: tokenized, passed, warned, or blocked. Blocked tool calls (rejected by a security policy) are also logged, ensuring full visibility into denied requests.
Export audit data via the admin UI (CSV, PDF) or the /api/mcp/audit endpoint (JSON).
Client Configuration
Cursor IDE
Add to .cursor/mcp.json in your project:
json
{
"mcpServers": {
"ghostai": {
"command": "ghostai-mcp",
"env": {
"GHOSTAI_BASE_URL": "http://localhost:8000",
"GHOSTAI_API_KEY": "gst_your_key_here"
}
}
}
}Claude Desktop
Add to ~/.config/claude/config.json (Linux/Mac) or %APPDATA%\Claude\config.json (Windows):
json
{
"mcpServers": {
"ghostai": {
"command": "ghostai-mcp",
"env": {
"GHOSTAI_API_KEY": "gst_your_key_here"
}
}
}
}OpenClaw
Add to openclaw.json:
json
{
"mcp": {
"ghostai": {
"command": "ghostai-mcp",
"env": {
"GHOSTAI_BASE_URL": "https://your-ghostai-instance.com",
"GHOSTAI_API_KEY": "${GHOSTAI_API_KEY}"
}
}
}
}This gives OpenClaw agents access to all GhostAI MCP tools for on-demand PII detection and file scanning. For automatic PII protection on every message, also configure GhostAI as a custom provider.
n8n
Use the MCP node with:
- Command:
ghostai-mcp - Environment Variables: Set
GHOSTAI_BASE_URLandGHOSTAI_API_KEY
Available Tools
ghostai_detect_pii
Detect PII in text without modifying it. Returns detected entities with types, confidence scores, and compliance tags.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Text to scan for PII |
vertical | string | No | Industry vertical: healthcare, financial, legal, government, technology, automotive, consumer, education, retail, manufacturing |
Example:
json
// Input
{
"text": "Contact John Smith at john.smith@acme.com or 555-123-4567"
}
// Output
{
"pii_detected": [
{
"type": "PERSON",
"value": "John Smith",
"start": 8,
"end": 18,
"confidence": 0.98,
"compliance_tags": ["PII"]
},
{
"type": "EMAIL",
"value": "john.smith@acme.com",
"start": 22,
"end": 41,
"confidence": 0.99,
"compliance_tags": ["PII", "CONTACT_INFO"]
},
{
"type": "PHONE_NUMBER",
"value": "555-123-4567",
"start": 45,
"end": 57,
"confidence": 0.95,
"compliance_tags": ["PII", "CONTACT_INFO"]
}
],
"sanitized_text": "Contact [PERSON_1] at [EMAIL_1] or [PHONE_1]"
}ghostai_sanitize
Replace PII with secure tokens. Returns sanitized text and a session ID for later restoration.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Text to sanitize |
session_id | string | No | Session ID for token continuity across calls |
Example:
json
// Input
{
"text": "Patient John Doe, SSN 123-45-6789, was seen on 01/15/2024"
}
// Output
{
"sanitized_text": "Patient [PERSON_1], SSN [SSN_1], was seen on [DATE_1]",
"session_id": "sess_abc123def456",
"pii_detected": [
{"type": "PERSON", "value": "John Doe"},
{"type": "US_SSN", "value": "123-45-6789"},
{"type": "DATE", "value": "01/15/2024"}
],
"entity_count": 3
}ghostai_restore
Restore original PII values from tokens. Requires the session ID from sanitization.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Tokenized text to restore |
session_id | string | Yes | Session ID from sanitization |
Example:
json
// Input
{
"text": "Patient [PERSON_1] was discharged on [DATE_1]",
"session_id": "sess_abc123def456"
}
// Output
{
"restored_text": "Patient John Doe was discharged on 01/15/2024",
"tokens_replaced": 2
}ghostai_chat
Send a chat message with automatic PII protection. PII is tokenized before sending to the LLM and optionally detokenized in the response.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
message | string | Yes | User message |
model | string | No | Model to use (uses default if not specified) |
session_id | string | No | Session ID for conversation continuity |
detokenize | boolean | No | Restore PII in response (default: true) |
Example:
json
// Input
{
"message": "Summarize the case for patient John Doe, DOB 01/15/1980",
"model": "openai/gpt-4o"
}
// Output
{
"response": "Patient John Doe (DOB: 01/15/1980) presents with...",
"model": "openai/gpt-4o",
"session_id": "sess_xyz789",
"pii_detected": [
{"type": "PERSON", "value": "John Doe"},
{"type": "DATE_OF_BIRTH", "value": "01/15/1980"}
],
"sanitized_prompt": "Summarize the case for patient [PERSON_1], DOB [DOB_1]"
}ghostai_scan_file
Scan a file for PII. Supports documents, images (OCR), code files, and archives.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
file_path | string | Yes | Path to file to scan |
vertical | string | No | Industry vertical for compliance context |
Supported formats:
- Documents: PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx)
- Images: JPEG, PNG, GIF, WebP (uses OCR)
- Code: Python, JavaScript, TypeScript, Java, Go, Rust, and 30+ languages
- Archives: ZIP, 7z, RAR (scans contents)
- Medical: DICOM, HL7
Example:
json
// Input
{
"file_path": "/path/to/patient-records.pdf",
"vertical": "healthcare"
}
// Output
{
"file_id": "file_abc123",
"filename": "patient-records.pdf",
"pii_detected": true,
"entities": [
{"type": "PERSON", "value": "Jane Smith", "page": 1},
{"type": "US_SSN", "value": "987-65-4321", "page": 2},
{"type": "MEDICAL_RECORD", "value": "MRN-12345", "page": 1}
],
"entity_count": 3,
"compliance_tags": ["HIPAA", "PHI", "PII"]
}ghostai_list_sessions
List active tokenization sessions with metadata.
Parameters: None
Example:
json
// Output
{
"sessions": [
{
"session_id": "sess_abc123",
"created_at": "2024-01-15T10:30:00Z",
"message_count": 5,
"title": "Patient consultation"
},
{
"session_id": "sess_def456",
"created_at": "2024-01-15T11:00:00Z",
"message_count": 3,
"title": "Contract review"
}
],
"total": 2
}ghostai_tokenize
Tokenize text by replacing PII with secure tokens. This is an explicit alias for ghostai_sanitize with clearer naming for tokenization workflows.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Text to tokenize |
session_id | string | No | Session ID for token continuity across calls |
Example:
json
// Input
{
"text": "Contact john@example.com for support"
}
// Output
{
"tokenized_text": "Contact [EMAIL_ADDRESS_a1b2c3d4] for support",
"session_id": "sess_xyz789",
"entities": [
{"type": "EMAIL_ADDRESS", "value": "john@example.com"}
],
"entity_count": 1
}ghostai_detokenize
Restore original PII values from tokenized text. This is an explicit alias for ghostai_restore with clearer naming for detokenization workflows.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Tokenized text to restore |
session_id | string | Yes | Session ID from tokenization |
Example:
json
// Input
{
"text": "Contact [EMAIL_ADDRESS_a1b2c3d4] for support",
"session_id": "sess_xyz789"
}
// Output
{
"restored_text": "Contact john@example.com for support",
"tokens_replaced": 1
}ghostai_scan_secrets
Scan text for secrets, API keys, tokens, and credentials (20+ types). Returns detected items with types, masked values, confidence, severity, and line numbers when applicable.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Text to scan for secrets |
filename | string | No | Optional filename for context (for example .env enables enhanced scanning) |
Dymium data tools (ghostai_data_query, ghostai_data_sources, ghostai_bi_insight)
These tools connect to governed enterprise data via the Dymium platform when it is configured for your tenant. They are registered alongside the core PII tools; availability depends on GhostAI/Dymium integration for your organization.
Use Cases
Healthcare: HIPAA-Compliant AI Analysis
1. User asks AI to analyze patient notes
2. AI calls ghostai_sanitize → PHI replaced with tokens
3. Sanitized text sent to external analytics service
4. Results returned with tokens
5. AI calls ghostai_restore → Original PHI restored for userLegal: Document Review Workflow
1. User uploads contract for review
2. AI calls ghostai_scan_file → Identifies PII in document
3. AI calls ghostai_sanitize on extracted text
4. Safe text sent for analysis
5. ghostai_restore brings back original names, dates, amountsFinance: Secure Data Processing
1. User asks about transaction for "John Doe, account 1234567890"
2. AI calls ghostai_chat → PII automatically protected
3. LLM never sees real account number
4. Response detokenized before showing to userAutomation: n8n PII Protection Workflow
[Webhook Trigger] → [GhostAI Sanitize] → [External API] → [GhostAI Restore] → [Output]Error Handling
The MCP server returns errors in the standard format:
json
{
"error": "Session not found",
"code": "SESSION_NOT_FOUND"
}Common error codes:
SESSION_NOT_FOUND: Invalid or expired session IDFILE_NOT_FOUND: File path doesn't existAUTHENTICATION_FAILED: Invalid API keyRATE_LIMITED: Too many requests
Security Considerations
API Keys: Always use API keys in production. Create scoped keys with minimal permissions.
Session Lifetime: Sessions expire after inactivity. Plan workflows to complete within session lifetime.
File Access: The MCP server can only access files the host process can read. Sensitive files should have appropriate permissions.
Network Security: Use HTTPS in production. The MCP server communicates with the GhostAI backend over HTTP/HTTPS.
Troubleshooting
"Connection refused"
Ensure GhostAI backend is running:
bash
cd securechat && ./start.sh"Authentication failed"
Check your API key:
bash
echo $GHOSTAI_API_KEY"Tool not found"
Restart your MCP client to reload tool definitions.
Logs
Enable debug logging:
bash
export GHOSTAI_DEBUG=1
ghostai-mcp