deephaven-mcp

Table of Contents

• Overview
• Key Use Cases
• 🚀 Quick Start
• 🔄 Quick Upgrade
• Deephaven MCP Components
• Available MCP Tools
• Architecture Diagrams
• Prerequisites
• Installation & Initial Setup
• Configuration
  • Configuring deephaven_mcp.json
  • Environment Variables
  • Browser Access to Created Sessions
  • Applying Configuration Changes
• AI Tool Setup
• Troubleshooting
• Advanced Usage
• Contributing
• Community & Support
• License

Overview

Supercharge your AI workflows with real-time data. Deephaven MCP brings the power of live dataframes directly to your favorite AI tools -— Claude Desktop, Cursor, VS Code (GitHub Copilot), Windsurf, and more.

Why Deephaven MCP?

Most data tools force you to choose: fast or real-time. With Deephaven's revolutionary live dataframes, you get both. Process streaming data at millisecond speeds while your AI assistant helps you build, query, and analyze -— all through natural language.

🚀 What makes this different:

• Live Data, Live Results: Query streaming Kafka, real-time feeds, and batch data as easily as static CSV files
• AI-Native Integration: Your AI assistant understands your data pipeline and can help optimize, debug, and extend it
• Enterprise Ready: Battle-tested on Wall Street for over a decade, now available for your team
• Zero Learning Curve: Write queries as if working with static tables -— real-time updates happen automatically

Deephaven MCP implements the Model Context Protocol (MCP) standard using FastMCP to provide seamless integration between Deephaven Community Core and Deephaven Enterprise systems and your AI development workflow. Perfect for data scientists, engineers, analysts, business users, and anyone who wants to harness real-time data—regardless of programming experience. Let AI generate the code while you focus on insights.

Key Use Cases

• AI-Assisted Development: Integrate Deephaven with LLM-powered development tools (e.g., Claude Desktop, GitHub Copilot) for AI-assisted data exploration, code generation, and analysis.
• Multi-Environment Management: Programmatically manage and query multiple Deephaven Community Core and Enterprise deployments from a single interface.
• Interactive Documentation: Quickly find information and examples from Deephaven documentation using natural language queries.
• Script Automation: Execute Python or Groovy scripts across multiple Deephaven sessions for data processing workflows.
• Schema Discovery: Automatically retrieve and analyze table schemas from connected Deephaven instances.
• Environment Monitoring: Monitor session health, package versions, and system status across your Deephaven infrastructure.

Deephaven MCP Components

Systems Server

Manages and connects to multiple Deephaven Community Core sessions and Deephaven Enterprise systems. This allows for unified control and interaction with your Deephaven instances from various client applications.

Key Capabilities:

• Session Management: List, monitor, and get detailed status of all configured Deephaven sessions
• Community Session Creation: Dynamically launch new Community Core sessions via Docker or python with configurable resources
• Enterprise Systems: Connect to and manage Deephaven Enterprise (Core+) deployments
• Enterprise Session Creation: Create and delete enterprise sessions with configurable resources and limits
• Persistent Query Management: Full lifecycle management of enterprise persistent queries (PQs) - create, start, stop, restart, and delete long-running worker sessions
• Catalog Discovery: Browse enterprise catalog at table and namespace levels to discover available data sources
• Table Discovery: Lightweight table name listing and comprehensive schema retrieval for both session and catalog tables
• Table Operations: Retrieve table schemas, metadata, and actual data with flexible formatting options
• Script Execution: Run Python or Groovy scripts directly on Deephaven sessions
• Package Management: Query installed Python packages in session environments
• Configuration Management: Dynamically reload and refresh session configurations

Available MCP Tools

Session Management:

• sessions_list - List all configured sessions
• session_details - Get detailed session information
• mcp_reload - Reload configuration and clear caches

Community Sessions:

• session_community_create - Dynamically launch Community Core sessions
• session_community_delete - Delete dynamically created sessions
• session_community_credentials - Retrieve session credentials

Enterprise Systems & Sessions:

• enterprise_systems_status - Get enterprise system status
• session_enterprise_create - Create enterprise sessions
• session_enterprise_delete - Delete enterprise sessions

Persistent Query (PQ) Management:

• pq_name_to_id - Convert PQ name to canonical pq_id
• pq_list - List all persistent queries on a system
• pq_details - Get detailed PQ information
• pq_create - Create new persistent queries
• pq_modify - Modify existing persistent query configuration
• pq_start - Start persistent queries (supports parallel execution with configurable concurrency)
• pq_stop - Stop running persistent queries (supports parallel execution with configurable concurrency)
• pq_restart - Restart persistent queries (supports parallel execution with configurable concurrency)
• pq_delete - Delete persistent queries (supports parallel execution with configurable concurrency)

Parallel Batch Operations: When operating on multiple PQs, pq_start, pq_stop, pq_restart, and pq_delete execute operations in parallel with a default concurrency limit of 20. This provides near-batch performance (~10x faster for large batches) while maintaining granular per-item error reporting for AI agents. The concurrency limit can be adjusted via the max_concurrent parameter to balance performance and server load.

Table Operations:

• session_tables_list - List available tables
• session_tables_schema - Get table schema information
• session_table_data - Retrieve table data with formatting options

Catalog Discovery (Enterprise):

