Deephaven MCP

This guide walks you through the installation, setup, and use of Deephaven's MCP integration with Deephaven Enterprise.

What is MCP?

Model Context Protocol (MCP) is an open-source standard for connecting AI applications to other services like Deephaven. People who use MCP do so to connect the AI models they use to things like databases, workflows, and filesystems to perform operations on them via natural language.

MCP provides a standardized way for AI applications to communicate with external services, similar to how REST APIs enable web services to communicate.

What is Deephaven MCP?

Deephaven MCP implements the MCP standard to connect Deephaven to your AI development workflow. AI models can query tables, generate code, and execute scripts directly against your Deephaven sessions.

Deephaven MCP has two components:

Systems server

The systems server manages and connects to pre-defined Deephaven Community Core and Deephaven Enterprise systems. With the systems server, you can:

List, monitor, and get detailed status of all configured sessions.
Connect and manage Enterprise Core+ deployments.
Create and destroy Core+ sessions.
Dynamically reload and refresh session configurations.
Retrieve table schemas, metadata, and data.
Execute Python and Groovy scripts.
Query installed packages and environment details.

Docs server

The docs server connects to Deephaven's documentation knowledge base so that AI models can query it for information about Deephaven. Ask questions in natural language to get specific answers with code examples and explanations.

Prerequisites

To use Deephaven MCP, you must have the following:

Python 3.11 or later.
Access to one or more Deephaven Enterprise systems with Core+ workers.
Appropriate authentication credentials for your Enterprise deployment.

Installation

Recommended (`uv`)

The recommended way to set up Deephaven MCP is through the Python uv package.

pip install uv

Create and activate a virtual environment

The following command creates a virtual environment in the .venv directory using Python 3.11. If your Python version differs, replace 3.11 with your preferred version (such as 3.12) or the full path to a Python executable.

uv venv .venv -p 3.11

# On MacOS and Linux
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

Install Deephaven MCP

Install with Community and Enterprise support:

uv pip install "deephaven-mcp[community,enterprise]"

Alternative (`pip`)

You can also install Deephaven MCP with pip.

Create and activate a virtual environment

Ensure your Python version is 3.11 or later.

python -m venv .venv

# On MacOS and Linux
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

Install Deephaven MCP

Install with Community and Enterprise support:

pip install "deephaven-mcp[community,enterprise]"

Setup

There are two steps to setting up Deephaven MCP for Enterprise.

Create a configuration file

Note

On Unix-like systems, restrict configuration file permissions to the owner only (for example, chmod 600 deephaven_mcp.json), as configuration files can contain sensitive information such as credentials. On Windows, store the file in a location accessible only to your user account or administrators.

A configuration file defines the Deephaven sessions that the Deephaven MCP systems server makes available to your AI tools. This file, written in JSON, should be called deephaven_mcp.json and can be placed wherever you like in your filesystem.

Note

