Deephaven

You can run Deephaven MCP to connect your AI tools to Deephaven data environments. This server lets you manage real-time dataframes and interact with Deephaven Community Core and Enterprise systems from your AI assistants and IDEs. It provides live data access, session management, and automation capabilities so you can build, query, and analyze data with AI help in real time.

How to use

Use the MCP server to expose Deephaven sessions to your AI tools and IDEs. Create and manage MCP connections to your Community Core sessions and Enterprise systems, then configure your AI tool to start the MCP systems and docs servers. Your AI assistant can list sessions, retrieve schemas, run scripts, and query data directly in your connected Deephaven environments. Follow the installation and configuration steps to set up the servers, then point your tool’s MCP configuration at the appropriate commands and URLs.

How to install

Prerequisites: Python 3.11, 3.12, or 3.13. A Python virtual environment is recommended. You may also enable Docker-based community session creation if you plan to launch sessions on demand.

Step 1: Prepare your environment and install the MCP package in a virtual environment.

Step 2: Create the configuration file deephaven_mcp.json with your Community Core and Enterprise connections.

Step 3: Configure your AI tool to launch the MCP systems server and the Docs server using the provided commands and the path to your configuration file.

Step 4: Start your AI tool and verify that the MCP servers appear as active endpoints. You can then ask the tool to list sessions, view table schemas, or run Python/Groovy scripts in your Deephaven sessions.

Configuration and MCP server endpoints

MCP servers expose both a Systems Server for managing sessions and an optional Docs Server for accessing documentation knowledge base and related features. The following configuration blocks are shown as examples you can adapt for your setup.

{
  "type": "http",
  "name": "docs_mcp",
  "url": "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp",
  "args": []
}

{
  "type": "stdio",
  "name": "systems_mcp",
  "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"
  }
}

Security and credentials

Keep sensitive information out of your configuration files whenever possible. Use environment variables for tokens and passwords, restrict file permissions, and enable credential controls in the MCP settings to limit who can retrieve session credentials.

Troubleshooting and tips

If you run into connection or startup issues, verify that your paths are absolute, your virtual environment is active, and the commands and URLs you configured match what your tool expects. Increase log detail by setting PYTHONLOGLEVEL=DEBUG in the MCP server environment to diagnose startup or runtime problems.

Advanced usage and tools

You can manage sessions, view details, reload configurations, create dynamic Community Core sessions, and interact with Enterprise systems using the MCP tools described in the available commands. Use the Systems Server to list sessions, get status, and execute scripts across your connected Deephaven environments.

Contributing and support

Contribute improvements, report issues, and engage with the Deephaven community for support. You can connect through the appropriate channels to request features, report bugs, and discuss best practices for MCP setup and AI integration.

Notes on browser access and credentials

When a new session is created, you may obtain a browser URL and temporary credentials to access data visually. Your tool can retrieve these credentials if credential retrieval is enabled in your security settings, and then you can open the provided browser URL to access the session directly.

Applying configuration changes

After adjusting deephaven_mcp.json or other config, restart your AI tool to apply changes. Then verify by listing sessions and checking that the MCP servers respond with the expected information.

AI tool setup and integration

Configure your AI tool with the mcpServers block that points to the system server command and the docs server URL. Use absolute paths for executables and config files, and set environment variables as shown in the examples.

Available tools

sessions_list

List all configured Sessions managed by the MCP Systems Server.

session_details

Get detailed information about a specific session.

mcp_reload

Reload configuration and clear internal caches without restarting the server.

session_community_create

Dynamically launch Community Core sessions.

session_community_delete

Delete dynamically created Community Core sessions.

enterprise_systems_status

Get status information for Enterprise systems.

session_enterprise_create

Create Enterprise sessions.

session_enterprise_delete

Delete Enterprise sessions.

session_tables_list

List available tables in a session.

session_tables_schema

Get schemas for a table.

session_table_data

Retrieve data from a table with formatting options.

catalog_tables_list

List catalog tables in Enterprise catalogs.

catalog_namespaces_list

Browse catalog namespaces.

catalog_tables_schema

Get catalog table schemas.

catalog_table_sample

Sample catalog table data.

session_script_run

Execute Python or Groovy scripts in a session.

session_pip_list

Query installed Python packages in a session.