• catalog_tables_list - List catalog tables
• catalog_namespaces_list - Browse catalog namespaces
• catalog_tables_schema - Get catalog table schemas
• catalog_table_sample - Sample catalog table data

Execution & Packages:

• session_script_run - Execute Python/Groovy scripts
• session_pip_list - Query installed packages

For detailed tool documentation with parameters and examples, see the Developer & Contributor Guide.

Docs Server

Connects to Deephaven's documentation knowledge base via Inkeep AI to answer questions about Deephaven features, APIs, and usage patterns. Ask questions in natural language and get specific answers with code examples and explanations.

Architecture Diagrams

Systems Server Architecture

graph TD
    A["MCP Clients (Claude Desktop, etc.)"] --"stdio (MCP)"--> B("MCP Systems Server")
    B --"Manages"--> C("Deephaven Community Core Worker 1")
    B --"Manages"--> D("Deephaven Community Core Worker N")
    B --"Manages"--> E("Deephaven Enterprise System 1")
    B --"Manages"--> F("Deephaven Enterprise System N")
    E --"Manages"--> G("Enterprise Worker 1.1")
    E --"Manages"--> H("Enterprise Worker 1.N")
    F --"Manages"--> I("Enterprise Worker N.1")
    F --"Manages"--> J("Enterprise Worker N.N")

Clients connect to the MCP Systems Server, which in turn manages and communicates with Deephaven Community Core sessions and Deephaven Enterprise systems.

Docs Server Architecture

graph TD
    A["MCP Clients with streamable-http support"] --"streamable-http (direct)"--> B("MCP Docs Server")
    C["MCP Clients without streamable-http support"] --"stdio"--> D["mcp-proxy"]
    D --"streamable-http"--> B
    B --"Accesses"--> E["Deephaven Documentation Corpus via Inkeep API"]

Modern MCP clients can connect directly via streamable-http for optimal performance. Clients without native streamable-http support can use mcp-proxy to bridge stdio to streamable-http.

🚀 Quick Start

Get up and running in 5 minutes! This quickstart assumes you have a local Deephaven Community Core instance running on localhost:10000. If you don't have one, download and start Deephaven Community Core first.

1. Create Virtual Environment

Using uv (recommended):

Pick a suitable project directory for your venv.

name_of_your_venv=".venv"
uv venv $name_of_your_venv -p 3.11

Using standard venv:

python3.11 -m venv .venv

Replace 3.11 / python3.11 with any supported Python version (3.11, 3.12, or 3.13).

2. Install Deephaven MCP

For most users, installing with both Community + Enterprise support is the best default.

These instructions cover the installation of the Deephaven MCP system server, which enables AI agents to interact with Deephaven Community and Enterprise systems.

Note: The Deephaven MCP docs server is hosted by Deephaven and requires no installation.

Using uv (recommended):

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

Using standard pip:

.venv/bin/pip install "deephaven-mcp[community,enterprise]"

Optional Dependencies:

For more details and additional installation methods, see Installation & Initial Setup.

3. Create Configuration File

Create a file called deephaven_mcp.json anywhere on your system:

{
  // Community Core session configurations
  "community": {
    "sessions": {
      // "local" is a custom name - use any name you want for your sessions
      "local": {
        "host": "localhost",           // Server hostname or IP address
        "port": 10000,                 // Deephaven gRPC port (default: 10000)
        // Full authentication handler class name (can also use "PSK" shorthand)
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token": "YOUR_PASSWORD_HERE"  // Must match your Deephaven server token
      }
    },
    // Optional: Enable MCP tools for creating/deleting sessions on-demand
    // Useful for temporary workspaces and dynamic testing environments
    "session_creation": {
      "defaults": {
        "launch_method": "python"     // "python" or "docker"
      }
    }
  }
}

⚠️ Security Note: Since this file contains authentication credentials, set restrictive permissions:

Copy

chmod 600 deephaven_mcp.json

💡 Dynamic Sessions: The session_creation section enables on-demand Community Core session creation. Requirements: deephaven-server (installed in any Python venv) for the python method, or Docker for the docker method. See Community Session Creation Configuration for details.

4. Configure Your AI Tool

For Claude Desktop, open Claude Desktop → Settings → Developer → Edit Config and add:

{
  "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"
      ]
    }
  }
}

For other tools, see the detailed setup instructions below.

5. Try It Out

Restart your AI tool (or IDE). This will start your mcp servers from the installation in the venv you have supplied, located from the configuration supplied.

Confirm the setup is working by asking:

"List my Deephaven sessions and show me the tables in the local session"

"What Python packages are installed in my Deephaven environment?"

"Execute this Python code in my Deephaven session: t = empty_table(100).update('x=i', 'y=i*2')"

Need help? Check the Troubleshooting section, ask the built-in docs server about Deephaven features, or join the Deephaven Community Slack!

🔄 Quick Upgrade

Already have deephaven-mcp installed? Here's how to upgrade:

Using uv:

uv pip install --upgrade deephaven-mcp

Using standard pip:

.venv/bin/pip install --upgrade deephaven-mcp

To upgrade with optional dependencies:

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

# pip
.venv/bin/pip install --upgrade "deephaven-mcp[community,enterprise]"

After upgrading, restart your AI tool for changes to take effect.

