Deephaven MCP

MCP servers for Deephaven to orchestrate data workers and power documentation Q&A with LLMs, enabling AI-driven data workflows.

View on GitHub →

deephaven-mcp

PyPI License GitHub Workflow Status

Table of Contents

Overview

Deephaven MCP, which implements the Model Context Protocol (MCP) standard, provides tools to orchestrate, inspect, and interact with Deephaven Community Core servers, and to access conversational documentation via LLM-powered Docs Servers. It's designed for data scientists, engineers, and anyone looking to leverage Deephaven's capabilities through programmatic interfaces or integrated LLM tools.

Deephaven MCP Components

Systems Server

Manages and connects to multiple Deephaven Community Core worker nodes and Deephaven Enterprise systems. This allows for unified control and interaction with your Deephaven instances from various client applications.

Key Capabilities:

  • Session Management: List, monitor, and get detailed status of all configured Deephaven sessions
  • Enterprise Systems: Connect to and manage Deephaven Enterprise (CorePlus) deployments
  • Table Operations: Retrieve table schemas and metadata from any connected session
  • Script Execution: Run Python or Groovy scripts directly on Deephaven sessions
  • Package Management: Query installed Python packages in session environments
  • Configuration Management: Dynamically reload and refresh session configurations

Docs Server

Provides access to an LLM-powered conversational Q&A interface for Deephaven documentation. Get answers to your Deephaven questions in natural language.

Key Use Cases

  • AI-Assisted Development: Integrate Deephaven with LLM-powered development tools (e.g., Claude Desktop, GitHub Copilot) for AI-assisted data exploration, code generation, and analysis.
  • Multi-Environment Management: Programmatically manage and query multiple Deephaven Community and Enterprise deployments from a single interface.
  • Interactive Documentation: Quickly find information and examples from Deephaven documentation using natural language queries.
  • Script Automation: Execute Python or Groovy scripts across multiple Deephaven sessions for data processing workflows.
  • Schema Discovery: Automatically retrieve and analyze table schemas from connected Deephaven instances.
  • Environment Monitoring: Monitor session health, package versions, and system status across your Deephaven infrastructure.

Architecture Diagrams

Systems Server Architecture

graph TD
    A["MCP Clients (Claude Desktop, etc.)"] --"stdio (MCP)"--> B("MCP Systems Server")
    B --"Manages"--> C("Deephaven Community Core Worker 1")
    B --"Manages"--> D("Deephaven Community Core Worker N")
    B --"Manages"--> E("Deephaven Enterprise System 1")
    B --"Manages"--> F("Deephaven Enterprise System N")
    E --"Manages"--> G("Enterprise Worker 1.1")
    E --"Manages"--> H("Enterprise Worker 1.N")
    F --"Manages"--> I("Enterprise Worker N.1")
    F --"Manages"--> J("Enterprise Worker N.N")

Clients connect to the MCP Systems Server, which in turn manages and communicates with Deephaven Community Core workers and Deephaven Enterprise systems.

Docs Server Architecture

graph TD
    A["MCP Clients with streamable-http support"] --"streamable-http (direct)"--> B("MCP Docs Server")
    C["MCP Clients without streamable-http support"] --"stdio"--> D["mcp-proxy"]
    D --"streamable-http"--> B
    B --"Accesses"--> E["Deephaven Documentation Corpus via Inkeep API"]

Modern MCP clients can connect directly via streamable-http for optimal performance. Clients without native streamable-http support can use mcp-proxy to bridge stdio to streamable-http.

Prerequisites

Installation & Initial Setup

The recommended way to install deephaven-mcp is from PyPI. This provides the latest stable release and is suitable for most users.

Installing from PyPI (Recommended for Users)

Choose one of the following Python environment and package management tools:

Option A: Using uv (Fast, Recommended)

If you have uv installed (or install it via pip install uv):

  1. Create and activate a virtual environment with your desired Python version: uv works best when operating within a virtual environment. To create one (e.g., named .venv) using a specific Python interpreter (e.g., Python 3.9), run:

    uv venv .venv -p 3.9

    Replace 3.9 with your target Python version (e.g., 3.10, 3.11) or the full path to a Python executable. Then, activate it:

    • On macOS/Linux: source .venv/bin/activate
    • On Windows (PowerShell): .venv\Scripts\Activate.ps1
    • On Windows (CMD): .venv\Scripts\activate.bat

  2. Install deephaven-mcp:

    uv pip install deephaven-mcp

