Model Context Protocol (MCP) Support

The Deephaven VS Code extension provides MCP (Model Context Protocol) server support, enabling AI assistants in VS Code and VS Code-based IDEs to interact with the Deephaven VS Code extension programmatically, and through it, with Deephaven servers.

What is MCP?

The Model Context Protocol is an open protocol that standardizes how AI assistants connect to external data sources and tools. By running as an MCP server, this extension exposes its functionality to AI assistants within VS Code and compatible IDEs, allowing them to:

• Connect to and manage Deephaven servers through the extension.
• Execute Python and Groovy code via the extension's connection management.
• Query connection states managed by the extension.
• Access the extension's output channels and logs.

Getting Started

Prerequisites

• Deephaven VS Code extension installed
• VS Code or a VS Code-based IDE (Windsurf, Cursor, etc.)
• GitHub Copilot or built-in AI assistant in your IDE
• At least one configured Deephaven server (see Configuration)

Configuration

MCP support is disabled by default. To use MCP features, you must first enable it in your VS Code settings.

MCP Server Settings

The extension provides two settings to control MCP functionality:

To enable the MCP server:

1. Look for the Deephaven MCP status bar item (shows "MCP: Disabled" when off).

   

2. Click the status bar item and select Enable Deephaven MCP Server.

   

3. The status bar will update to show MCP:<port> with the assigned port number.

   

This automatically sets "deephaven.mcp.enabled": true in your workspace settings (.vscode/settings.json). The MCP server starts immediately, listening on a local HTTP endpoint. Each workspace gets its own port (see Port Assignment).

Port Assignment

• The first time the MCP server starts in a workspace, the OS assigns it a random free port.
• The extension saves that port for the workspace and reuses it every time the workspace opens, so manually configured endpoints keep working.
• If the saved port is in use (e.g. by another VS Code window), the server picks a new random port and saves that one. If you configured the endpoint manually, update it to the new port shown in the status bar. VS Code with GitHub Copilot picks up the change automatically. Windsurf asks before updating its config, unless deephaven.mcp.autoUpdateConfig is true.
• There is no setting to choose a specific port.

Docs MCP Server Configuration

The Deephaven Documentation Searching skill connects to the Deephaven Docs MCP server. The server is automatically configured for GitHub Copilot and Claude Code or can be manually configured for other agents as described in Manual MCP Server Configuration. The extension skill makes AI assistants aware of the documentation capabilities. For more information about the Deephaven Docs MCP server itself, see the official documentation.

The documentation server can be independently enabled/disabled via the deephaven.mcp.docsEnabled setting:

Setting: deephaven.mcp.docsEnabled (default: true)

When deephaven.mcp.enabled is true, documentation queries are enabled by default. Set deephaven.mcp.docsEnabled to false to disable documentation queries while keeping the extension's MCP tools available.

IDE-Specific Configuration

Different IDEs require different MCP server configuration:

Claude Code Configuration

If Claude Code is installed, either as the claude CLI or as the Claude Code VS Code extension (which bundles the CLI), the extension registers its MCP servers with Claude Code using local scope for each workspace folder. local scope config is stored in ~/.claude.json keyed by the project directory (the git repository root, or the workspace folder if not in a git repository), so no files are added to your workspace. On Windows, Claude Code treats paths that differ only in drive letter case (e.g. c:\code\repo and C:\code\repo) as different projects, and the Claude Code IDE extension and terminals typically use different casings, so the servers are registered under both. This applies to Claude Code running in a VS Code integrated terminal as well as the Claude Code IDE extension, in any VS Code-based IDE.

The following servers are registered:

The servers are removed when the corresponding setting is disabled.

Note: If you've already configured the Deephaven Documentation MCP server for Claude Code yourself (under any name), set deephaven.mcp.docsEnabled to false to avoid registering it twice. Note that this setting also applies to GitHub Copilot.

Claude Code expands ${DEEPHAVEN_VSCODE_MCP_PORT} from its own environment. Each VS Code window sets this variable to the port of its own MCP server, both for its integrated terminals and for the Claude Code IDE extension. This way, Claude Code always talks to the VS Code window it was started from, even when several windows share the same Claude project (e.g. multiple git worktrees of the same repository, which Claude Code configures as a single project).

To verify the configuration, run the /mcp command in Claude Code, or if the claude CLI is installed, run the following from an integrated terminal in your workspace:

Note: Claude Code started outside VS Code (e.g. in an external terminal) doesn't have DEEPHAVEN_VSCODE_MCP_PORT set, so deephaven-vscode fails to connect. To use it from an external terminal, set the variable to the port shown in the status bar first, e.g. export DEEPHAVEN_VSCODE_MCP_PORT=<port>.