Prerequisites

• Python: Version 3.11, 3.12, or 3.13. (Download Python)
• Docker (Optional): Required for Docker-based community session creation. (Download Docker)
• Access to Deephaven systems: To use the MCP Systems Server, you will need one or more of the following:
  • Deephaven Community Core instance(s): For development and personal use.
  • Deephaven Enterprise system(s): For enterprise-level features and capabilities.
• Choose your Python environment setup method:
  • Option A: uv (Recommended): A very fast Python package installer and resolver. If you don't have it, you can install it via pip install uv or see the uv installation guide.
  • Option B: Standard Python venv and pip: Uses Python's built-in virtual environment (venv) tools and pip.
• Configuration Files: Each integration requires proper configuration files (specific locations detailed in each integration section)

Installation & Initial Setup

⚡ Quick Path: For a fast getting-started experience, see the 🚀 Quick Start guide above. This section provides additional installation details and alternative methods.

The recommended way to install deephaven-mcp is from PyPI, which provides the latest stable release.

Installation Methods

Using uv (Fast, Recommended)

uv is a high-performance Python package manager. For detailed uv workflows and project-specific setup, see the uv documentation.

Install uv:

pip install uv

Create environment and install:

# Create virtual environment with Python 3.11+, in a chosen project directory
name_of_your_venv=".venv"
uv venv $name_of_your_venv -p 3.11

# Install deephaven-mcp (choose your extras)
uv pip install deephaven-mcp                           # Basic
uv pip install "deephaven-mcp[community]"              # + Python session creation
uv pip install "deephaven-mcp[enterprise]"             # + Enterprise support
uv pip install "deephaven-mcp[community,enterprise]"   # Both

Using Standard pip and venv

Create environment and install:

# Create virtual environment
python3.11 -m venv .venv

# Install deephaven-mcp (choose your extras)
.venv/bin/pip install deephaven-mcp                           # Basic
.venv/bin/pip install "deephaven-mcp[community]"              # + Python session creation
.venv/bin/pip install "deephaven-mcp[enterprise]"             # + Enterprise support
.venv/bin/pip install "deephaven-mcp[community,enterprise]"   # Both

Optional Dependency Reference:

Configuration

This section covers all aspects of configuring Deephaven MCP, from defining your sessions and systems to setting environment variables and managing browser access.

Configuring deephaven_mcp.json

This section explains how to configure the Deephaven MCP Systems Server to connect to and manage your Deephaven Community Core instances and Deephaven Enterprise systems. This involves creating a systems session definition file and understanding how the server locates this file.

The deephaven_mcp.json File

This file tells the MCP Systems Server how to connect to your Deephaven instances. You'll create this file to define your connections to either Community Core sessions or Enterprise systems (or both).

File Format: The configuration file supports both standard JSON and JSON5 formats:

• Single-line comments: // This is a comment
• Multi-line comments: /* This is a multi-line comment */
• Trailing commas are also supported

The configuration file supports two main sections:

• "community": For connecting to Community Core session instances
• "enterprise": For connecting to Enterprise systems

You can include either section, both, or neither (empty file). Each section contains connection details specific to that type of Deephaven system.

🔒 Security Note: For controlling access to session credentials, see the Security Configuration section below.

Community Core Configuration

Community Examples

Minimal configuration (no connections):

{}

Anonymous authentication (simplest):

{
  "community": {
    "sessions": {
      // No authentication required - use only for local development!
      // When auth_type is omitted, defaults to "Anonymous"
      "my_local_server": {
        "host": "localhost",  // Deephaven server address
        "port": 10000          // Default Deephaven port (gRPC)
      }
    }
  }
}

PSK authentication:

{
  "community": {
    "sessions": {
      "psk_server": {
        "host": "localhost",
        "port": 10000,
        // Pre-Shared Key authentication (most common for production)
        // Can use "PSK" shorthand or full class name shown here
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token": "your-shared-secret-key"  // Token configured on server
      }
    }
  }
}

Basic authentication with environment variable:

{
  "community": {
    "sessions": {
      "prod_session": {
        "host": "deephaven-prod.example.com",  // Remote server
        "port": 10000,
        "auth_type": "Basic",  // HTTP Basic authentication
        // More secure: read credentials from environment variable
        // Set in shell: export DH_AUTH_TOKEN="username:password"
        "auth_token_env_var": "DH_AUTH_TOKEN"  // Must be in "user:pass" format
      }
    }
  }
}

TLS/SSL configuration:

{
  "community": {
    "sessions": {
      "secure_tls_session": {
        "host": "secure.deephaven.example.com",
        "port": 443,  // Standard HTTPS port (use 10000 for non-TLS)
        "use_tls": true,  // Enable SSL/TLS encryption
        // Optional: Custom CA certificate for server verification
        "tls_root_certs": "/absolute/path/to/ca.pem",  // Must be absolute path!
        // Optional: Mutual TLS (mTLS) for client authentication
        "client_cert_chain": "/absolute/path/to/client-cert.pem",
        "client_private_key": "/absolute/path/to/client-key.pem"
      }
    }
  }
}

Community Configuration Fields

All community session fields are optional. Default values are applied by the server if a field is omitted.

💡 See Examples Above: For complete configuration examples, refer to Community Examples.