This command installs deephaven-mcp and its dependencies into the active virtual environment. If you skipped the explicit virtual environment creation step above, uv might still create or use one automatically (typically .venv in your current directory if UV_AUTO_CREATE_VENV is not false, or a globally managed one). In any case where a virtual environment is used (either explicitly created or automatically by uv), ensure it remains active for manual command-line use of dh-mcp-systems-server or dh-mcp-docs-server, or if your LLM tool requires an active environment.

Option B: Using Standard pip and venv

  1. Create a virtual environment (e.g., named .venv): 
    python -m venv .venv
  2. Activate the virtual environment:
    • On macOS/Linux: 
      source .venv/bin/activate
    • On Windows (Command Prompt/PowerShell): 
      .venv\Scripts\activate
  3. Install deephaven-mcp into the activated virtual environment: 
    pip install deephaven-mcp
    Ensure this virtual environment is active in any terminal session where you intend to run dh-mcp-systems-server or dh-mcp-docs-server manually, or if your LLM tool requires an active environment when spawning these processes.

Configuring deephaven_mcp.json

This section explains how to configure the Deephaven MCP Systems Server to connect to and manage your Deephaven Community Core instances and Deephaven Enterprise systems. This involves creating a systems session definition file and understanding how the server locates this file.

The deephaven_mcp.json File

Purpose and Structure

The Deephaven MCP Systems Server requires a JSON configuration file that describes the Deephaven Community Core worker instances and Deephaven Enterprise systems it can connect to.

  • The file must be a JSON object. It can be an empty object {} if no community sessions are to be configured.
  • Optionally, it can contain a top-level key named "community" with a nested "sessions" key.
    • If this key is present, its value must be an object (which can be empty, e.g., {}) where each key is a unique session name (e.g., "local_session", "prod_cluster_1_session") and the value is a configuration object for that session. An empty object signifies no sessions are configured under this key.
    • If this key is absent from the JSON file, it is treated as a valid configuration with no community sessions defined.

In addition to "community", the deephaven_mcp.json file can optionally include an "enterprise" key for configuring connections to Deephaven Enterprise instances. Within the "enterprise" object, you can define a "systems" key that maps system names to their configurations. The configuration details for both community.sessions and enterprise.systems are provided below.

Community Session Configuration Fields

The fields listed below pertain to community sessions. All community session fields are optional. Default values are applied by the server if a field is omitted. Configuration fields for enterprise systems are detailed in a subsequent section.

  • host (string): Hostname or IP address of the Deephaven Community Core worker (e.g., "localhost").
  • port (integer): Port number for the worker connection (e.g., 10000).
  • auth_type (string): Authentication type. Common values include:
    • "Anonymous": For no authentication (default if omitted).
    • "Basic": For username/password authentication (requires auth_token in "username:password" format).
    • Custom authenticator strings (e.g., "io.deephaven.authentication.psk.PskAuthenticationHandler" for Pre-Shared Key authentication).
  • auth_token (string): The authentication token. For "Basic" auth, this must be in "username:password" format. For custom authenticators, this should conform to the specific requirements of that authenticator. Ignored when auth_type is "Anonymous". Consult your Deephaven server's authentication documentation for specifics.
  • auth_token_env_var (string): Alternative to auth_token - specifies the name of an environment variable containing the authentication token (e.g., "MY_AUTH_TOKEN"). Mutually exclusive with auth_token.
  • never_timeout (boolean): If true, the MCP server will attempt to configure the session to this worker to never time out. Server-side configurations may still override this.
  • session_type (string): Specifies the type of session to create. Common values are "groovy" or "python".
  • use_tls (boolean): Set to true if the connection to the worker requires TLS/SSL.
  • tls_root_certs (string): Absolute path to a PEM file containing trusted root CA certificates for TLS verification. If omitted, system CAs might be used, or verification might be less strict depending on the client library.
  • client_cert_chain (string): Absolute path to a PEM file containing the client's TLS certificate chain. Used for client-side certificate authentication (mTLS).
  • client_private_key (string): Absolute path to a PEM file containing the client's private key. Used for client-side certificate authentication (mTLS).