The configuration file supports both standard JSON and JSON5 formats. JSON5 features such as single-line comments (//), multi-line comments (/* */), and trailing commas are all valid.

Enterprise Core+ configuration

The following example configuration file is configured for a Deephaven Enterprise deployment with Core+ workers using password authentication:

{
  "enterprise": {
    "systems": {
      "my_enterprise_deployment": {
        "connection_json_url": "https://enterprise.example.com:8000/iris/connection.json",
        "auth_type": "password",
        "username": "admin",
        "password_env_var": "DH_ENTERPRISE_PASSWORD",
        "connection_timeout": 10
      }
    }
  }
}

Note

The connection_timeout field sets a limit (in seconds) on how long the MCP server waits when establishing a connection to your Enterprise deployment. Without it, a failed or slow connection attempt can hang indefinitely and make all MCP tools unresponsive.

Multiple deployments

You can configure multiple Enterprise Core+ deployments in a single configuration file:

{
  "enterprise": {
    "systems": {
      "production": {
        "connection_json_url": "https://prod.enterprise.example.com:8000/iris/connection.json",
        "auth_type": "password",
        "username": "admin",
        "password_env_var": "DH_PROD_PASSWORD"
      },
      "staging": {
        "connection_json_url": "https://staging.enterprise.example.com:8000/iris/connection.json",
        "auth_type": "password",
        "username": "admin",
        "password_env_var": "DH_STAGING_PASSWORD"
      }
    }
  }
}

Mixed Community Core and Enterprise Core+ configuration

If you need to connect to both Community Core and Enterprise Core+ systems:

{
  "community": {
    "sessions": {
      "local_dev": {
        "host": "localhost",
        "port": 10000,
        "session_type": "python",
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token": "YOUR_PASSWORD_HERE"
      }
    }
  },
  "enterprise": {
    "systems": {
      "enterprise_prod": {
        "connection_json_url": "https://prod.enterprise.example.com:8000/iris/connection.json",
        "auth_type": "password",
        "username": "admin",
        "password_env_var": "DH_PROD_PASSWORD"
      }
    }
  }
}

This file can contain any number of Deephaven Community Core and Deephaven Enterprise Core+ sessions. See the Systems server configuration parameters section for a complete list of available configuration parameters.

Configure your AI tool

Your AI tool configuration should look like this:

{
  "mcpServers": {
    "deephaven-systems": {
      "command": "/full/path/to/your/.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/.venv/bin/mcp-proxy",
      "args": [
        "--transport=streamablehttp",
        "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
      ]
    }
  }
}

/full/path/to/your/.venv/ is the full filepath to the Python virtual environment you created earlier. Both dh-mcp-systems-server and mcp-proxy are installed in the same virtual environment when you install deephaven-mcp.

Caution

For production Enterprise deployments, use environment variables for credentials (passwords or private keys) rather than hardcoding them in configuration files. The environment variables must be available to the MCP server process — setting them in a terminal session is not sufficient.

How to set up credential environment variables

Option 1: Add to your shell startup file

Add the following to your shell's startup file and restart your AI tool:

zsh: ~/.zshrc
bash: ~/.bashrc or ~/.bash_profile

export DH_ENTERPRISE_PASSWORD="your-password-here"

This only works when your AI tool is launched from a terminal session that sources the file. GUI-launched applications often do not inherit shell environment variables.

Option 2: Add directly to your AI tool's env block (recommended for Windsurf, Cursor, and VS Code)

Some AI tools, including Windsurf, do not reliably inherit shell startup file environment variables. The most reliable approach is to put the credential directly in the env block of your AI tool's MCP configuration:

"env": {
  "DH_MCP_CONFIG_FILE": "/full/path/to/your/deephaven_mcp.json",
  "PYTHONLOGLEVEL": "INFO",
  "DH_ENTERPRISE_PASSWORD": "your-password-here"
}

In either case, ensure configuration files containing credentials have restricted permissions. On Unix-like systems, run chmod 600 deephaven_mcp.json. On Windows, store the file in a location accessible only to your user account or administrators.

Your configuration steps vary slightly depending on which AI tool you use. For more on each AI tool, see the Appendix.

Use Deephaven MCP

If you just configured (or changed the configuration of) your AI tool for MCP, you must restart it for the configuration changes to take effect.

In VS Code, you can verify the servers are running by opening the Copilot Chat sidebar and checking for Deephaven tools in the tools panel. You can also check the Output panel (View → Output) and select MCP Server: deephaven-systems from the dropdown to see server logs.

Test the connection by asking your AI tool:

Are the Deephaven MCP servers working? Can you list available sessions?

If that works, you're all set! Try Deephaven MCP for:

Session management:

List available Core+ sessions.
Create and destroy Core+ sessions.
Monitor session health and package versions.
Get environment details.

Data operations:

List tables across sessions.
Analyze table schemas and metadata.
Retrieve and analyze data.
Write and execute queries.
Execute Python and Groovy scripts.

Enterprise operations:

Manage Persistent Query (PQ) lifecycle: list, create, start, stop, restart, and delete PQs.
Browse the Enterprise catalog to discover available namespaces and tables.

Documentation:

Query Deephaven documentation for customized help and code examples.

Appendix

Systems server configuration parameters

The following parameters are available for the systems server:

Community Core sessions

Field	Type	Required	Description
`host`	string	No	Hostname or IP address of the Deephaven Community Core session (e.g., `"localhost"`).
`port`	integer	No	Port number for the session connection (e.g., `10000`).
`auth_type`	string	No	Authentication type: `"Anonymous"` (default), `"Basic"`, or custom authenticator strings.
`auth_token`	string	No	Authentication token. For `"Basic"` auth: `"username:password"` format. Mutually exclusive with `auth_token_env_var`.
`auth_token_env_var`	string	No	Environment variable name containing the auth token (e.g., `"MY_AUTH_TOKEN"`). More secure than hardcoding tokens.
`never_timeout`	boolean	No	If `true`, attempts to configure the session to never time out.
`session_type`	string	No	Type of session to create: `"groovy"` or `"python"`.
`use_tls`	boolean	No	Set to `true` if the connection requires TLS/SSL.
`tls_root_certs`	string	No	Absolute path to PEM file with trusted root CA certificates for TLS verification.
`client_cert_chain`	string	No	Absolute path to PEM file with client's TLS certificate chain (for mTLS).
`client_private_key`	string	No	Absolute path to PEM file with client's private key (for mTLS).

Enterprise systems

Field	Type	Required	Description
`connection_json_url`	string	Yes	URL to the Enterprise `connection.json` endpoint (e.g., `"https://enterprise.example.com:8000/iris/connection.json"`).
`auth_type`	string	Yes	Authentication type: `"password"` or `"private_key"`.
`username`	string	Required if `auth_type` is `"password"`	Username for password authentication.
`password`	string	No	Password for `"password"` auth. Mutually exclusive with `password_env_var`.
`password_env_var`	string	Recommended	Environment variable containing the password. More secure than hardcoding.
`private_key_path`	string	Required if `auth_type` is `"private_key"`	Absolute path to the private key file (Deephaven proprietary format, typically named `priv-<keyname>.base64.txt`).
`connection_timeout`	number	No	Timeout in seconds for the connection attempt.

Important

The value of password_env_var in deephaven_mcp.json must match the name of an environment variable provided to the MCP server process. For example, if deephaven_mcp.json contains "password_env_var": "DH_ENTERPRISE_PASSWORD", then the env block in your AI tool's MCP configuration must include "DH_ENTERPRISE_PASSWORD": "your-actual-password". The two values must match exactly.

AI tool configuration

The process for configuring your AI tool depends on which one you use. This section covers several of the most popular ones.

Claude Desktop

Open Claude Desktop -> Settings -> Developer -> Edit Config. It should open a JSON file, to which you can add the configuration above.

Cursor

For project-specific configuration, edit .cursor/mcp.json in the project root. For global configuration, edit ~/.cursor/mcp.json. Add the configuration above.

Visual Studio Code

Create .vscode/mcp.json in your project root with the configuration below. Alternatively, run the MCP: Add Server command from the Command Palette to configure servers through a guided flow.

Note that VS Code uses "servers" as the top-level key instead of "mcpServers":

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

Note

VS Code also supports direct HTTP connections to the docs server using "type": "http" (see the VS Code MCP documentation), but mcp-proxy is the more reliable approach.

Windsurf

Go to Windsurf -> Settings -> Windsurf Settings -> Cascade -> MCP Servers -> Manage MCPs -> View Raw Config, which opens ~/.codeium/windsurf/mcp_config.json. Windsurf supports direct HTTP connections to the docs server, so mcp-proxy is not required:

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

Troubleshooting

This section contains the most commonly observed issues and solutions.

VS Code: MCP servers not appearing in Copilot Chat

Where you'll see it: Copilot Chat sidebar — no Deephaven tools listed

Verify .vscode/mcp.json is saved and all paths are absolute.
Check the Output panel (View → Output → MCP Server: deephaven-systems) for error messages.
Ensure the GitHub Copilot extension is installed and signed in — VS Code MCP support requires it.
Check that DH_ENTERPRISE_PASSWORD (or whatever your password_env_var value is) is set in the env block of .vscode/mcp.json.
Restart VS Code after any configuration changes.

spawn uv ENOENT

Where you'll see it: AI tool logs and UI pop-up

This error occurs when the AI tool cannot find the MCP server executable. Check your AI tool configuration and ensure it uses the full absolute path to the virtual environment and that the path is correct.

Connection failed

Where you'll see it: MCP server logs

This error most commonly happens when connecting to an external Deephaven server. Check your internet connection, server URLs, firewall rules, and VPN configuration.

For Enterprise Core+ deployments, verify:

Your network has access to the Enterprise deployment.
TLS certificates are valid and trusted.
Authentication credentials are correct and not expired.
Firewall rules allow connections to the deployment port.

Config not found

Where you'll see it: MCP server startup logs

The MCP server cannot find the deephaven_mcp.json file. Verify the full absolute path to the file in your AI tool configuration.

Permission denied

Where you'll see it: Command execution logs

The MCP server does not have permission to access a file or directory. Ensure your Python installation and packages like uv have the proper permissions.

Python version error

Where you'll see it: Installation or startup logs

You are using an unsupported Python version. Deephaven MCP requires Python 3.11 or later.

JSON parse error

Where you'll see it: AI tool logs

There is a syntax error in one of your configuration files. Validate your configuration file syntax using a JSON5-compatible validator (for example, json5.org).

Module not found: deephaven_mcp

Where you'll see it: MCP server logs

The virtual environment does not have the required dependencies installed. For Enterprise Core+, ensure you installed with the [enterprise] extra: pip install "deephaven-mcp[community,enterprise]".

Port already in use

Where you'll see it: Server startup logs

The PORT environment variable conflicts with another process. Check for conflicting processes and adjust the port configuration if needed.

Invalid session_id format

Where you'll see it: MCP tool response

The session identifier format is incorrect. Session IDs must follow the format: {type}:{source}:{session_name} where:

type is either community or enterprise
source is the deployment or session name from your configuration
session_name is the specific session identifier

SSL certificate verification failed

Where you'll see it: MCP server startup logs

On macOS, Python installed from python.org does not use the macOS system keychain for SSL verification. This causes certificate errors even for servers with valid, publicly trusted certificates.

To fix this, run the Install Certificates.command script that ships with your Python installation:

open "/Applications/Python 3.x/Install Certificates.command"

Replace 3.x with your Python version (for example, 3.11).

Note

Do not set the SSL_CERT_FILE environment variable unless you have a correct CA bundle to point it at. When set, Python uses only that file for SSL verification and ignores all other certificate sources, including certifi. Pointing it at the wrong file causes the same verification errors.

Enterprise connection hangs and MCP tools become unresponsive

Where you'll see it: All MCP tool calls hang or time out

If a connection_timeout is not set in your enterprise system configuration, the MCP server can hang indefinitely while waiting for a connection that never completes. This blocks all MCP tool responses, not just the failing connection.

Add connection_timeout to your enterprise system configuration to prevent this:

{
  "enterprise": {
    "systems": {
      "my_enterprise_deployment": {
        "connection_json_url": "https://enterprise.example.com:8000/iris/connection.json",
        "auth_type": "password",
        "username": "admin",
        "password_env_var": "DH_ENTERPRISE_PASSWORD",
        "connection_timeout": 10
      }
    }
  }
}

If the MCP server is already stuck in this state, restart it from your AI tool's MCP server settings, or kill the process and restart your AI tool.

Authentication errors

For Enterprise Core+ deployments:

Verify your authentication token is valid and not expired.
Ensure the auth_type matches your Enterprise deployment configuration.
Check that environment variables are properly set before starting your AI tool.
Confirm your user account has appropriate permissions in the Enterprise deployment.

Deephaven MCP

What is MCP?

What is Deephaven MCP?

Systems server

Docs server

Prerequisites

Installation

Recommended (uv)

Create and activate a virtual environment

Install Deephaven MCP

Alternative (pip)

Create and activate a virtual environment

Install Deephaven MCP

Setup

Create a configuration file

Enterprise Core+ configuration

Multiple deployments

Mixed Community Core and Enterprise Core+ configuration

Configure your AI tool

Use Deephaven MCP

Appendix

Systems server configuration parameters

Community Core sessions

Enterprise systems

AI tool configuration

Claude Desktop

Cursor

Visual Studio Code

Windsurf

Troubleshooting

VS Code: MCP servers not appearing in Copilot Chat

spawn uv ENOENT

Connection failed

Config not found

Permission denied

Python version error

JSON parse error

Module not found: deephaven_mcp

Port already in use

Invalid session_id format

SSL certificate verification failed

Enterprise connection hangs and MCP tools become unresponsive

Authentication errors

Related documentation

Recommended (`uv`)

Alternative (`pip`)