Community Session Creation Configuration

The session_creation key enables dynamic creation of Deephaven Community Core sessions on-demand. When configured, the MCP tools session_community_create and session_community_delete become available.

Requirements by launch method:

• Docker method (launch_method: "docker"):

  • Requires Docker installed and running
  • Works with base deephaven-mcp installation (no additional packages needed)

• Python method (launch_method: "python"):

  • Requires deephaven-server installed in a Python environment
  • Default venv: Uses same venv as MCP server
  • Custom venv: Optionally specify a different venv via python_venv_path parameter
  • No Docker needed

Docker Image Configuration Examples:

// CORRECT: Use programming_language for standard Deephaven images
{
  "session_creation": {
    "defaults": {
      "launch_method": "docker",
      "programming_language": "Python"  // Uses ghcr.io/deephaven/server:latest
    }
  }
}

// CORRECT: Use programming_language for Groovy
{
  "session_creation": {
    "defaults": {
      "launch_method": "docker",
      "programming_language": "Groovy"  // Uses ghcr.io/deephaven/server-slim:latest
    }
  }
}

// CORRECT: Use docker_image for custom images
{
  "session_creation": {
    "defaults": {
      "launch_method": "docker",
      "docker_image": "my-custom-deephaven:v1.0"  // Uses your custom image
    }
  }
}

// INCORRECT: Don't use both programming_language and docker_image together
{
  "session_creation": {
    "defaults": {
      "launch_method": "docker",
      "programming_language": "Python",  // Conflict!
      "docker_image": "custom:latest"     // Conflict!
    }
  }
}

📝 Session Lifecycle Notes:

Automatic Cleanup:

• Sessions are automatically stopped and cleaned up when the MCP server shuts down
• All ports are released and containers/processes are terminated gracefully
• On restart, the MCP server detects and cleans up any orphaned resources from previous runs

Session Management:

• Auto-generated PSK tokens are logged at WARNING level for visibility (similar to Jupyter notebooks)
• Created sessions use session IDs in format: community:dynamic:{session_name}
• Only dynamically created sessions can be deleted via session_community_delete
• Static configuration-based sessions cannot be deleted via MCP tools

Enterprise System Configuration

Enterprise Examples

Password authentication (direct):

{
  "enterprise": {
    "systems": {
      // "dev_enterprise_system" is a custom name - use any name you like
      "dev_enterprise_system": {
        // Enterprise server provides this URL (for envoy on port 8000, and typically ends with /iris/connection.json)
        "connection_json_url": "https://dev-enterprise.example.com:8000/iris/connection.json",
        "auth_type": "password",  // Username/password authentication
        "username": "admin",
        "password": "your-password-here"  // Consider password_env_var for security!
      }
    }
  }
}

Password authentication (environment variable):

{
  "enterprise": {
    "systems": {
      "my_enterprise_system": {
        "connection_json_url": "https://my-enterprise.example.com:8000/iris/connection.json",
        "auth_type": "password",
        "username": "admin",
        // RECOMMENDED: Read password from environment variable
        // Set in shell: export DH_ENTERPRISE_PASSWORD="your-password"
        "password_env_var": "DH_ENTERPRISE_PASSWORD"
      }
    }
  }
}

Private key authentication:

{
  "enterprise": {
    "systems": {
      "saml_enterprise": {
        "connection_json_url": "https://enterprise.example.com:8000/iris/connection.json",
        // Private key authentication (commonly used with SAML/SSO setups)
        // Your IT/security team provides the private keypair file (Deephaven proprietary format)
        // Typically named: priv-<keyname>.base64.txt
        "auth_type": "private_key",
        "private_key_path": "/absolute/path/to/priv-mykeyname.base64.txt"  // Must be absolute!
      }
    }
  }
}

Enterprise Configuration Fields

The enterprise key contains a "systems" dictionary mapping custom system names to their configuration objects.

💡 See Examples Above: For complete configuration examples, refer to Enterprise Examples.

📝 Note: All file paths should be absolute and accessible by the MCP server process.

Security Configuration

The top-level security section in deephaven_mcp.json controls security-sensitive features. This section is optional.

Community Credential Retrieval

The security.community.credential_retrieval_mode setting controls whether and how the session_community_credentials MCP tool can retrieve authentication credentials programmatically.

🔒 SECURITY WARNING

When credential retrieval is enabled, your AI assistant can see and access the authentication tokens. The AI can use these credentials to connect to your Deephaven sessions. The credentials may also be logged by the AI assistant.

Only enable credential retrieval modes if you understand these security implications. NEVER enable credential retrieval when the MCP server is accessible over untrusted networks.

Mode Descriptions:

• "none" (default): Credential retrieval disabled for all sessions (most secure)

  • Tool returns error with configuration instructions
  • Credentials only available via console logs

• "dynamic_only": Only dynamically created session credentials can be retrieved

  • Recommended for development environments
  • Allows retrieval for sessions created via session_community_create
  • Denies retrieval for static configuration-based sessions

• "static_only": Only static configuration-based session credentials can be retrieved

  • For controlled environments where static credentials are managed
  • Allows retrieval for sessions defined in community.sessions
  • Denies retrieval for dynamically created sessions

• "all": Both dynamic and static session credentials can be retrieved

  • Maximum flexibility but requires careful security consideration
  • Only enable if you understand the security implications