Enterprise System Configuration Fields

The enterprise key with nested "systems" in deephaven_mcp.json is a dictionary mapping custom system names (e.g., "prod_cluster", "data_science_env") to their specific configuration objects. Each configuration object supports the following fields:

Required Fields:

  • connection_json_url (string): URL to the Deephaven Enterprise server's connection.json file (e.g., "https://enterprise.example.com/iris/connection.json"). This file provides the necessary details for the client to connect to the server.
  • auth_type (string): Specifies the authentication method. Must be one of:
    • "password": For username/password authentication.
    • "private_key": For authentication using a private key (e.g., SAML or other private key-based auth).

Conditional Fields (based on auth_type):

  • If auth_type is "password":
    • username (string): The username for authentication (required).
    • One of the following must be provided for the password:
      • password (string): The password itself.
      • password_env_var (string): The name of an environment variable that holds the password (e.g., "MY_ENTERPRISE_PASSWORD").
  • If auth_type is "private_key":
    • private_key_path (string): The absolute path to the private key file (e.g., "/path/to/your/private_key.pem") (required).

Note: All paths, like private_key_path, should be absolute and accessible by the MCP server process.

Example deephaven_mcp.json

{
  "community": {
    "sessions": {
      "my_local_deephaven": {
        "host": "localhost",
        "port": 10000,
        "session_type": "python"
      },
      "psk_authenticated_session": {
        "host": "localhost",
        "port": 10001,
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token": "your-shared-secret-key",
        "session_type": "python"
      },
      "basic_auth_session": {
        "host": "secure.deephaven.example.com",
        "port": 10002,
        "auth_type": "Basic",
        "auth_token": "username:password",
        "use_tls": true,
        "tls_root_certs": "/path/to/community_root.crt"
      }
    }
  },
  "enterprise": {
    "systems": {
      "prod_cluster": {
        "connection_json_url": "https://prod.enterprise.example.com/iris/connection.json",
        "auth_type": "password",
        "username": "your_username",
        "password_env_var": "ENTERPRISE_PASSWORD"
      },
      "data_science_env": {
        "connection_json_url": "https://data-science.enterprise.example.com/iris/connection.json",
        "auth_type": "private_key",
        "private_key_path": "/path/to/your/private_key.pem"
      }
    }
  }
}

Security Note for deephaven_mcp.json

The deephaven_mcp.json file can contain sensitive information such as authentication tokens, usernames, and passwords. Ensure that this file is protected with appropriate filesystem permissions to prevent unauthorized access. For example, on Unix-like systems (Linux, macOS), you can restrict permissions to the owner only using the command:

chmod 600 /path/to/your/deephaven_mcp.json

Additional Notes for deephaven_mcp.json

  • Ensure all file paths within the config (e.g., for TLS certificates if used) are absolute and accessible by the server process.
  • The session names are arbitrary and used to identify sessions in client tools.

Setting DH_MCP_CONFIG_FILE (Informing the MCP Server)

The DH_MCP_CONFIG_FILE environment variable tells the Deephaven MCP Systems Server where to find your deephaven_mcp.json file (detailed in The deephaven_mcp.json File (Defining Your Community Sessions)). You will set this environment variable as part of the server launch configuration within your LLM tool, as detailed in the Configure Your LLM Tool to Use MCP Servers section.

When launched by an LLM tool, the MCP Systems Server process reads this variable to load your session definitions. For general troubleshooting or if you need to set other environment variables like PYTHONLOGLEVEL (e.g., to DEBUG for verbose logs), these are also typically set within the LLM tool's MCP server configuration (see Defining MCP Servers for Your LLM Tool (The mcpServers JSON Object)).

Configure Your LLM Tool to Use MCP Servers

This section details how to configure your LLM tool (e.g., Claude Desktop, GitHub Copilot) to launch and communicate with the Deephaven MCP Systems Server and the Deephaven MCP Docs Server. This involves providing a JSON configuration, known as the "mcpServers" object, to your LLM tool.