Note: Claude Code loads MCP servers when a session starts. To pick up changes, restart claude or start a new session. Terminals running the Claude CLI that were opened before the MCP server started need to be relaunched first, since they don't have DEEPHAVEN_VSCODE_MCP_PORT set.

Manual MCP Server Configuration

For IDEs that require manual configuration (Cursor and other VS Code-based IDEs), you'll need to configure the MCP server endpoint. The MCP server port is displayed in the status bar as MCP:<port> when running. You can click the status bar item to copy the full endpoint URL to your clipboard. The endpoint URL follows the format: http://localhost:<port>/mcp.

Cursor:

Create a .cursor/mcp.json file in your workspace root:

Claude Code (if not configured automatically):

Create a .mcp.json file in your workspace root:

Note: This configuration should work for Claude running in any VS Code-based IDE that supports the Deephaven extension (VS Code, Cursor, Windsurf, etc.).

Other IDEs:

Configuration format varies by IDE but should be similar to the examples above. Consult your IDE's MCP documentation for the specific configuration file location and format.

Note: After configuration changes, you may need to restart agent sessions or clear MCP tool caches.

Available Tools

The MCP server provides tools for:

• Server Management - Connect to and list configured Deephaven servers.

  • connectToServer - Create a connection to a server.
  • listServers - List all configured servers.

• Connection Management - Query active connections.

  • listConnections - List active connections, optionally filtered by URL.

• Code Execution - Run Python and Groovy code.

  • runCode - Execute arbitrary code text.
  • runCodeFromUri - Execute code from workspace files.

• Variables - Query and interact with Deephaven variables.

  • listVariables - List all variables on a connection.
  • openVariablePanels - Open variable panels for specific variables.

• Table Data & Statistics - Fetch and analyze table data.

  • getTableData - Fetch paginated data from a table.
  • getTableStats - Get schema information and basic statistics.
  • getColumnStats - Get statistical information for a column.

• Remote File Sources - Manage server file source paths.

  • addRemoteFileSources - Add folders as remote file sources.
  • listRemoteFileSources - List current remote file sources.
  • removeRemoteFileSources - Remove remote file sources.

• Output & Logging - Access extension logs.

  • getLogs - Retrieve server or debug logs.
  • showOutputPanel - Display output panel in VS Code.

For detailed documentation on each tool including parameters, return types, and examples, see MCP Tool Reference.

Agent Skills

In addition to MCP tools, the extension provides agent skills that can be registered with supported AI assistants to provide domain-specific knowledge and capabilities. For GitHub Copilot users, the skills are automatically registered when the extension loads. Other agents require manual installation.

Provided Skills

1. Deephaven VS Code Usage (deephaven-vscode-using)

   • Manages Deephaven server connections and code execution through VS Code MCP tools.
   • Handles connecting to DHC/DHE servers, executing Python/Groovy code.
   • Provides workflows for opening variable panels and troubleshooting connection issues.
   • Use when working with the vscode-deephaven extension's MCP tools.

2. Deephaven Documentation Searching (deephaven-docs-searching)

   • Queries Deephaven documentation for API help, syntax guidance, and best practices.
   • Provides answers about table operations, filtering, joining, aggregations, plotting, and other Deephaven features.
   • Supports both Python and Groovy.
   • Does NOT require a running server or connection - purely documentation queries.

Installation Options

Note: GitHub Copilot users should have access to the skills automatically and don't need to install anything.

1. Using npx skills (recommended if you have Node.js installed):

2. Manual installation:

   • Navigate to the skills folder in the vscode-deephaven repository.
   • Download the SKILL.md file from each skill you want to use:
     • deephaven-vscode-using/SKILL.md - For interacting with Deephaven through the VS Code extension's MCP tools
     • deephaven-docs-searching/SKILL.md - For querying Deephaven documentation
   • Install the skill(s) according to your AI assistant's documentation.

Tool Response Format

All MCP tools follow a consistent response structure:

Success Response

Error Response

Supported IDEs

The MCP server is designed specifically for VS Code and IDEs built on top of VS Code. See the IDE-Specific Configuration table above for details on which IDEs require manual configuration.

Tested and Fully Supported:

• VS Code with GitHub Copilot
• Windsurf

Supported with Manual Configuration:

• Claude in VS Code-based IDEs (VS Code, Cursor, Windsurf, etc.)
• Cursor
• Other VS Code-based IDEs (untested, configuration format may vary)