Example Configuration:

{
  "security": {
    "community": {
      "credential_retrieval_mode": "dynamic_only"
    }
  },
  "community": {
    "sessions": {
      "local": {
        "host": "localhost",
        "port": 10000
      }
    }
  }
}

Combined Configuration Example

Here's a complete example showing both Community and Enterprise configurations:

{
  /* ====================================
   * Community Core Session Configurations
   * ==================================== */
  "community": {
    "sessions": {
      // Local development - no authentication
      "my_local_deephaven": {
        "host": "localhost",
        "port": 10000,
        "session_type": "python"  // "python" or "groovy" - sets query language
      },
      // Staging environment - PSK authentication
      "psk_authenticated_session": {
        "host": "localhost",
        "port": 10001,
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token": "your-shared-secret-key",
        "session_type": "python"
      },
      // Production - Basic auth with TLS
      "basic_auth_session": {
        "host": "secure.deephaven.example.com",
        "port": 10002,
        "auth_type": "Basic",
        "auth_token": "username:password",  // Better: use auth_token_env_var!
        "use_tls": true,
        "tls_root_certs": "/path/to/community_root.crt"  // Absolute path
      }
    },
    /* Dynamic session creation configuration
     * Enables on-demand session creation via MCP tools */
    "session_creation": {
      "max_concurrent_sessions": 5,  // Maximum number of concurrent dynamic sessions
      "defaults": {
        "launch_method": "docker",  // "docker" or "python"
        "auth_type": "PSK",  // Auto-generate PSK tokens for security
        "docker_image": "ghcr.io/deephaven/server:latest",  // Docker image to use
        "docker_memory_limit_gb": null,  // null = no limit, or specify GB (e.g., 8.0)
        "docker_cpu_limit": null,  // null = no limit, or specify cores (e.g., 2.0)
        "docker_volumes": [],  // Empty = no mounts, or add paths like ["/data:/data"]
        "heap_size_gb": 4.0,  // JVM heap size (4GB works for most cases)
        "extra_jvm_args": [],  // Custom JVM flags if needed
        "environment_vars": {},  // Custom environment variables
        "startup_timeout_seconds": 60,  // How long to wait for session to start
        "startup_check_interval_seconds": 2,  // How often to check if ready
        "startup_retries": 3  // Number of restart attempts on failure
      }
    }
  },
  /* ====================================
   * Enterprise System Configurations
   * ==================================== */
  "enterprise": {
    "systems": {
      // "prod_cluster" is a custom name - use whatever makes sense for your setup
      "prod_cluster": {
        "connection_json_url": "https://prod.enterprise.example.com/iris/connection.json",
        "auth_type": "password",
        "username": "your_username",
        "password_env_var": "ENTERPRISE_PASSWORD",  // Read from environment (secure)
        // Enable dynamic Enterprise session creation
        "session_creation": {
          "max_concurrent_sessions": 3,  // Lower limit for production stability
          "defaults": {
            "heap_size_gb": 8.0,  // Larger heap for production workloads
            "programming_language": "Groovy",  // "Python" or "Groovy"
            "auto_delete_timeout": 3600,  // Auto-delete idle sessions after 1 hour
            "server": "gpu-server-1",  // Target specific Enterprise server/node
            "engine": "DeephavenCommunity",  // Engine type (check with your admin)
            // Performance tuning: G1GC with 200ms pause target
            "extra_jvm_args": ["-XX:+UseG1GC", "-XX:MaxGCPauseMillis=200"],
            // Custom environment for your workflows (format: "KEY=value")
            "extra_environment_vars": ["PYTHONPATH=/custom/libs", "LOG_LEVEL=DEBUG"],
            // Access control: Who can admin vs view the session
            "admin_groups": ["deephaven-admins", "data-team-leads"],
            "viewer_groups": ["analysts", "data-scientists"],
            "timeout_seconds": 120.0,  // Wait up to 2 minutes for session startup
            // Custom args passed to pydeephaven.Session (advanced)
            "session_arguments": {"custom_setting": "example_value"}
          }
        }
      },
      // Separate data science environment - private key auth (SAML)
      "data_science_env": {
        "connection_json_url": "https://data-science.enterprise.example.com/iris/connection.json",
        "auth_type": "private_key",
        "private_key_path": "/path/to/priv-mykeyname.base64.txt"  // Proprietary keypair file from your IT team
      }
    }
  }
}

Security Note

⚠️ Security Warning: The deephaven_mcp.json file can contain sensitive information such as authentication tokens, usernames, and passwords. Ensure that this file is protected with appropriate filesystem permissions to prevent unauthorized access.

For example, on Unix-like systems (Linux, macOS), you can restrict permissions to the owner only:

Copy

chmod 600 /path/to/your/deephaven_mcp.json

Setting DH_MCP_CONFIG_FILE

The DH_MCP_CONFIG_FILE environment variable tells the Deephaven MCP Systems Server where to find your deephaven_mcp.json file (detailed in The deephaven_mcp.json File). You will set this environment variable as part of the server launch configuration within your LLM tool, as detailed in the Setup Instructions by Tool section.