How LLM Tools Launch MCP Servers (Overview)

LLM tools that support the Model Context Protocol (MCP) can be configured to use the Deephaven MCP Community and Docs Servers. The LLM tool's configuration will typically define how to start the necessary MCP server processes.

Understanding Deephaven Core Worker Status (via MCP)

The MCP Systems Server, launched by your LLM tool, will attempt to connect to the Deephaven Community Core instances defined in your deephaven_mcp.json file (pointed to by DH_MCP_CONFIG_FILE as described in Setting DH_MCP_CONFIG_FILE (Informing the MCP Server)).

It's important to understand the following:

  • MCP Server Independence: The MCP Systems Server itself will start and be available to your LLM tool even if some or all configured Deephaven Community Core workers are not currently running or accessible. The LLM tool will be able to list the configured workers and see their status (e.g., unavailable, connected).
  • Worker Interaction: To successfully perform operations on a specific Deephaven Community Core worker (e.g., list tables, execute scripts), that particular worker must be running and network-accessible from the environment where the MCP Systems Server process is executing.
  • Configuration is Key: Ensure your deephaven_mcp.json file accurately lists the systems session configurations you intend to use. The MCP server uses this configuration to know which sessions to attempt to manage.

Defining MCP Servers for Your LLM Tool (The mcpServers JSON Object)

Your LLM tool requires a specific JSON configuration to define how MCP servers are launched. This configuration is structured as a JSON object with a top-level key named "mcpServers". This "mcpServers" object tells the tool how to start the Deephaven MCP Systems Server (for interacting with Deephaven Community Core) and the mcp-proxy (for interacting with the Docs Server).

Depending on your LLM tool, this "mcpServers" object might be:

  • The entire content of a dedicated file (e.g., named mcp.json in VS Code).
  • A part of a larger JSON configuration file used by the tool (e.g., for Claude Desktop).

Consult your LLM tool's documentation for the precise file name and location. Below are two examples of the "mcpServers" JSON structure. Choose the one that matches your Python environment setup (either uv or pip + venv).

Important: All paths in the JSON examples (e.g., /full/path/to/...) must be replaced with actual, absolute paths on your system.

Example "mcpServers" object for uv users:

{
  "mcpServers": {
    "deephaven-systems": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/deephaven-mcp",
        "run",
        "dh-mcp-systems-server"
      ],
      "env": {
        "DH_MCP_CONFIG_FILE": "/full/path/to/your/deephaven_mcp.json",
        "PYTHONLOGLEVEL": "INFO" 
      }
    },
    "deephaven-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/deephaven-mcp",
        "run",
        "mcp-proxy",
        "--transport=streamablehttp",
        "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
      ]
    }
  }
}

Note: You can change "PYTHONLOGLEVEL": "INFO" to "PYTHONLOGLEVEL": "DEBUG" for more detailed server logs, as further detailed in the Troubleshooting section.

Example "mcpServers" object for pip + venv users:

{
  "mcpServers": {
    "deephaven-systems": {
      "command": "/full/path/to/your/deephaven-mcp/.venv/bin/dh-mcp-systems-server",
      "args": [], 
      "env": {
        "DH_MCP_CONFIG_FILE": "/full/path/to/your/deephaven_mcp.json",
        "PYTHONLOGLEVEL": "INFO"
      }
    },
    "deephaven-docs": {
      "command": "/full/path/to/your/deephaven-mcp/.venv/bin/mcp-proxy",
      "args": [
        "--transport=streamablehttp",
        "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
      ]
    }
  }
}

Note: You can change "PYTHONLOGLEVEL": "INFO" to "PYTHONLOGLEVEL": "DEBUG" for more detailed server logs, as further detailed in the Troubleshooting section.

Tool-Specific File Locations for the mcpServers Configuration

