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 provide seamless integration between Deephaven and your AI development workflow. While AI models query tables, generate code, and do the busy work, you get to focus on turning that work into actionable insights.

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:

Session management:

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.

Data operations:

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 with a high degree of confidence.

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

For Enterprise Core+ deployments, install the full package with Core+ support:

uv pip install "deephaven-mcp[coreplus]"

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 Core+ support:

pip install "deephaven-mcp[coreplus]"

Setup

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

Create a configuration file

Note

It is recommended to set configuration file permissions to 600, as they can contain sensitive information such as credentials.

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.

Enterprise Core+ configuration

The following example configuration file is configured for a Deephaven Enterprise deployment with Core+ workers using pre-shared key authentication:

{
  "coreplus": {
    "deployments": {
      "my_enterprise_deployment": {
        "host": "enterprise.example.com",
        "port": 443,
        "use_tls": true,
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token_env_var": "DH_ENTERPRISE_TOKEN"
      }
    }
  }
}

Multiple deployments

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

{
  "coreplus": {
    "deployments": {
      "production": {
        "host": "prod.enterprise.example.com",
        "port": 443,
        "use_tls": true,
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token_env_var": "DH_PROD_TOKEN"
      },
      "staging": {
        "host": "staging.enterprise.example.com",
        "port": 443,
        "use_tls": true,
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token_env_var": "DH_STAGING_TOKEN"
      }
    }
  }
}

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"
      }
    }
  },
  "coreplus": {
    "deployments": {
      "enterprise_prod": {
        "host": "prod.enterprise.example.com",
        "port": 443,
        "use_tls": true,
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token_env_var": "DH_PROD_TOKEN"
      }
    }
  }
}

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.

Caution

For production Enterprise deployments, use environment variables for authentication tokens rather than hardcoding them in configuration files. Set the environment variables in your shell or system configuration before starting your AI tool.

For example:

export DH_PROD_TOKEN="your-token-here"
export DH_STAGING_TOKEN="your-token-here"
export DH_LOCAL_TOKEN="your-token-here"

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.

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.

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 Core+ deployments

Field	Type	Required	Description
`host`	string	Yes	Hostname or IP address of the Deephaven Enterprise Core+ deployment.
`port`	integer	Yes	Port number for the deployment connection (typically `443` for HTTPS).
`auth_type`	string	Yes	Authentication type configured for your Enterprise deployment.
`auth_token`	string	No	Authentication token. Mutually exclusive with `auth_token_env_var`.
`auth_token_env_var`	string	Recommended	Environment variable name containing the auth token. More secure than hardcoding tokens.
`use_tls`	boolean	Recommended	Set to `true` for production deployments (default for Enterprise).
`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).

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

Run the MCP: Add Server command from the Command Palette. Then select Workspace Settings to create the .vscode/mcp.json file. Alternatively, you can create this file manually in your project root. Add the configuration above.

Windsurf

Go to Windsurf -> Settings -> Windsurf Settings -> Cascade -> MCP Servers -> Manage MCPs -> View Raw Config, which opens ~/.codeium/windsurf/mcp_config.json. Add the configuration above.

Troubleshooting

This section contains the most commonly observed issues and solutions.

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 JSON syntax using a JSON validator.

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 [coreplus] extra: pip install "deephaven-mcp[coreplus]".

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 coreplus
source is the deployment or session name from your configuration
session_name is the specific session identifier

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 Core+ deployments

AI tool configuration

Claude Desktop

Cursor

Visual Studio Code

Windsurf

Troubleshooting

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

Authentication errors

Related documentation

Recommended (`uv`)

Alternative (`pip`)