Tonic Textual MCP Server

An MCP (Model Context Protocol) server that connects AI assistants to Tonic Textual for PII detection and de-identification. It allows Claude and other MCP-compatible clients to redact sensitive data from text, files, and entire directories.

Key capabilities:

• Text redaction — Redact plain text, JSON, XML, and HTML with structure preservation
• File redaction — Process PDFs, Word docs, spreadsheets, and images while keeping original formatting
• Directory redaction — De-identify entire folder trees in a single call with automatic file type routing
• Dataset management — Create, upload to, and download from Textual datasets
• Fine-grained control — Per-entity redaction/synthesis config, deterministic replacements, allow/block lists, custom entity models, and 35+ built-in entity types across 50+ languages

Prerequisites

• Node.js >= 18.0.0
• A Tonic Textual instance (cloud or self-hosted)
• A Tonic Textual API key (how to create one)

Installation

From npm

npm install -g @tonicai/textual-mcp

From source

git clone https://github.com/TonicAI/textual-mcp.git
cd textual-mcp
npm install
npm run build

Configuration

The server is configured via environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | TONIC_TEXTUAL_API_KEY | Yes | — | Your Tonic Textual API key | | TONIC_TEXTUAL_BASE_URL | No | https://textual.tonic.ai | Base URL of your Textual instance | | PORT | No | 3000 | HTTP port for the MCP server | | TONIC_TEXTUAL_MAX_CONCURRENT_REQUESTS | No | 50 | Max concurrent requests to the Textual API | | TONIC_TEXTUAL_POLL_TIMEOUT_SECONDS | No | 900 | Timeout (in seconds) for polling file processing jobs | | TONIC_TEXTUAL_LOG_DIR | No | ./logs | Directory for structured log files |

Running the server

TONIC_TEXTUAL_API_KEY is required. For a self-hosted Textual instance, also set TONIC_TEXTUAL_BASE_URL.

Global install

# Tonic Textual cloud
TONIC_TEXTUAL_API_KEY=your-key textual-mcp

# Self-hosted instance
TONIC_TEXTUAL_API_KEY=your-key TONIC_TEXTUAL_BASE_URL=https://your-instance.example.com textual-mcp

From source

# Tonic Textual cloud
TONIC_TEXTUAL_API_KEY=your-key npm start

# Self-hosted instance
TONIC_TEXTUAL_API_KEY=your-key TONIC_TEXTUAL_BASE_URL=https://your-instance.example.com npm start

The server starts on http://localhost:3000/mcp by default. A health check endpoint is available at http://localhost:3000/health.

Adding to Claude

Note: You must start the MCP server before adding it to your Claude client. See Running the server above.

Claude Code

With the server running, register it as an HTTP transport:

claude mcp add --transport http textual-mcp http://localhost:3000/mcp

Claude Desktop

With the server running, add the following to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "textual-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Available tools

Text redaction

| Tool | Description | |---|---| | redact_text | Redact PII from a plain text string | | redact_bulk | Redact PII from multiple text strings in one call | | redact_json | Redact PII from a JSON string, preserving structure | | redact_xml | Redact PII from an XML string, preserving structure | | redact_html | Redact PII from an HTML string, preserving structure |

All text redaction tools support:

• generatorConfig — per-entity-type handling (e.g. {"NAME_GIVEN": "Synthesis", "US_SSN": "Redaction"})
• generatorDefault — default handling: Redaction, Synthesis, Off, GroupingSynthesis, or ReplacementSynthesis
• generatorMetadata — per-entity-type synthesis configuration (generator version, custom generators, deterministic swaps)
• customEntities — custom PII entity identifiers for detection
• labelBlockLists — regex/string patterns to exclude from detection per entity type
• labelAllowLists — regex/string patterns to force-detect per entity type

File redaction

| Tool | Description | |---|---| | redact_file | Redact PII from a binary file (PDF, docx, xlsx, images). Uploads, polls for completion, and saves the redacted version. | | download_redacted_file | Download a previously redacted file by job ID |

Directory redaction

| Tool | Description | |---|---| | scan_directory | Preview a directory tree before redaction (file types, sizes, counts) | | deidentify_folder | Redact an entire directory tree, preserving folder structure. Optionally redacts folder and file names. |

Dataset management

| Tool | Description | |---|---| | create_dataset | Create a new Textual dataset | | list_datasets | List all datasets | | get_dataset | Get dataset details including files and processing status | | upload_file_to_dataset | Upload a file to a dataset | | download_dataset_file | Download a redacted file from a dataset |

Job monitoring

| Tool | Description | |---|---| | list_file_jobs | List all unattached file redaction jobs with statuses | | get_file_job | Get status of a specific file redaction job | | get_job_error_logs | Download error logs for a failed job |

Reference

| Tool | Description | |---|---| | list_pii_types | List all PII entity types that Textual can detect |

Examples

Once the server is running and connected to your MCP client, you can interact with Textual using natural language.

Redact text

"Redact the PII from this text: John Smith lives at 123 Main St and his SSN is 456-78-9012"

Redact a PDF

"Redact all PII from /path/to/document.pdf and save it to /path/to/output.pdf"

Redact with synthesis

"Redact this text using synthesis for names and redaction for SSNs: John Smith's SSN is 456-78-9012"

The agent will call redact_text with generatorConfig: {"NAME_GIVEN": "Synthesis", "NAME_FAMILY": "Synthesis", "US_SSN": "Redaction"}.

De-identify a folder

"Scan /path/to/documents first, then de-identify the whole folder to /path/to/output, skipping any .log files"

Manage datasets

"Create a new dataset called 'training-data', upload all the files in /path/to/docs, and download the redacted versions when they're done"

Check job status

"List all file redaction jobs from the last hour"

Architecture

• HTTP streaming transport — Serves MCP over HTTP at /mcp with session management
• Concurrency control — Semaphore-based rate limiting prevents overwhelming the Textual API
• Background task processing — File uploads use the MCP task API for non-blocking operation with status polling
• Automatic retries — Transient network errors (ECONNRESET, ECONNREFUSED, EPIPE) are retried transparently
• Structured logging — Rotating JSON log files (per-date, 10MB rotation) for observability

Development

npm install
npm run dev     # watch mode — recompiles on changes
npm run build   # one-time build
npm start       # run the server
npm run clean   # remove compiled output

Resources

• Tonic Textual product documentation
• Textual REST API reference
• Textual Python SDK documentation
• Model Context Protocol specification

License

MIT