---
title: Deephaven MCP
sidebar_label: 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)](https://modelcontextprotocol.io/docs/getting-started/intro) 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](/community/) and [Deephaven Enterprise](/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`](https://pypi.org/project/uv/) package.

```bash
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.

```bash
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:

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

### Alternative (`pip`)

You can also install Deephaven MCP with [`pip`](https://pypi.org/project/pip/).

#### Create and activate a virtual environment

Ensure your Python version is `3.11` or later.

```bash
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:

```bash
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](#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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](#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:

```json
{
  "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](#installation). 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.

<details>
<summary>How to set up credential environment variables</summary>

**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`

```bash
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:

```json
"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.

</details>

Your configuration steps vary slightly depending on which AI tool you use. For more on each AI tool, see the [Appendix](#ai-tool-configuration).

## Use Deephaven MCP

If you just [configured](#configure-your-ai-tool) (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:

```text
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](#configure-your-ai-tool) above.

#### Cursor

For project-specific configuration, edit **`.cursor/mcp.json`** in the project root. For global configuration, edit **`~/.cursor/mcp.json`**. Add the [configuration](#configure-your-ai-tool) 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"`:

```json
{
  "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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)), 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:

```json
{
  "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](#configure-your-ai-tool) 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`](#create-a-configuration-file) 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](https://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](https://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:

```bash
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:

```json
{
  "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.

## Related documentation

- [Authentication Service](../sys-admin/core-components/authentication.md)
- [SAML authentication](../sys-admin/configuration/saml-auth.md)
- [Python client](./python/coreplus-python-client.md)
- [JavaScript client](./javascript.md)