Delphix DCT MCP Server

The Delphix DCT MCP Server provides a robust Model Context Protocol (MCP) interface for interacting with the Delphix Data Control Tower (DCT) API. This service enables AI assistants and client applications to securely access test data management capabilities through a structured toolset.

Table of Contents

• Features
• Quick Start
• Videos
• Environment Variables
• MCP Client Configuration
• Advanced Installation
• Toolsets
• Available Tools
• Privacy & Telemetry
• Troubleshooting
• Project Structure
• License
• Support & Contributing

Features

• Dynamic Mode: Default 2-tool mode (discovery + execute) that exposes the full DCT API driven by the live OpenAPI spec.
• Persona-Based Toolsets: Choose from 5 pre-configured toolsets tailored for different roles (Self-Service, Self-Service Provisioning, Continuous Data Admin, Platform Admin, Reporting & Insights).
• Grouped Tools: Each tool handles multiple related actions via an action parameter, reducing tool count while maintaining full functionality.
• Confirmation System: Built-in confirmation checks for destructive operations to prevent accidental data loss.
• Comprehensive DCT integration: Access datasets, environments, engines, compliance, jobs, and reporting through specialized tools.
• Security and reliability: API client includes retry logic, exponential backoff, and SSL configuration.
• Flexible configuration: Environment-based setup with validation.
• Cross-platform support: Startup scripts for Windows, macOS, and Linux.
• Structured logging: Application and session logging with telemetry tracking.
• Telemetry (Optional): Usage analytics are disabled by default and require user consent.

Quick Start

Configure the MCP server within your AI client application (such as Claude Desktop, Cursor, or VS Code). This is the recommended method and does not require separate installation.

What you need:

• Delphix DCT Instance: Running Delphix Data Control Tower instance
• API Key: Valid DCT API key with the following READ permissions:
  • VDBs
  • VDB Groups
  • dSources
  • Environments
  • Bookmarks
  • Snapshots
  • Data Connections
  • Engines
  • Virtualization and Compliance Job Executions
  • All Virtualization Storage Insights
• uv (recommended): Install using uv. This method provides access to the uvx command.
• OR Python 3.11+: If not using uv/uvx

Next step: Proceed to MCP Client Configuration to complete setup.

Alternative: To run the server as a standalone command-line tool or contribute to development, see Advanced Installation.

Videos

Watch these videos to see the MCP Server in action:

• General overview of the MCP Server
• Claude App configuration and sample usage
• Visual Studio Code configuration and sample usage

Environment Variables

All configuration methods use these environment variables:

• DCT_API_KEY - Your Delphix DCT API key (required).

  Do not prefix with apk. Use the key exactly as provided by DCT. Example: 2.123abc...

• DCT_BASE_URL - Your DCT instance URL (required).

  Do not append with /dct. Example: https://dct-hostname.com

• DCT_VERIFY_SSL - Enable SSL verification (true/false, default: false)

• DCT_LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

• DCT_TIMEOUT - Request timeout in seconds (default: 30)

• DCT_MAX_RETRIES - Maximum retry attempts (default: 3)

• DCT_TOOLSET - Toolset to load (see Toolsets section below)

  • dynamic (default) - 2-tool mode (discovery + execute) driven by the live DCT OpenAPI spec
  • self_service - Basic VDB operations (7 tools)
  • self_service_provision - Self-service + provisioning (14 tools)
  • continuous_data_admin - Full DBA operations (22 tools)
  • platform_admin - System administration (13 tools)
  • reporting_insights - Read-only reporting (13 tools)

• IS_LOCAL_TELEMETRY_ENABLED - Enable telemetry (true/false, default: false)

MCP Client Configuration

Note: Use absolute paths for the command field in all configurations. Ensure environment variables are set for each client application.

Configuration examples for popular MCP clients are provided below. The structure may vary (some use mcpServers, others use servers).

Configuration Methods

All clients support three installation methods:

• Using uvx (Recommended):

  Requires uv. Handles dependencies automatically.

• Using Python directly:

  Point to the main.py file in your local repository clone.

