--- 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 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](/community/) and [Deephaven Enterprise](/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`](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 For Enterprise Core+ deployments, install the full package with Core+ support: ```bash uv pip install "deephaven-mcp[coreplus]" ``` ### 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 Core+ support: ```bash 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](#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: ```json { "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: ```json { "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: ```json { "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](#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). > [!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: > > ```bash > 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](#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. 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. **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](#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 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](#configure-your-ai-tool) 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](#configure-your-ai-tool) 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](#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 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. ## 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)