The "mcpServers" JSON object, whose structure is detailed in Defining MCP Servers for Your LLM Tool (The mcpServers JSON Object), needs to be placed in a specific configuration file or setting area for your LLM tool. Here’s how to integrate it with common tools:

  • Claude Desktop:
    • The mcpServers object should be added to the main JSON object within this file:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json (e.g., C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)
    • Linux: ~/.config/Claude/claude_desktop_config.json
  • GitHub Copilot (Visual Studio Code):
  • GitHub Copilot (JetBrains IDEs - IntelliJ IDEA, PyCharm, etc.):
    • The method for configuring custom MCP servers may vary. Please consult the official GitHub Copilot extension documentation for your specific JetBrains IDE for the most current instructions. It might involve a specific settings panel or a designated configuration file.

Restarting Your LLM Tool (Applying the Configuration)

Once you have saved the "mcpServers" JSON object in the correct location for your LLM tool, restart the tool (Claude Desktop, VS Code, JetBrains IDEs, etc.). The configured servers (e.g., deephaven-systems, deephaven-docs) should then be available in its MCP interface.

Verifying Your Setup

After restarting your LLM tool, the first step is to verify that the MCP servers are recognized:

  • Open your LLM tool's interface where it lists available MCP servers or data sources.
  • You should see deephaven-systems and deephaven-docs (or the names you configured in the mcpServers object) listed.
  • Attempt to connect to or interact with one of them (e.g., by listing available Deephaven Community Core workers via the deephaven-systems server).

If the servers are not listed or you encounter errors at this stage, please proceed to the Troubleshooting section for guidance.

Troubleshooting

  • LLM Tool Can't Connect / Server Not Found:
    • Verify all paths in your LLM tool's JSON configuration are absolute and correct.
    • Ensure DH_MCP_CONFIG_FILE environment variable is correctly set in the JSON config and points to a valid worker file.
    • Ensure any Deephaven Community Core workers you intend to use (as defined in deephaven_mcp.json) are running and accessible from the MCP Systems Server's environment.
    • Check for typos in server names, commands, or arguments in the JSON config.
    • Validate the syntax of your JSON configurations (mcpServers object in the LLM tool, and deephaven_mcp.json). A misplaced comma or incorrect quote can prevent the configuration from being parsed correctly. Use a JSON validator tool or your IDE's linting features.
      • Set PYTHONLOGLEVEL=DEBUG in the env block of your JSON config to get more detailed logs from the MCP servers. For example, Claude Desktop often saves these to files like ~/Library/Logs/Claude/mcp-server-SERVERNAME.log. Consult your LLM tool's documentation for specific log file locations.
  • Firewall or Network Issues: * Ensure that there are no firewall rules (local or network) preventing: * The MCP Systems Server from connecting to your Deephaven Community Core instances on their specified hosts and ports. * Your LLM tool or client from connecting to the mcp-proxy's target URL ([https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io](https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io)) if using the Docs Server. * Test basic network connectivity (e.g., using ping or curl from the relevant machine) if connections are failing.
  • command not found for uv (in LLM tool logs):
    • Ensure uv is installed and its installation directory is in your system's PATH environment variable, accessible by the LLM tool.
  • command not found for dh-mcp-systems-server or mcp-proxy (venv option in LLM tool logs):
    • Double-check that the command field in your JSON config uses the correct absolute path to the executable within your .venv/bin/ (or .venv\Scripts\) directory.
  • Port Conflicts: If a server fails to start (check logs), another process might be using the required port (e.g., port 8000 for default streamable-http/SSE).
  • Python Errors in Server Logs: Check the server logs for Python tracebacks. Ensure all dependencies were installed correctly (see Installation & Initial Setup).
  • Worker Configuration Issues: * If the Systems Server starts but can't connect to Deephaven Community Core workers, verify your deephaven_mcp.json file (see The deephaven_mcp.json File (Defining Your Community Sessions) for details on its structure and content). * Ensure the target Deephaven Community Core instances are running and network-accessible. * Confirm that the process running the MCP Systems Server has read permissions for the deephaven_mcp.json file itself.

Contributing

We warmly welcome contributions to Deephaven MCP! Whether it's bug reports, feature suggestions, documentation improvements, or code contributions, your help is valued.

  • Reporting Issues: Please use the GitHub Issues tracker.
  • Development Guidelines: For details on setting up your development environment, coding standards, running tests, and the pull request process, please see our Developer & Contributor Guide.

Advanced Usage & Further Information

Community & Support

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Related Servers