MCP Tool Guide

This guide helps you understand what the Deephaven MCP tools can do and how to use them effectively with AI assistants like GitHub Copilot.

Note: The AI assistant can see the full tool schemas automatically. This guide focuses on when and how to use each tool.

Quick Reference

Server Management

Listing and Connecting to Servers

Use listServers to see what Deephaven servers are configured in your VS Code settings. This is useful when you need to check server status or see what's available.

Use connectToServer to create a connection to a configured server. You need a connection before you can run code.

Common patterns:

Notes:

• Servers must be configured in VS Code settings first (see Configuration).
• Community servers auto-start if they're pip-managed.
• The AI can find servers by URL or label when connecting.
• Connecting to Enterprise servers creates a new worker.

Running Code

Execute Code Snippets or Files

Use runCode when you want to execute code directly (like "run this Python snippet").

Use runCodeFromUri when working with files in your workspace (like "run this file" or "run lines 10-20").

Auto-connection: If you're not connected, runCode will try to connect automatically to a running server.

Common patterns:

Notes:

• Language is detected from the file extension or specified explicitly.
• Variables created by the code are returned in the response.

Checking Connections

See What's Connected

Use listConnections to see active connections and their status.

Common patterns:

Useful for:

• Debugging connection issues.
• Checking if code is currently running.
• Resolving connection names to URLs.

Working with Variables

List and Open Variable Panels

Use listVariables to see all panel variables available on a connection. This returns variable metadata including IDs, titles, and types.

Use openVariablePanels to open UI panels for specific variables (tables, plots, etc.). Requires variable objects with both id and title from listVariables or code execution responses.

Common patterns:

Notes:

• Variables are automatically opened as panels after code execution, so openVariablePanels is typically used to reopen panels that were closed or for variables that weren't initially opened.
• listVariables only returns variables that support panels (tables, plots, etc.), not scalar values or functions.
• Panel URLs are included in responses for UI verification.

Table Data & Statistics

Fetch and Analyze Table Data

Use getTableData to fetch paginated data from a table. Returns actual row data with configurable limit and offset for pagination.

Use getTableStats to get schema information and basic statistics like row count, column names, types, and descriptions.

Use getColumnStats to get detailed statistics for a specific column (min, max, average, unique values, etc.).

Common patterns:

Notes:

• Prefer variableId (from runCode or listVariables) over tableName when available.
• getTableData supports pagination via limit and offset parameters (max 10,000 rows per request).
• Statistics are computed on-demand and may take time for large tables.
• All tools work with both static and ticking (real-time) tables.

Remote File Sources

Manage Server File Paths

Remote file sources allow the Deephaven server to access source files during code execution (e.g., for Python imports or file reading).

Use addRemoteFileSources to add workspace folders as remote file sources on a connection.

Use listRemoteFileSources to see which folders are currently registered as remote file sources.

Use removeRemoteFileSources to unregister folders when they're no longer needed.

Common patterns:

Useful for:

• Enabling server-side Python imports from local files.
• Allowing Deephaven to read data files from your workspace.
• Setting up development workflows with local code.

Notes:

• Only works with Enterprise (DHE) servers.
• Folders must be within the workspace.
• Files are synced to the server when registered.

Accessing Logs

View Extension Output

Use getLogs to retrieve log history programmatically. Specify "server" for server logs or "debug" for detailed diagnostics.

Use showOutputPanel to open the VS Code Output panel in the UI.

Common patterns:

Useful for:

• Debugging connection issues.
• Investigating code execution errors.
• Seeing what happened during operations.

Getting Help

If tools aren't working as expected:

1. Use getLogs to see what errors occurred.
2. Verify your server configuration in VS Code settings.
3. Check that the MCP server is enabled (deephaven.mcp.enabled).
4. Check the VS Code Output panel (View → Output → Deephaven) for error messages.