When launched by an LLM tool, the MCP Systems Server process reads this variable to load your session definitions. For general troubleshooting or if you need to set other environment variables like PYTHONLOGLEVEL (e.g., to DEBUG for verbose logs), these are also typically set within the LLM tool's MCP server configuration (see Setup Instructions by Tool).

Environment Variables

⚠️ Security Warning: Environment variables containing sensitive information like API keys and authentication tokens should be handled securely and never committed to version control.

For the full reference of all supported environment variables — including credential variables, timeout tuning, and Docs Server configuration — see docs/ENV.md.

The variables needed to get started are:

• DH_MCP_CONFIG_FILE (required): Path to your deephaven_mcp.json configuration file

  • Example: DH_MCP_CONFIG_FILE=/path/to/your/deephaven_mcp.json

• PYTHONLOGLEVEL: Controls the verbosity of logging output

  • Values: DEBUG, INFO, WARNING, ERROR
  • Default: INFO
  • Example: PYTHONLOGLEVEL=DEBUG

• Custom authentication variables: Any environment variable specified in your deephaven_mcp.json configuration's auth_token_env_var field will be used to source authentication tokens

  • Example: If config specifies "auth_token_env_var": "MY_AUTH_TOKEN", then MY_AUTH_TOKEN=username:password
  • Note: This is a more secure alternative to hardcoding tokens in configuration files

Browser Access to Created Sessions

When you create a Deephaven session via the MCP tools, you may want to access it through a web browser. By default, authentication credentials are not returned through MCP tools for security.

Viewing Credentials in Console

When a session is created with an auto-generated token, the connection information is logged to your console:

====================================================================
🔑 Session 'my-analysis' Created - Browser Access Information:
   Port: 45123
   Base URL: http://localhost:45123
   Auth Token: abc123xyz789...
   Browser URL: http://localhost:45123/?psk=abc123xyz789

   To retrieve credentials via MCP tool, set security.community.credential_retrieval_mode
   in your deephaven_mcp.json configuration.
====================================================================

You can copy this URL directly into your browser.

Retrieving Credentials via MCP Tool (Optional)

If you want AI agents to retrieve credentials programmatically, you can enable the session_community_credentials tool in your configuration:

1. Edit your deephaven_mcp.json:

   Copy

   {
     "security": {
       "community": {
         "credential_retrieval_mode": "dynamic_only"
       }
     },
     "community": {
       "session_creation": {
         "defaults": {
           "launch_method": "docker",
           "heap_size_gb": 4
         }
       }
     }
   }

   Valid credential_retrieval_mode values:

   • "none" (default): Credential retrieval disabled for all sessions (most secure)
   • "dynamic_only": Only auto-generated tokens from dynamically created sessions (recommended for development)
   • "static_only": Only pre-configured tokens from static sessions in your config
   • "all": Both dynamic and static session credentials

2. Use the tool:

   Ask your AI assistant: "Get me the browser URL for session 'my-analysis'"

   The AI will use session_community_credentials to retrieve the authenticated URL.

   🔒 SECURITY WARNING

   This tool exposes sensitive credentials. Only enable credential retrieval if the MCP server is running locally and you understand the security implications. NEVER enable when accessible over untrusted networks.

Applying Configuration Changes

After creating or modifying your MCP configuration, you must restart your IDE or AI assistant for the changes to take effect.

Restart and Verify

1. Restart your tool completely (Claude Desktop, VS Code, Cursor, etc.)

2. Check MCP server status in your tool's interface - you should see deephaven-systems and deephaven-docs listed

3. Test the connection by asking your AI assistant:

   Copy

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

   Your AI assistant should connect to both servers and respond with information about Deephaven capabilities and available sessions.

If the servers don't appear or you encounter errors, see the Troubleshooting section.

AI Tool Setup

This section explains how to connect Deephaven to your AI assistant or IDE. While the goal is the same -— pointing your tool to the Deephaven MCP servers -— the specific configuration steps vary for each tool.

How Configuration Works

All AI tools that support MCP use the same core configuration format: a JSON object called "mcpServers". This object defines how to launch the Deephaven MCP servers.

The mcpServers object is always the same - what differs between tools is only where this object goes in their configuration file:

Basic Configuration

Here's the standard mcpServers configuration for Deephaven. It works for both uv and pip installations.

Note: you will not start these mcpServers directly. When configuration is supplied to your AI Tool, the servers will be started via that tool.

⚙️ Important: All paths in the following examples must be absolute paths. Replace /full/path/to/your/ with the correct absolute path to your project directory (where the venv was setup).

"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"
    ]
  }
}

📝 Note: Change "PYTHONLOGLEVEL": "INFO" to "PYTHONLOGLEVEL": "DEBUG" for detailed server logs (see Troubleshooting).

Direct HTTP Server Configuration

The Deephaven MCP Docs Server natively supports streaming HTTP connections and can be accessed directly by AI agents without requiring the mcp-proxy tool. This provides optimal performance with lower latency and reduced overhead compared to the proxy-based approach.

How It Works:

• The docs server runs as a FastAPI web service with native MCP streaming HTTP support
• It accepts direct HTTP connections on https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp
• Modern AI agents can connect directly using their built-in streaming HTTP clients
• This eliminates the need for a local proxy process, simplifying the setup

When to Use Direct HTTP:

