Metadata-Version: 2.4
Name: deephaven-mcp
Version: 0.0.14
Summary: Unified Python package providing Model Context Protocol (MCP) servers for Deephaven: orchestrate Community Core data workers and power Documentation Q&A with LLMs. Supports AI-driven data workflows and agentic documentation assistance in a single deployable package.
Author-email: Deephaven Data Labs <support@deephaven.io>
License: Apache-2.0
Project-URL: Homepage, https://deephaven.io
Project-URL: Documentation, https://deephaven.io/docs/
Project-URL: Repository, https://github.com/deephaven/deephaven-mcp
Project-URL: Issues, https://github.com/deephaven/deephaven-mcp/issues
Keywords: deephaven,mcp,model-context-protocol,ai,documentation,llm,orchestration,community-core,docs,q&a
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing_extensions>=4.3.0
Requires-Dist: aiofiles>=23.2.1
Requires-Dist: aiohttp>=3.11.18
Requires-Dist: autogen-ext[mcp]>=0.5.4
Requires-Dist: mcp[cli]>=1.12.0
Requires-Dist: mcp-proxy
Requires-Dist: pydeephaven>=0.39
Requires-Dist: fastapi>=0.116.0
Requires-Dist: uvicorn[standard]>=0.35.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiolimiter>=1.1.0
Requires-Dist: autogen-core
Requires-Dist: autogen-ext
Requires-Dist: google-cloud-logging>=3.8.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
Requires-Dist: httpx[cli]>=0.24.0; extra == "test"
Requires-Dist: deephaven-server>=0.39; extra == "test"
Provides-Extra: dev
Requires-Dist: deephaven-mcp[test]; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
Requires-Dist: mypy>=1.6.0; extra == "dev"
Requires-Dist: types-aiofiles; extra == "dev"
Requires-Dist: typing_extensions>=4.3.0; extra == "dev"
Requires-Dist: pre-commit>=3.4.0; extra == "dev"
Provides-Extra: coreplus
Dynamic: license-file

# deephaven-mcp

