Skip to content

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-mcp

Or 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 use

Running the Server ​

bash
ghostai-mcp
# or
python -m ghostai_mcp

MCP 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 successfully
  • auth_required — server requires OAuth authentication
  • error — 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-gateway

DataIntel Context-Aware Scanning ​

DataIntel adjusts PII detection depth per tool call based on three signals:

SignalDescriptionEffect
Tool risk profileAuto-classified from tool name (low/medium/high/critical)Higher risk = deeper scan
Data source classificationUpstream server tag (public/internal/confidential/regulated)Regulated sources get maximum scanning
Admin overridePer-tool manual risk assignmentOverrides auto-classification

Scan depth levels:

DepthLatencyDetectors
Light<5msPattern matching only
Standard10-30msPatterns + NER
Deep30-80msPatterns + NER + AI verification
Maximum80-200msAll 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_URL and GHOSTAI_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:

ParameterTypeRequiredDescription
textstringYesText to scan for PII
verticalstringNoIndustry 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:

ParameterTypeRequiredDescription
textstringYesText to sanitize
session_idstringNoSession 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:

ParameterTypeRequiredDescription
textstringYesTokenized text to restore
session_idstringYesSession 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:

ParameterTypeRequiredDescription
messagestringYesUser message
modelstringNoModel to use (uses default if not specified)
session_idstringNoSession ID for conversation continuity
detokenizebooleanNoRestore 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:

ParameterTypeRequiredDescription
file_pathstringYesPath to file to scan
verticalstringNoIndustry 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:

ParameterTypeRequiredDescription
textstringYesText to tokenize
session_idstringNoSession 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:

ParameterTypeRequiredDescription
textstringYesTokenized text to restore
session_idstringYesSession 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:

ParameterTypeRequiredDescription
textstringYesText to scan for secrets
filenamestringNoOptional 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 user
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, amounts

Finance: 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 user

Automation: 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 ID
  • FILE_NOT_FOUND: File path doesn't exist
  • AUTHENTICATION_FAILED: Invalid API key
  • RATE_LIMITED: Too many requests

Security Considerations ​

  1. API Keys: Always use API keys in production. Create scoped keys with minimal permissions.

  2. Session Lifetime: Sessions expire after inactivity. Plan workflows to complete within session lifetime.

  3. File Access: The MCP server can only access files the host process can read. Sensitive files should have appropriate permissions.

  4. 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

SOC 2 Type II Certified | BAA Available | HIPAA-Ready