• Your AI agent supports native streaming HTTP MCP connections
• You want optimal performance and reduced resource usage
• You prefer simpler configuration without local proxy processes

When to Use Proxy-Based Approach:

• Your AI agent only supports stdio MCP connections
• You need universal compatibility across all MCP clients
• You're troubleshooting connection issues

⚠️ Note: Each tool uses different configuration schemas for direct HTTP servers. The examples below show tool-specific formats.

For Windsurf IDE:

"deephaven-docs": {
  "serverUrl": "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp",
  "disabled": false
}

For VS Code:

"deephaven-docs": {
  "type": "http",
  "url": "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
}

For more details on HTTP server configuration, see the Windsurf MCP documentation and VS Code HTTP servers guide.

📝 Note: Claude Desktop and Cursor currently require the proxy-based approach shown in the standard configuration above.

Setup Instructions by Tool

The following sections provide specific integration steps for each supported IDE and AI assistant platform, covering the required configuration and file locations.

Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config to configure your MCP servers:

{
  "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"
      ]
    }
  }
}

Additional Resources:

• MCP User Quickstart Guide
• MCP Troubleshooting guide
• Claude Desktop MCP Troubleshooting guide

Cursor

Create or edit an MCP configuration file:

• Project-specific: .cursor/mcp.json in your project root
• Global: ~/.cursor/mcp.json for all projects

{
  "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"
      ]
    }
  }
}

Additional Resources:

• Cursor MCP documentation

VS Code (GitHub Copilot)

To add MCP servers to your workspace, run the MCP: Add Server command from the Command Palette (Cmd-Shift-P), then select Workspace Settings to create the .vscode/mcp.json file. Alternatively, create .vscode/mcp.json manually in your project root.

Configure your servers:

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

You will see the mcp servers listed in the Extensions sidebar under "MCP Servers". (Collapse the sections for extensions to install to have the mcp servers easily visible.)

Additional Resources:

• VS Code MCP documentation
• VS Code MCP Configuration format reference
• VS Code MCP Troubleshooting guide

Windsurf

Go to Windsurf Settings > Cascade > MCP Servers > Manage MCPs > View Raw Config to open ~/.codeium/windsurf/mcp_config.json for editing.

Configure the file with your Deephaven servers:

{
  "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"
      ]
    }
  }
}

Additional Resources:

• Windsurf MCP documentation
• Windsurf MCP Troubleshooting guide

Advanced Usage

• Detailed Server APIs and Tools: For in-depth information about the tools exposed by the Systems Server (e.g., mcp_reload, session_tables_schema) and the Docs Server (docs_chat), refer to the Developer & Contributor Guide.
• uv Workflow: For more details on using uv for project management, see docs/UV.md.
• Deephaven Documentation:
  • Deephaven Documentation
  • Deephaven Community Core Python API Reference
  • Deephaven Enterprise Python API Reference

Troubleshooting

This section provides comprehensive guidance for diagnosing and resolving common issues with Deephaven MCP setup and operation. Issues are organized by category, starting with the most frequently encountered problems.

Quick Fixes

Before diving into detailed troubleshooting, try these common solutions:

1. Restart your IDE/AI assistant after any configuration changes
2. Check that all file paths are absolute in your JSON configurations
3. Verify your virtual environment is activated when running commands
4. Validate JSON syntax using https://jsonlint.com or your IDE's JSON validator

Common Error Messages

JSON Configuration Issues

Most configuration problems stem from JSON syntax errors or incorrect paths:

• Invalid JSON Syntax:

  • Missing or extra commas, brackets, or quotes
  • Use JSON validator to check syntax
  • Common mistake: trailing comma in last object property

• Incorrect File Paths:

  • All paths in JSON configurations must be absolute paths
  • Use forward slashes / even on Windows in JSON
  • Verify files exist at the specified paths

• Environment Variable Issues:

  • DH_MCP_CONFIG_FILE must point to valid deephaven_mcp.json file
  • Environment variables in env block must use correct names
  • Sensitive values should use environment variables, not hardcoded strings

LLM Tool Connection Issues

• LLM Tool Can't Connect / Server Not Found:
  • Verify all paths in your LLM tool's JSON configuration are absolute and correct
  • Ensure DH_MCP_CONFIG_FILE environment variable is correctly set in the JSON config and points to a valid deephaven_mcp.json file
  • Ensure any Deephaven Community Core sessions you intend to use (as defined in deephaven_mcp.json) are running and accessible from the MCP Systems Server's environment
  • Check for typos in server names, commands, or arguments in the JSON config
  • Validate the syntax of your JSON configurations (mcpServers object in the LLM tool, and deephaven_mcp.json) using a JSON validator tool or your IDE's linting features
  • Set PYTHONLOGLEVEL=DEBUG in the env block of your JSON config to get more detailed logs from the MCP servers

Network and Firewall Issues

• Firewall or Network Issues:
  • Ensure that there are no firewall rules (local or network) preventing:
    • The MCP Systems Server from connecting to your Deephaven Community Core instances on their specified hosts and ports.
    • Your LLM tool or client from connecting to the mcp-proxy's target URL (https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io) if using the Docs Server.
  • Test basic network connectivity (e.g., using ping or curl from the relevant machine) if connections are failing.

Command and Path Issues