[![PyPI](https://img.shields.io/pypi/v/deephaven-mcp)](https://pypi.org/project/deephaven-mcp/)
[![License](https://img.shields.io/github/license/deephaven/deephaven-mcp)](https://github.com/deephaven/deephaven-mcp/blob/main/LICENSE)
[![Build Status](https://img.shields.io/github/actions/workflow/status/deephaven/deephaven-mcp/unit-tests.yml?branch=main)](https://github.com/deephaven/deephaven-mcp/actions/workflows/unit-tests.yml)

## Table of Contents

- [Overview](#overview)
- [🚀 Quick Start](#-quick-start)
- [🔄 Quick Upgrade](#-quick-upgrade)
- [Key Use Cases](#key-use-cases)
- [Deephaven MCP Components](#deephaven-mcp-components)
- [Available MCP Tools](#available-mcp-tools)
- [Architecture Diagrams](#architecture-diagrams)
- [Prerequisites](#prerequisites)
- [Installation & Initial Setup](#installation--initial-setup)
- [Upgrading](#upgrading)
- [Configuring `deephaven_mcp.json`](#configuring-deephaven_mcpjson)
- [Environment Variables](#environment-variables)
- [Browser Access to Created Sessions](#browser-access-to-created-sessions)
- [AI Tool Setup](#ai-tool-setup)
- [Applying Configuration Changes](#applying-configuration-changes)
- [Troubleshooting](#troubleshooting)
- [Advanced Usage](#advanced-usage)
- [Contributing](#contributing)
- [Community & Support](#community--support)
- [License](#license)

---

## Overview

**Supercharge your AI workflows with real-time data.** Deephaven MCP brings the power of [live dataframes](https://deephaven.io) directly to your favorite AI tools -— [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.sh/), [VS Code (GitHub Copilot)](https://code.visualstudio.com/docs/copilot/overview), [Windsurf](https://codeium.com/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](https://spec.modelcontextprotocol.io/) to provide seamless integration between [Deephaven Community Core](https://deephaven.io/community/) and [Deephaven Enterprise](https://deephaven.io/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.

---

## 🚀 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](https://deephaven.io/core/docs/getting-started/quickstart/) first.

### 1. Create Virtual Environment

```bash
python3.11 -m venv .venv
```

> **Note:** Replace `python3.11` with any supported Python version (3.11, 3.12, or 3.13).

### 2. Install CorePlus Client Wheel (optional, Enterprise only)

**Skip this step if you only need Community Core support.**

If you need Enterprise systems support, first download the installation script, then install the `deephaven-coreplus-client` wheel (obtain from your Deephaven Enterprise administrator):

```bash
# Download the installation script
curl -O https://raw.githubusercontent.com/deephaven/deephaven-mcp/main/bin/dev_manage_coreplus_client.sh
chmod +x dev_manage_coreplus_client.sh

# Install the CorePlus wheel
./dev_manage_coreplus_client.sh install-wheel --venv .venv --wheel-file /path/to/deephaven_coreplus_client-X.Y.Z-py3-none-any.whl
```

### 3. Install Deephaven MCP and Dependencies

Choose the installation that matches your needs:

**Basic installation:**

```bash
.venv/bin/pip install deephaven-mcp
```

Connects to existing Community Core instances. If you have [Docker](https://www.docker.com/get-started/) installed on your system, you can also dynamically create Community Core sessions using Docker.

**For python-based Community Core session creation:**

If you want to use the python launch method (no Docker required), install `deephaven-server`:

```bash
pip install deephaven-server
```

This installs in the same venv as the MCP server. For advanced use cases with a separate venv, see the `python_venv_path` parameter in [Community Session Creation Configuration](#community-session-creation-configuration).

**Add Enterprise support:**

```bash
.venv/bin/pip install "deephaven-mcp[coreplus]"
```

Adds ability to connect to Deephaven Enterprise systems (requires step 2). If you also want python-based session creation, separately install `deephaven-server` as shown above.

### 4. Create Configuration File

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

```json
{
  "community": {
    "sessions": {
      "local": {
        "host": "localhost",
        "port": 10000,
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token": "YOUR_PASSWORD_HERE"
      }
    },
    "session_creation": {
      "defaults": {
        "launch_method": "python"
      }
    }
  }
}
```

> **⚠️ Security Note**: Since this file contains authentication credentials, set restrictive permissions:
> ```bash
> chmod 600 deephaven_mcp.json
> ```

> **💡 Dynamic Sessions**: The `session_creation` section enables on-demand [Community Core](https://deephaven.io/community/) session creation. Requirements: `deephaven-server` (installed in any Python venv) for the python method, or [Docker](https://www.docker.com/get-started/) for the docker method. See [Community Session Creation Configuration](#community-session-creation-configuration) for details.

### 5. Configure Your AI Tool

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

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

**For other tools**, see the [detailed setup instructions](#setup-instructions-by-tool) below.

### 6. Try It Out!

Restart your AI tool and try 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](#troubleshooting) section, ask the built-in docs server about Deephaven features, or join the [Deephaven Community Slack](https://deephaven.io/slack)!

---

## 🔄 Quick Upgrade

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

### 1. Remove the old virtual environment

```bash
rm -rf .venv
```

### 2. Reinstall with the latest version

Repeat the [🚀 Quick Start](#-quick-start) steps 1-3 above to reinstall with the latest version.

For more upgrade options, see the detailed [Upgrading](#upgrading) section below.

---

## Key Use Cases

*   **AI-Assisted Development**: Integrate Deephaven with LLM-powered development tools (e.g., [Claude Desktop](https://www.anthropic.com/claude), [GitHub Copilot](https://github.com/features/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](https://deephaven.io/community/) sessions and [Deephaven Enterprise](https://deephaven.io/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
- **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

*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/DEVELOPER_GUIDE.md).

---

### Docs Server
Connects to Deephaven's documentation knowledge base via 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

```mermaid
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](#systems-server-architecture), which in turn manages and communicates with [Deephaven Community Core](https://deephaven.io/community/) sessions and [Deephaven Enterprise](https://deephaven.io/enterprise/) systems.*

### Docs Server Architecture

```mermaid
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`](https://github.com/modelcontextprotocol/mcp-proxy) to bridge stdio to streamable-http.*

---

## Prerequisites

*   **Python**: Version 3.11 or later. ([Download Python](https://www.python.org/downloads/))
*   **Docker (Optional)**: Required for Docker-based community session creation. ([Download Docker](https://www.docker.com/get-started/))
*   **Access to Deephaven systems:** To use the [MCP Systems Server](#systems-server-architecture), you will need one or more of the following:
    *   **[Deephaven Community Core](https://deephaven.io/community/) instance(s):** For development and personal use.
    *   **[Deephaven Enterprise](https://deephaven.io/enterprise/) system(s):** For enterprise-level features and capabilities.
*   **Choose your Python environment setup method:**
    *   **Option A: [`uv`](https://docs.astral.sh/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](https://github.com/astral-sh/uv#installation).
    *   **Option B: Standard Python `venv` and `pip`**: Uses Python's built-in [virtual environment (`venv`)](https://docs.python.org/3/library/venv.html) tools and [`pip`](https://pip.pypa.io/en/stable/getting-started/).
*   **Configuration Files**: Each integration requires proper configuration files (specific locations detailed in each integration section)

---

## Installation & Initial Setup

The recommended way to install `deephaven-mcp` is from PyPI. This provides the latest stable release and is suitable for most users.

### Installing from PyPI

Choose one of the following Python environment and package management tools:

#### Option A: Using `uv` (Fast, Recommended)

1.  **Install `uv` (if not already installed):**
    You can install `uv` using `pip`:
    ```sh
    pip install uv
    ```
    For more information on `uv`, see the official [GitHub project](https://github.com/astral-sh/uv) or the local [`uv` documentation](docs/UV.md).

2.  **Create a virtual environment with your desired Python version:**
    
    [uv](docs/UV.md) works best when operating within a virtual environment. To create one (e.g., named `.venv`) using a specific Python interpreter (e.g., Python 3.11), run:
    ```sh
    uv venv .venv -p 3.11 
    ```
    Replace `3.11` with your target Python version (e.g., `3.12`) or the full path to a Python executable.

3.  **Install the CorePlus client wheel (optional, Enterprise systems only):**

    **Skip this step if you only need Community Core support.**

    If you need Enterprise systems support, the `deephaven-coreplus-client` wheel must be installed first. This wheel is not available on PyPI and must be obtained from your Deephaven Enterprise administrator.

    Once you have the wheel file, install it using the provided script:

    ```sh
    ./bin/dev_manage_coreplus_client.sh install-wheel --venv .venv --wheel-file /path/to/deephaven_coreplus_client-X.Y.Z-py3-none-any.whl
    ```

    Replace `/path/to/deephaven_coreplus_client-X.Y.Z-py3-none-any.whl` with the actual path to the wheel file provided by your administrator. The script handles dependency version conflicts automatically.

4.  **Install `deephaven-mcp`:**

    This command installs `deephaven-mcp` and its dependencies into the virtual environment.

    ```sh
    # For Community Core only (most users)
    uv pip install deephaven-mcp
    
    # For Enterprise systems (if you completed step 3)
    uv pip install "deephaven-mcp[coreplus]"
    ```

#### Option B: Using Standard `pip` and `venv`

1.  **Create a virtual environment** (e.g., named `.venv`):
    ```sh
    python -m venv .venv
    ```

2.  **Install the CorePlus client wheel (optional, Enterprise systems only):**
    
    **Skip this step if you only need Community Core support.**
    
    If you need Enterprise systems support, the `deephaven-coreplus-client` wheel must be installed first. This wheel is not available on PyPI and must be obtained from your Deephaven Enterprise administrator.
    
    Once you have the wheel file, install it using the provided script:
    ```sh
    ./bin/dev_manage_coreplus_client.sh --venv .venv install-wheel --wheel-file /path/to/deephaven_coreplus_client-X.Y.Z-py3-none-any.whl
    ```
    
    Replace `/path/to/deephaven_coreplus_client-X.Y.Z-py3-none-any.whl` with the actual path to the wheel file provided by your administrator. The script handles dependency version conflicts automatically.

3.  **Install `deephaven-mcp`**:

    This command installs `deephaven-mcp` and its dependencies into the virtual environment.

    **For Community Core only (most users):**
    ```sh
    .venv/bin/pip install deephaven-mcp
    ```

    **For Enterprise systems (if you completed step 2):**
    ```sh
    .venv/bin/pip install "deephaven-mcp[coreplus]"
    ```

---

## Upgrading

### Recommended: Recreate Virtual Environment

The simplest and most reliable way to upgrade is to delete your virtual environment and recreate it:

```bash
# Remove the old virtual environment
rm -rf .venv
```

Then follow the installation steps again:

- For quickstart users: Repeat steps 1-3 from the [Quick Start](#-quick-start) section
- For detailed installation: Follow the [Installing from PyPI](#installing-from-pypi) instructions

This approach ensures:

- Clean installation with no dependency conflicts
- Correct CorePlus wheel version for Enterprise users
- No leftover packages from previous versions

After recreating the environment, restart your AI tool to use the new version.

### Alternative: In-Place Upgrade

If you prefer to upgrade without recreating the virtual environment:

**For Community Core only:**

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

**For Enterprise systems:**

```bash
.venv/bin/pip install --upgrade "deephaven-mcp[coreplus]"
```

> **⚠️ Note for Enterprise Users**: When upgrading in-place, ensure your CorePlus client wheel version matches your Enterprise server version. Contact your Deephaven Enterprise administrator for the correct wheel version.

After upgrading, restart your AI tool to use the new version.

---

## Configuring `deephaven_mcp.json`

This section explains how to configure the [Deephaven MCP Systems Server](#systems-server) to connect to and manage your [Deephaven Community Core](https://deephaven.io/community/) instances and [Deephaven Enterprise](https://deephaven.io/enterprise/) systems. This involves creating a [systems session definition file](#the-deephaven_mcpjson-file-defining-your-community-sessions) 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).

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.

### Community Core Configuration

#### Community Examples

**Minimal configuration (no connections):**
```json
{}
```

**Anonymous authentication (simplest):**
```json
{
  "community": {
    "sessions": {
      "my_local_server": {
        "host": "localhost",
        "port": 10000
      }
    }
  }
}
```

**PSK authentication:**
```json
{
  "community": {
    "sessions": {
      "psk_server": {
        "host": "localhost",
        "port": 10000,
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token": "your-shared-secret-key"
      }
    }
  }
}
```

**Basic authentication with environment variable:**
```json
{
  "community": {
    "sessions": {
      "prod_session": {
        "host": "deephaven-prod.example.com",
        "port": 10000,
        "auth_type": "Basic",
        "auth_token_env_var": "DH_AUTH_TOKEN"
      }
    }
  }
}
```

**TLS/SSL configuration:**
```json
{
  "community": {
    "sessions": {
      "secure_tls_session": {
        "host": "secure.deephaven.example.com",
        "port": 443,
        "use_tls": true,
        "tls_root_certs": "/path/to/ca.pem",
        "client_cert_chain": "/path/to/client-cert.pem",
        "client_private_key": "/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.*

| Field | Type | Required When | Description |
|-------|------|---------------|-------------|
| `host` | string | Optional | Hostname or IP address of the Deephaven Community Core session (e.g., `"localhost"`) |
| `port` | integer | Optional | Port number for the session connection (e.g., `10000`) |
| `auth_type` | string | Optional | Authentication type: `"PSK"` (shorthand), `"Anonymous"` (default), `"Basic"`, or full class names like `"io.deephaven.authentication.psk.PskAuthenticationHandler"` |
| `auth_token` | string | Optional | Authentication token. For `"Basic"` auth: `"username:password"` format. Mutually exclusive with `auth_token_env_var` |
| `auth_token_env_var` | string | Optional | Environment variable name containing the auth token (e.g., `"MY_AUTH_TOKEN"`). More secure than hardcoding tokens |
| `never_timeout` | boolean | Optional | If `true`, attempts to configure the session to never time out |
| `session_type` | string | Optional | Type of session to create: `"groovy"` or `"python"` |
| `use_tls` | boolean | Optional | Set to `true` if the connection requires TLS/SSL |
| `tls_root_certs` | string | Optional | Absolute path to PEM file with trusted root CA certificates for TLS verification |
| `client_cert_chain` | string | Optional | Absolute path to PEM file with client's TLS certificate chain (for mTLS) |
| `client_private_key` | string | Optional | Absolute path to PEM file with client's private key (for mTLS) |

#### 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](https://www.docker.com/get-started/) 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

| Field | Type | Required When | Description |
|-------|------|---------------|-------------|
| `session_creation` | object | Optional | Configuration for creating community sessions. If omitted, session creation tools are unavailable |
| `session_creation.max_concurrent_sessions` | integer | Optional | Maximum concurrent sessions (default: 5). Set to 0 to disable session creation |
| `session_creation.defaults` | object | Optional | Default parameters for new sessions |
| `session_creation.defaults.launch_method` | string | Optional | How to launch sessions: `"docker"` or `"python"` (default: "docker") |
| `session_creation.defaults.auth_type` | string | Optional | Authentication type: `"PSK"` (default), `"Anonymous"`, or full class name `"io.deephaven.authentication.psk.PskAuthenticationHandler"`. Case-insensitive for shorthand. Basic auth not supported for dynamic sessions |
| `session_creation.defaults.auth_token` | string | Optional | Pre-shared key for PSK auth. If omitted with PSK auth, a secure token is auto-generated |
| `session_creation.defaults.auth_token_env_var` | string | Optional | Environment variable containing auth token. Mutually exclusive with `auth_token` |
| `session_creation.defaults.programming_language` | string | Optional | Programming language for Docker sessions: `"Python"` or `"Groovy"` (default: "Python"). Docker only. Mutually exclusive with `docker_image`. See examples below. |
| `session_creation.defaults.docker_image` | string | Optional | Custom Docker image to use. Docker only. Mutually exclusive with `programming_language`. If neither specified, defaults to Python image. See examples below. |
| `session_creation.defaults.docker_memory_limit_gb` | float | Optional | Container memory limit in GB (Docker only, default: no limit) |
| `session_creation.defaults.docker_cpu_limit` | float | Optional | Container CPU limit in cores (Docker only, default: no limit) |
| `session_creation.defaults.docker_volumes` | array | Optional | Volume mounts in format `["host:container:mode"]` (Docker only, default: []) |
| `session_creation.defaults.python_venv_path` | string | Optional | Path to custom Python venv directory (Python only). If provided, uses deephaven from that venv. If null (default), uses same venv as MCP server. Raises error if used with docker. |
| `session_creation.defaults.heap_size_gb` | integer | Optional | JVM heap size in gigabytes (default: 4) |
| `session_creation.defaults.extra_jvm_args` | array | Optional | Additional JVM arguments (e.g., `["-XX:+UseG1GC"]`, default: []) |
| `session_creation.defaults.environment_vars` | object | Optional | Environment variables as key-value pairs (default: {}) |
| `session_creation.defaults.startup_timeout_seconds` | float | Optional | Maximum time to wait for session startup (default: 60) |
| `session_creation.defaults.startup_check_interval_seconds` | float | Optional | Time between health checks during startup (default: 2) |
| `session_creation.defaults.startup_retries` | integer | Optional | Connection attempts per health check (default: 3) |

**Docker Image Configuration Examples:**

```json
// ✅ 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](https://jupyter.org/) 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):**
```json
{
  "enterprise": {
    "systems": {
      "dev_enterprise_system": {
        "connection_json_url": "https://dev-enterprise.example.com/iris/connection.json",
        "auth_type": "password",
        "username": "admin",
        "password": "your-password-here"
      }
    }
  }
}
```

**Password authentication (environment variable):**
```json
{
  "enterprise": {
    "systems": {
      "my_enterprise_system": {
        "connection_json_url": "https://my-enterprise.example.com/iris/connection.json",
        "auth_type": "password",
        "username": "admin",
        "password_env_var": "DH_ENTERPRISE_PASSWORD"
      }
    }
  }
}
```

**Private key authentication:**
```json
{
  "enterprise": {
    "systems": {
      "saml_enterprise": {
        "connection_json_url": "https://enterprise.example.com/iris/connection.json",
        "auth_type": "private_key",
        "private_key_path": "/path/to/your/private_key.pem"
      }
    }
  }
}
```

#### Enterprise Configuration Fields

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

| Field | Type | Required When | Description |
|-------|------|---------------|-------------|
| `connection_json_url` | string | Always | URL to the Enterprise server's `connection.json` file. For standard HTTPS port 443, no port is needed (e.g., `"https://enterprise.example.com/iris/connection.json"`). For non-standard ports, include the port number explicitly (e.g., `"https://enterprise.example.com:8123/iris/connection.json"`) |
| `auth_type` | string | Always | Authentication method: `"password"` for username/password auth, or `"private_key"` for private key-based auth (e.g., SAML) |
| `username` | string | `auth_type` = `"password"` | Username for authentication |
| `password` | string | `auth_type` = `"password"` | Password (use `password_env_var` instead for security) |
| `password_env_var` | string | `auth_type` = `"password"` | Environment variable containing the password (recommended) |
| `private_key_path` | string | `auth_type` = `"private_key"` | Absolute path to private key file |
| `use_tls` | boolean | Optional | Enable TLS encryption for connections (default: false) |
| `tls_root_certs` | string | Optional | Absolute path to custom TLS root certificate bundle file |
| `tls_verify_server_cert` | boolean | Optional | Verify server TLS certificate (default: true when TLS enabled) |
| `client_cert_chain` | string | Optional | Absolute path to client certificate chain file for mutual TLS |
| `client_private_key` | string | Optional | Absolute path to client private key file for mutual TLS |
| `session_creation` | object | Optional | Configuration for creating enterprise sessions. If omitted, session creation tools are unavailable |
| `session_creation.max_concurrent_sessions` | integer | Optional | Maximum concurrent sessions (default: 5). Set to 0 to disable session creation |
| `session_creation.defaults` | object | Optional | Default parameters for new sessions |
| `session_creation.defaults.heap_size_gb` | float | Optional | Default JVM heap size in gigabytes for new sessions |
| `session_creation.defaults.programming_language` | string | Optional | Default programming language for new sessions ("Python" or "Groovy", default: "Python") |
| `session_creation.defaults.auto_delete_timeout` | integer | Optional | Default auto-deletion timeout in seconds for idle sessions (API default: 600) |
| `session_creation.defaults.server` | string | Optional | Default target server/environment name where sessions will be created |
| `session_creation.defaults.engine` | string | Optional | Default engine type for new sessions (e.g., "DeephavenCommunity") |
| `session_creation.defaults.extra_jvm_args` | array | Optional | Default additional JVM arguments for new sessions (e.g., ["-XX:+UseG1GC"]) |
| `session_creation.defaults.extra_environment_vars` | array | Optional | Default environment variables for new sessions (format: ["NAME=value"]) |
| `session_creation.defaults.admin_groups` | array | Optional | Default user groups with administrative permissions for new sessions |
| `session_creation.defaults.viewer_groups` | array | Optional | Default user groups with read-only access to new sessions |
| `session_creation.defaults.timeout_seconds` | float | Optional | Default session startup timeout in seconds (API default: 60) |
| `session_creation.defaults.session_arguments` | object | Optional | Default arguments for pydeephaven.Session constructor (passed as-is, no validation of contents) |

> **📝 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.

| Field | Type | Values | Description |
|-------|------|--------|-------------|
| `security.community.credential_retrieval_mode` | string | `"none"` (default), `"dynamic_only"`, `"static_only"`, `"all"` | Controls credential retrieval access |

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

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

```json
{
  "community": {
    "sessions": {
      "my_local_deephaven": {
        "host": "localhost",
        "port": 10000,
        "session_type": "python"
      },
      "psk_authenticated_session": {
        "host": "localhost",
        "port": 10001,
        "auth_type": "io.deephaven.authentication.psk.PskAuthenticationHandler",
        "auth_token": "your-shared-secret-key",
        "session_type": "python"
      },
      "basic_auth_session": {
        "host": "secure.deephaven.example.com",
        "port": 10002,
        "auth_type": "Basic",
        "auth_token": "username:password",
        "use_tls": true,
        "tls_root_certs": "/path/to/community_root.crt"
      }
    },
    "session_creation": {
      "max_concurrent_sessions": 5,
      "defaults": {
        "launch_method": "docker",
        "auth_type": "PSK",
        "docker_image": "ghcr.io/deephaven/server:latest",
        "docker_memory_limit_gb": null,
        "docker_cpu_limit": null,
        "docker_volumes": [],
        "heap_size_gb": 4.0,
        "extra_jvm_args": [],
        "environment_vars": {},
        "startup_timeout_seconds": 60,
        "startup_check_interval_seconds": 2,
        "startup_retries": 3
      }
    }
  },
  "enterprise": {
    "systems": {
      "prod_cluster": {
        "connection_json_url": "https://prod.enterprise.example.com/iris/connection.json",
        "auth_type": "password",
        "username": "your_username",
        "password_env_var": "ENTERPRISE_PASSWORD",
        "session_creation": {
          "max_concurrent_sessions": 3,
          "defaults": {
            "heap_size_gb": 8.0,
            "programming_language": "Groovy",
            "auto_delete_timeout": 3600,
            "server": "gpu-server-1",
            "engine": "DeephavenCommunity",
            "extra_jvm_args": ["-XX:+UseG1GC", "-XX:MaxGCPauseMillis=200"],
            "extra_environment_vars": ["PYTHONPATH=/custom/libs", "LOG_LEVEL=DEBUG"],
            "admin_groups": ["deephaven-admins", "data-team-leads"],
            "viewer_groups": ["analysts", "data-scientists"],
            "timeout_seconds": 120.0,
            "session_arguments": {"custom_setting": "example_value"}
          }
        }
      },
      "data_science_env": {
        "connection_json_url": "https://data-science.enterprise.example.com/iris/connection.json",
        "auth_type": "private_key",
        "private_key_path": "/path/to/your/private_key.pem"
      }
    }
  }
}
```


### 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:
> ```bash
> 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](#systems-server) where to find your `deephaven_mcp.json` file (detailed in [The `deephaven_mcp.json` File (Defining Your Community Sessions)](#the-deephaven_mcp.json-file-defining-your-community-sessions)). You will set this environment variable as part of the server launch configuration within your LLM tool, as detailed in the [Configure Your AI Agent / IDE to Use MCP Servers](#configure-your-ai-agent--ide-to-use-mcp-servers) section. 

When launched by an LLM tool, the [MCP Systems Server](#systems-server-architecture) 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 [Defining MCP Servers for Your LLM Tool (The `mcpServers` JSON Object)](#defining-mcp-servers-for-your-llm-tool-the-mcpservers-json-object)).

---

## Environment Variables

The following environment variables can be used to configure the behavior of the Deephaven MCP Systems Server.

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


### Core Configuration

* **`DH_MCP_CONFIG_FILE`**: Path to your `deephaven_mcp.json` configuration file
  * Example: `DH_MCP_CONFIG_FILE=/path/to/your/deephaven_mcp.json`
  * Default: Looks for `deephaven_mcp.json` in the current directory

* **`PORT`**: Port number for the MCP server
  * Example: `PORT=8000`
  * Default: `8000`

### Authentication

* **Environment variables for `auth_token_env_var`**: 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

### Debugging and Logging

* **`PYTHONLOGLEVEL`**: Controls the verbosity of logging output
  * Values: `DEBUG`, `INFO`, `WARNING`, `ERROR`
  * Example: `PYTHONLOGLEVEL=DEBUG`
  * Default: `INFO`

---

## 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/?authToken=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`:**

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


---

## 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:

| Tool | Configuration Structure |
|------|------------------------|
| **Windsurf, Cursor, Claude Desktop** | The `mcpServers` object is the root of the JSON file. |
| **VS Code** | The `mcpServers` object goes inside a `"servers"` key |

### Basic Configuration

Here's the standard `mcpServers` configuration for Deephaven. It works for both [`uv`](./docs/UV.md) and `pip` installations.

> **⚙️ 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.

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

> **📝 Note**: Change `"PYTHONLOGLEVEL": "INFO"` to `"PYTHONLOGLEVEL": "DEBUG"` for detailed server logs (see [Troubleshooting](#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`](https://github.com/modelcontextprotocol/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:**
```json
"deephaven-docs": {
  "serverUrl": "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp",
  "disabled": false
}
```

**For VS Code:**
```json
"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](https://docs.windsurf.com/windsurf/cascade/mcp) and [VS Code HTTP servers guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_http-and-server-sent-events-sse-servers).

> **📝 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:

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

**Additional Resources:**
- [MCP User Quickstart Guide](https://modelcontextprotocol.io/quickstart/user)
- [MCP Troubleshooting guide](https://modelcontextprotocol.io/docs/concepts/transports#troubleshooting)
- [Claude Desktop MCP Troubleshooting guide](https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)

### Cursor

Create or edit an MCP configuration file:
- **Project-specific**: `.cursor/mcp.json` in your project root
- **Global**: `~/.cursor/mcp.json` for all projects

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

**Additional Resources:**
- [Cursor MCP documentation](https://docs.cursor.com/en/context/mcp)

### VS Code (GitHub Copilot)

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

Configure your servers:

```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"
      }
    },
    "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:**
- [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
- [VS Code MCP Configuration format reference](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_configuration-format)
- [VS Code MCP Troubleshooting guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_troubleshoot-and-debug-mcp-servers)

### 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:

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

**Additional Resources:**
- [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp)
- [Windsurf MCP Troubleshooting guide](https://docs.windsurf.com/troubleshooting/windsurf-common-issues)

---

## 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:
   ```
   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](#troubleshooting) section.

---

## 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](https://jsonlint.com/) or your IDE's JSON validator

### Common Error Messages

| Error | Where You'll See This | Solution |
|-------|----------------------|----------|
| `spawn uv ENOENT` | IDE/AI assistant logs | Use full path to [`uv`](docs/UV.md) |
| `Connection failed` | MCP server logs | Check internet connection and server URLs |
| `Config not found` | MCP server startup | Verify full path to `deephaven_mcp.json` |
| `Permission denied` | Command execution | Ensure [`uv`](docs/UV.md) executable has proper permissions |
| `Python version error` | Virtual environment | Verify supported Python version is installed and accessible |
| `JSON parse error` | IDE/AI assistant logs | Fix JSON syntax errors in configuration files |
| `Module not found: deephaven_mcp` | MCP server logs | Ensure virtual environment is activated and dependencies installed |
| `Port already in use` | Server startup logs | Change `PORT` environment variable or kill conflicting process |
| `Invalid session_id format` | MCP tool responses | Use format: `{type}:{source}:{session_name}` |

### 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](https://jsonlint.com/) 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 worker file
  * Ensure any [Deephaven Community Core](https://deephaven.io/community/) sessions you intend to use (as defined in `deephaven_mcp.json`) are running and accessible from the [MCP Systems Server](#systems-server-architecture)'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](https://jsonlint.com/) 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](#systems-server-architecture) from connecting to your [Deephaven Community Core](https://deephaven.io/community/) 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](#docs-server).
  * Test basic network connectivity (e.g., using [`ping`](https://en.wikipedia.org/wiki/Ping_(networking_utility)) or [`curl`](https://curl.se/docs/manpage.html) from the relevant machine) if connections are failing.

### Command and Path Issues

* **`command not found` for [`uv`](docs/UV.md) (in LLM tool logs):**
  * Ensure [`uv`](docs/UV.md) 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`](https://github.com/modelcontextprotocol/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

* **Port Conflicts:**
  * **Symptom:** Server fails to start with "port already in use" error
  * **Solution:** Change `PORT` environment variable or kill conflicting process
  * **Default ports:** 8000 (streamable-http), check your specific configuration

* **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:
    ```bash
    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 [configuration guide](#the-deephaven_mcpjson-file-defining-your-community-sessions))
  * Ensure target [Deephaven Community Core](https://deephaven.io/community/) 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 any required authentication
  * **Enterprise sessions:** Check authentication tokens and certificate paths
  * **Environment variables:** Ensure sensitive credentials are properly set

### 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:

```json
{
  "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](docs/DEVELOPER_GUIDE.md) for advanced troubleshooting
   * Check the [GitHub Issues](https://github.com/deephaven/deephaven-mcp/issues) for similar problems

3. **Community Support:**
   * Post in [Deephaven Community Slack](https://deephaven.io/slack)
   * Create a GitHub issue with detailed information
   * Check [Deephaven Community Forums](https://github.com/deephaven/deephaven-core/discussions)

### 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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_troubleshoot-and-debug-mcp-servers)
* **Cursor**: [Cursor MCP documentation](https://docs.cursor.com/en/context/mcp)
* **Claude Desktop**: [Claude Desktop MCP Troubleshooting guide](https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
* **Windsurf**: [Windsurf MCP Troubleshooting guide](https://docs.windsurf.com/troubleshooting/windsurf-common-issues)

---

## Advanced Usage

*   **Detailed Server APIs and Tools:** For in-depth information about the tools exposed by the [Systems Server](#systems-server) (e.g., [`mcp_reload`](docs/DEVELOPER_GUIDE.md#mcp_reload), [`session_tables_schema`](docs/DEVELOPER_GUIDE.md#session_tables_schema)) and the [Docs Server](#docs-server) ([`docs_chat`](docs/DEVELOPER_GUIDE.md#docs_chat)), refer to the [Developer & Contributor Guide](docs/DEVELOPER_GUIDE.md).
*   **`uv` Workflow:** For more details on using `uv` for project management, see [docs/UV.md](docs/UV.md).

---
## Contributing

We warmly welcome contributions to Deephaven MCP! Whether it's bug reports, feature suggestions, documentation improvements, or code contributions, your help is valued.

**Where to Start:**

*   **Reporting Issues**: Found a bug or have a feature request? Open an issue on GitHub: [https://github.com/deephaven/deephaven-mcp/issues](https://github.com/deephaven/deephaven-mcp/issues)
*   **Contributing Guide**: See our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) for guidelines on how to get involved.
*   **Development Guide**: Looking to contribute code? See the [Developer & Contributor Guide](docs/DEVELOPER_GUIDE.md) for setup instructions, architecture details, and development workflows.

---

## Community & Support

*   **GitHub Issues:** For bug reports and feature requests: [https://github.com/deephaven/deephaven-mcp/issues](https://github.com/deephaven/deephaven-mcp/issues)
*   **Deephaven Community Slack:** Join the conversation and ask questions: [https://deephaven.io/slack](https://deephaven.io/slack)

---

## License

This project is licensed under the [Apache 2.0 License](./LICENSE). See the [LICENSE](./LICENSE) file for details.