• Using shell/batch scripts

  Use provided startup scripts (_python.sh for Linux/macOS, _python.bat for Windows). The _uv.sh and _uv.bat scripts require uv.

See below for the full JSON configuration examples for each client.

---

Advanced Installation

For running as a standalone command-line tool or contributing to development.

Most users should use the MCP Client Configuration above instead.

Setting Environment Variables

For standalone installation, set the environment variables in your shell before running the server.

Quick Start (Command-Line Tool)

Recommended method for users who want to use the server without modifying its code.

Prerequisites:

• Python 3.11+
• pip and git installed on your system
• Environment variables configured in your shell. See above examples.

Install the server directly from GitHub using pip:

pip install git+https://github.com/delphix/dxi-mcp-server.git

# Verify the installation
dct-mcp-server --help

This makes the dct-mcp-server command available globally in your environment.

Developer Setup

Method for developers who want to modify the code or run it from a local clone.

Prerequisites:

• Python 3.11+
• git installed on your system
• Environment variables configured in your shell. See above examples.

Steps:

1. Clone the repository:

   git clone https://github.com/delphix/dxi-mcp-server.git
   cd dxi-mcp-server
   

2. Set up the environment and install dependencies:

   The included scripts handle environment setup automatically. We recommend using uv (which provides uvx) for the best performance:

   Linux/macOS:

   chmod +x start_mcp_server_uv.sh
   ./start_mcp_server_uv.sh
   

   Windows:

   start_mcp_server_windows_uv.bat
   

   Note: If you prefer not to use uv, scripts for standard Python with venv are also provided (start_mcp_server_python.sh and start_mcp_server_windows_python.bat).

Connecting a Client to a Running Server