• command not found for uv (in LLM tool logs):
  • Ensure uv is installed and its installation directory is in your system's PATH environment variable, accessible by the LLM tool.
• command not found for dh-mcp-systems-server or mcp-proxy (venv option in LLM tool logs):
  • Double-check that the command field in your JSON config uses the correct absolute path to the executable within your .venv/bin/ (or .venv\Scripts\) directory.

Virtual Environment and Dependency Issues

• Virtual Environment Not Activated:

  • Symptoms: Module not found errors, command not found for installed packages
  • Solution: Activate your virtual environment before running commands
  • Verify: Check that your prompt shows the environment name in parentheses

• Dependency Installation Problems:

  • Missing Dependencies: Run uv pip install -e ".[dev]" in your virtual environment
  • Version Conflicts: Check for conflicting package versions in your environment
  • Platform-Specific Issues: Some packages may require platform-specific compilation

• Python Version Compatibility:

  • Deephaven MCP requires Python 3.11 or higher
  • Check your Python version: python --version
  • Ensure your virtual environment uses the correct Python version

Server and Environment Issues

• Server Startup Failures:

  • Python Errors: Check server logs for Python tracebacks and ensure dependencies are installed correctly
  • Permission Issues: Ensure the MCP server process has necessary file and network permissions
  • Path Issues: Verify all executable paths in configuration are correct and accessible

• Runtime Issues:

  • Coroutine errors: Restart the MCP server after making code changes

  • Memory issues: Monitor server resource usage, especially with large datasets

  • Cache issues: Clear Python cache files if experiencing persistent issues:

    Copy

    find . -name "*.pyc" -delete

• uv-Specific Issues:

  • Command failures: Ensure uv is installed and pyproject.toml is properly configured
  • Path issues: Verify uv is in your system's PATH environment variable
  • Project detection: Run uv commands from the project root directory

Deephaven Session Configuration Issues

• Session Connection Failures:

  • Verify your deephaven_mcp.json file syntax and content - see Community Configuration or Enterprise Configuration
  • Check the Environment Variables section for required environment variables
  • Ensure target Deephaven Community Core instances are running and network-accessible
  • Check that the MCP Systems Server process has read permissions for the configuration file

• Session ID Format Issues:

  • Use the correct format: {type}:{source}:{session_name}
  • Examples: community:local_dev:my_session, enterprise:staging:analytics
  • Avoid special characters or spaces in session names

• Authentication Problems:

  • Community sessions: Verify connection URLs and authentication - see Community Configuration Fields
  • Enterprise sessions: Check authentication tokens and certificate paths - see Enterprise Configuration Fields
  • Environment variables: Ensure sensitive credentials are properly set - see Environment Variables
  • Credential retrieval: Check Security Configuration for credential access settings

Platform-Specific Issues

• Windows-Specific:

  • Use forward slashes / in JSON file paths, even on Windows
  • Executable paths should point to .venv\Scripts\ instead of .venv/bin/
  • PowerShell execution policy may block script execution

• macOS-Specific:

  • Gatekeeper may block unsigned executables
  • File permissions may need adjustment: chmod +x /path/to/executable
  • Network security settings may block connections

• Linux-Specific:

  • Check firewall settings: ufw status or iptables -L
  • Verify user permissions for network binding
  • SELinux policies may restrict server operations

Log Analysis and Debugging

Log File Locations:

• Claude Desktop (macOS): ~/Library/Logs/Claude/mcp-server-*.log
• VS Code/Copilot: Check VS Code's Output panel and Developer Console
• Cursor IDE: Check the IDE's log panel and developer tools
• Windsurf IDE: Check the IDE's integrated terminal and log outputs

What to Look For in Logs:

• Startup errors: Python tracebacks, missing modules, permission denied
• Connection errors: Network timeouts, refused connections, DNS resolution failures
• Configuration errors: JSON parsing errors, invalid paths, missing environment variables
• Runtime errors: Unexpected exceptions, resource exhaustion, timeout errors

Enabling Debug Logging:

Set PYTHONLOGLEVEL=DEBUG in your MCP server configuration's env block for detailed logging:

{
  "mcpServers": {
    "deephaven-systems": {
      "command": "/path/to/dh-mcp-systems-server",
      "env": {
        "DH_MCP_CONFIG_FILE": "/path/to/deephaven_mcp.json",
        "PYTHONLOGLEVEL": "DEBUG"
      }
    }
  }
}

When to Seek Help

If you've tried the above solutions and are still experiencing issues:

1. Gather Information:

   • Error messages from logs
   • Your configuration files (remove sensitive information)
   • System information (OS, Python version, package versions)
   • Steps to reproduce the issue

2. Check Documentation:

   • Review the Developer Guide for advanced troubleshooting
   • Check the GitHub Issues for similar problems

3. Community Support:

   • Post in Deephaven Community Slack
   • Create a GitHub issue with detailed information
   • Check Deephaven Community Forums

IDE and AI Assistant Troubleshooting

For IDE and AI assistant troubleshooting, refer to the official documentation for each tool:

• VS Code (GitHub Copilot): VS Code MCP Troubleshooting guide
• Cursor: Cursor MCP documentation
• Claude Desktop: Claude Desktop MCP Troubleshooting guide
• Windsurf: Windsurf MCP Troubleshooting guide

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.