Once the server is running (either via the command-line tool or from the source), it will print the port it is listening on to the console (e.g., INFO: Uvicorn running on http://127.0.0.1:6790 (Press CTRL+C to quit)).

To connect your client, you only need to specify this port number. You do not need to provide environment variables in the client configuration, as the server already has them from your terminal session.

Example for Claude Desktop:

{
  "mcpServers": {
    "delphix-dct": {
      "port": 6790
    }
  }
}

Note: You can configure other MCP clients similarly by providing the port number. This method is ideal for development, as it allows you to restart the server without reconfiguring or restarting your client application. For troubleshooting, all log files can be found in the logs directory created in the project root.

Toolsets

The server organizes tools into persona-based toolsets designed for specific roles and use cases. Each toolset provides a curated set of grouped tools.

Available Toolsets

Fixed Toolset Mode

For environments where you always need the same toolset, set it directly:

{
  "env": {
    "DCT_TOOLSET": "self_service"
  }
}

This pre-registers all tools at startup.

Grouped Tools

Each tool in a toolset handles multiple related actions via an action parameter:

# Instead of calling separate tools:
search_vdbs(filter_expression="...")
get_vdb(vdbId="...")
refresh_vdb_by_timestamp(vdbId="...", timestamp="...")

# Call one grouped tool with different actions:
vdb_tool(action="search_vdbs", filter_expression="...")
vdb_tool(action="get_vdb", vdbId="...")
vdb_tool(action="refresh_vdb_by_timestamp", vdbId="...", timestamp="...")

This reduces tool count while maintaining full functionality.

Confirmation for Destructive Operations

Destructive operations (delete, disable, etc.) require explicit confirmation:

# First call returns confirmation requirement
vdb_tool(action="delete_vdb", vdbId="vdb-123")
# Response: {"status": "confirmation_required", "confirmation_level": "manual", ...}

# Confirm by setting confirmed=True
vdb_tool(action="delete_vdb", vdbId="vdb-123", confirmed=True)
# Response: {"status": "success", ...}

Upgrade note: renamed tools and actions (2026.1.0.0)

Breaking change, no compatibility aliases. Persona-toolset tools and actions whose names carried retired terminology were renamed, and the old names are gone. Scripts, saved prompts, agent configurations and tests that call them by name must be updated. DCT API paths are unchanged, and the default dynamic toolset (discovery / execute) is not affected.

Available Tools

The tools available depend on the configured toolset. Below are the grouped tools for each toolset.

continuous_data_admin Toolset (22 Tools)

self_service Toolset (7 Tools)

self_service_provision Toolset (14 Tools)

Inherits all tools from self_service with extended capabilities, plus additional tools.

platform_admin Toolset (13 Tools)

reporting_insights Toolset (13 Tools)

All tools in this toolset are read-only for monitoring and reporting.

Legacy Tool Reference

The following documents the individual endpoint tools (used in older versions):

Dataset Management Tools

Environment Management Tools

Engine Administration Tools

Compliance & Security Tools

Job Monitoring Tools

Reporting & Analytics Tools

Common Tool Features

All tools support:

• Advanced Filtering: Complex filter expressions using comparison operators (EQ, NE, GT, LT, CONTAINS, IN) and logical operators (AND, OR, NOT)
• Flexible Pagination: Control result sets with limit and cursor parameters
• Smart Sorting: Sort results by any available field in ascending or descending order
• Comprehensive Search: Use the SEARCH operator to find items across multiple attributes
• Error Handling: Detailed error responses with actionable troubleshooting information

Filter Expression Examples

# Find active Oracle databases
"filter_expression": "platform EQ 'oracle' AND status EQ 'ACTIVE'"

# Search for large datasets (> 100GB)
"filter_expression": "size GT 107374182400"

# Find resources with specific tags
"filter_expression": "tags CONTAINS 'production'"

# Complex logical expressions
"filter_expression": "NOT (status EQ 'INACTIVE') AND (platform IN ['oracle', 'postgresql'])"

Privacy & Telemetry

When IS_LOCAL_TELEMETRY_ENABLED is set to true, the server collects anonymous usage analytics to improve functionality and user experience.

What Data is Collected

• Tool execution details: Tool name, execution status (success or failure), and session duration
• User identifier: Operating system username (via getpass.getuser()) for usage analysis
• Error context: Anonymized error types and frequencies (no sensitive data)
• Performance metrics: Execution times and resource usage

What is NOT Collected

• Sensitive data: No API keys, database content, or business data
• Personal information: No personally identifiable information beyond OS username
• DCT data: No data returned from DCT API calls
• Network details: No IP addresses or network configurations

Data Storage & Privacy

• Local only: Telemetry data is stored in the logs/sessions/ directory
• No remote transmission: Data never leaves your machine
• User control: Disable telemetry by setting IS_LOCAL_TELEMETRY_ENABLED="false"
• Readable format: Logs use human-readable JSON

Sample Telemetry Entry

{
  "session_id": "abc123",
  "timestamp": "2025-12-05T10:30:00Z",
  "user": "developer",
  "tool": "get_datasets",
  "status": "success",
  "duration_ms": 245,
  "args_count": 3
}

Troubleshooting

Common Issues

Connection Errors

# Check DCT connectivity
curl -k -H "Authorization: Bearer $DCT_API_KEY" "$DCT_BASE_URL/v1/about"

# Verify SSL settings
export DCT_VERIFY_SSL="false"  # For self-signed certificates

Authentication Failures

# Verify API key is set
echo $DCT_API_KEY  # Should be your DCT API key (do NOT add 'apk' prefix)

# Check API key permissions in DCT admin console

Tool Generation Issues

# Enable debug logging
export DCT_LOG_LEVEL="DEBUG"

# Check DCT API accessibility
curl -k "$DCT_BASE_URL/v1/about"

MCP Client Connection Issues

# Test server startup
./start_mcp_server_python.sh

# Verify Python path
export PYTHONPATH=src
python -c "import dct_mcp_server; print('Import successful')"

Debug Mode

Enable comprehensive debugging:

export DCT_LOG_LEVEL="DEBUG"
export IS_LOCAL_TELEMETRY_ENABLED="true"
./start_mcp_server_python.sh 2>&1 | tee debug.log

Log Analysis

By default, all log files are generated in a logs directory. The location depends on how the server is started:

• Local development: When you run the server from the cloned source code, the logs directory is created at the root of the project.
• Client application: When an MCP client starts the server, the logs directory is typically created at the root of the workspace or project folder you have open in that client.

Check these logs for issues:

# Main application logs
tail -f logs/dct_mcp_server.log

# Session telemetry
ls -la logs/sessions/

# Startup logs
cat logs/mcp_server_setup_logfile.txt

“Server starting…” followed by “No such file or directory” or “command not found”

• Cause: This happens when the command path in your MCP client’s JSON configuration is incorrect. The client optimistically reports that it is “starting” the server, but then the operating system immediately fails because it cannot find the script at the specified location.
• Solution: Ensure the command value is the absolute path to the correct startup script (e.g., start_mcp_server_uv.sh or start_mcp_server_python.sh). Verify that the file exists at that exact path and that it has execute permissions (chmod +x ).

Project Structure

dxi-mcp-server/
├── README.md                   # This file
├── LICENSE.md                  # MIT license
├── pyproject.toml              # Python project configuration
├── requirements.txt            # Dependencies (legacy format)
├── uv.lock                     # Locked dependencies (uv format)
├── start_mcp_server_*.{sh,bat} # Cross-platform startup scripts
├── logs/                       # Runtime logs and telemetry
│   ├── dct_mcp_server.log      # Main application logs
│   └── sessions/               # Telemetry session logs
└── src/
    └── dct_mcp_server/
        ├── main.py             # Application entry point
        ├── config/
        │   ├── config.py       # Configuration management
        │   ├── loader.py       # Toolset configuration loader
        │   ├── toolsets/       # Toolset definitions
        │   │   ├── self_service.txt          # Default toolset (6 tools)
        │   │   ├── self_service_provision.txt
        │   │   ├── continuous_data_admin.txt
        │   │   ├── platform_admin.txt
        │   │   └── reporting_insights.txt
        │   └── mappings/       # Confirmation rules
        │       └── manual_confirmation.txt
        ├── core/
        │   ├── decorators.py   # Logging and telemetry decorators
        │   ├── exceptions.py   # Custom exception classes
        │   ├── logging.py      # Logging configuration
        │   └── session.py      # Session and telemetry management
        ├── dct_client/
        │   └── client.py       # DCT API HTTP client
        ├── tools/
        │   ├── core/           # Tool generation framework
        │   │   ├── meta_tools.py   # Retained spec helpers (find_endpoint, get_spec_chunk)
        │   │   └── tool_factory.py # Dynamic tool generator
        │   ├── dataset_endpoints_tool.py   # VDBs, VDB groups, dSources, snapshots, bookmarks
        │   ├── engine_endpoints_tool.py    # Engine management
        │   ├── environment_endpoints_tool.py  # Environments, sources, toolkits
        │   ├── iam_endpoints_tool.py       # Accounts, roles, access-groups, tags
        │   ├── job_endpoints_tool.py       # Job monitoring
        │   ├── misc_endpoints_tool.py      # Admin/platform, vaults, diagnostics
        │   ├── policy_endpoints_tool.py    # Replication and virtualization policies
        │   ├── reports_endpoints_tool.py   # Reporting and analytics
        │   └── template_endpoints_tool.py  # Database and hook templates
        ├── toolsgenerator/
        │   └── driver.py       # OpenAPI-driven tool code generator
        └── icons/
            └── logo-delphixmcp-reg.png

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Support & Contributing

Getting Help

1. Check the logs: Review logs/dct_mcp_server.log for error details.
2. Enable debug mode: Set DCT_LOG_LEVEL="DEBUG" for verbose output.
3. Search existing issues: Check GitHub Issues for similar problems.
4. Create a new issue: Provide DCT version, Python version, and error logs.

Community Resources

• Issues: Report bugs and request features on GitHub Issues
• Documentation: Full documentation available in the project wiki
• Community support: - Community-driven support
• Delphix DCT API documentation: Official API docs

Contributing

We welcome contributions! Please review our community documents:

• Community Guidelines: An overview of how our community operates.
• Code of Conduct: Our commitment to a respectful and inclusive environment.
• Contributing Guidelines: The technical guide on how to contribute to this project.

When you are ready to submit a change, please use our Pull Request Template.

---

Enable your AI assistants to seamlessly manage your data infrastructure with Delphix DCT.