Skip to content

Commit f1e7f68

Browse files
bminglesmargaretkennedy
bmingles
and
margaretkennedy
authored
docs: DOC-1241: MCP setup in other IDEs (#317)
Documented MCP server config + agent skills installation for non Copilot scenarios --------- Co-authored-by: margaretkennedy <82049573+margaretkennedy@users.noreply.github.com>
1 parent 71cc01f commit f1e7f68

4 files changed

Lines changed: 86 additions & 69 deletions

File tree

‎docs/assets/mcp-disabled.png‎

4.35 KB
Loading

‎docs/assets/mcp-enable.png‎

10.1 KB
Loading

‎docs/assets/mcp-enabled.png‎

4.29 KB
Loading

‎docs/mcp.md‎

Lines changed: 86 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -22,117 +22,128 @@ The [Model Context Protocol](https://modelcontextprotocol.io/) is an open protoc
2222

2323
### Configuration
2424

25-
The MCP server is disabled by default. To use MCP features, you must first enable it in your VS Code settings.
25+
MCP support is disabled by default. To use MCP features, you must first enable it in your VS Code settings.
2626

27-
#### Enabling/Disabling MCP Server
27+
#### MCP Server Settings
2828

29-
The MCP server can be controlled via the VS Code setting:
29+
The extension provides two settings to control MCP functionality:
3030

31-
**Setting**: `deephaven.mcp.enabled` (default: `false`)
31+
| Setting | Default | Description |
32+
| --------------------------- | ------- | -------------------------------------------------------------------------------------------- |
33+
| `deephaven.mcp.enabled` | `false` | Enables/disables MCP servers. Must be `true` for any MCP features to work. |
34+
| `deephaven.mcp.docsEnabled` | `true` | Enables/disables documentation queries. Only applies when `deephaven.mcp.enabled` is `true`. |
3235

33-
To enable the MCP server, set this to `true` in your VS Code settings (UI or JSON):
36+
**To enable the MCP server:**
3437

35-
**Via the Settings UI:**
38+
1. Look for the Deephaven MCP status bar item (shows "MCP: Disabled" when off).
3639

37-
1. Open VS Code Settings (`Cmd+,` on macOS, `Ctrl+,` on Windows/Linux).
38-
2. Choose **User** settings (applies to all workspaces) or **Workspace** settings (applies only to the current workspace).
39-
3. Search for `deephaven.mcp.enabled`.
40-
4. Check the box to enable.
40+
![MCP Disabled](assets/mcp-disabled.png)
4141

42-
**Via `settings.json`:**
42+
2. Click the status bar item and select **Enable Deephaven MCP Server**.
4343

44-
```json
45-
{
46-
"deephaven.mcp.enabled": true
47-
}
48-
```
44+
![Enable Deephaven MCP Server](assets/mcp-enable.png)
4945

50-
Once enabled, the MCP server automatically starts when the extension loads, listening on a local HTTP endpoint. Each workspace gets a unique auto-allocated port, which is displayed in a status bar item as `MCP:<port>`.
46+
3. The status bar will update to show `MCP:<port>` with the assigned port number.
5147

52-
#### Documentation Queries
48+
![MCP Enabled](assets/mcp-enabled.png)
5349

54-
The extension provides a separate MCP server for querying Deephaven documentation, which is enabled by default when the main MCP server is enabled.
50+
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 a unique port.
5551

56-
**Setting**: `deephaven.mcp.docsEnabled` (default: `true`)
52+
#### Docs MCP Server Configuration
5753

58-
This setting controls whether documentation queries are available to AI assistants. When `deephaven.mcp.enabled` is `true`, the documentation server is automatically enabled unless `deephaven.mcp.docsEnabled` is set to `false`.
54+
The Deephaven Documentation Searching skill connects to the [Deephaven Docs MCP server](https://deephaven.io/enterprise/docs/clients/mcp/#docs-server). The server is automatically configured for Github Copilot or can be manually configured for other agents as described in [Manual MCP Server Configuration](#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](https://deephaven.io/enterprise/docs/clients/mcp/#docs-server).
5955

60-
To disable documentation queries while keeping the extension's MCP tools available:
56+
The documentation server can be independently enabled/disabled via the `deephaven.mcp.docsEnabled` setting:
6157

62-
```json
63-
{
64-
"deephaven.mcp.enabled": true,
65-
"deephaven.mcp.docsEnabled": false
66-
}
67-
```
58+
**Setting**: `deephaven.mcp.docsEnabled` (default: `true`)
6859

69-
#### VS Code with GitHub Copilot
60+
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.
7061

71-
When using GitHub Copilot in VS Code, the extension's MCP server is automatically configured and available once enabled. No additional configuration is required.
62+
#### IDE-Specific Configuration
7263

73-
#### Windsurf
64+
Different IDEs require different MCP server configuration:
7465

75-
Windsurf automatically detects and connects to the MCP server when the Deephaven extension is active. No additional configuration is required.
66+
| IDE | Auto-Configured | MCP Configuration File |
67+
| ------------------------------- | ---------------------------- | ------------------------------------- |
68+
| **VS Code with GitHub Copilot** | ✅ Yes | None required |
69+
| **Windsurf** | ✅ Yes (after user approval) | `~/.codeium/windsurf/mcp_config.json` |
70+
| **Claude in VS Code-based IDE** | ❌ No | `<wksp-folder>/.mcp.json` |
71+
| **Cursor** | ❌ No | `<wksp-folder>/.cursor/mcp.json` |
72+
| **Other VS Code-based IDEs** | ❌ No | Varies by IDE |
7673

77-
> **Note:** Since each workspace uses a unique port and Windsurf only supports user-level MCP configuration, the extension will automatically update the MCP configuration when a Windsurf window becomes active to match the current workspace's port. This has not been thoroughly tested and may require manual steps, such as restarting IDE/agent sessions.
74+
#### Manual MCP Server Configuration
7875

79-
#### Other VS Code-based IDEs
76+
For IDEs that require manual configuration (Cursor and other VS Code-based IDEs) or Claude running in 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`.
8077

81-
For other VS Code-based IDEs that support MCP, you may need to configure the MCP server endpoint in your IDE's settings.
78+
**Cursor:**
8279

83-
The MCP server uses an auto-allocated port that varies per session. When the MCP server starts, a status bar item will display `MCP:<port>` showing the actual port being used. The endpoint URL follows the format:
80+
Create a `.cursor/mcp.json` file in your workspace root:
8481

85-
```
86-
http://localhost:<port>/mcp
82+
```json
83+
{
84+
"mcpServers": {
85+
"Deephaven VS Code": {
86+
"url": "http://localhost:<port>/mcp"
87+
},
88+
"Deephaven Documentation": {
89+
"url": "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
90+
}
91+
}
92+
}
8793
```
8894

89-
> **Note:** The port is unique per workspace. If you switch workspaces, you may need to update your MCP configuration with the new port shown in the status bar. Most IDEs don't yet seem to support workspace-level MCP configs, so settings may have to be updated at the user level. This may also require restarting agent sessions, MCP tool caches, etc.
95+
**Claude in VS Code-based IDE:**
9096

91-
Example configuration (format may vary by IDE):
97+
Create a `.mcp.json` file in your workspace root:
9298

9399
```json
94100
{
95-
"mcp.servers": {
96-
"deephaven": {
97-
"url": "http://localhost:45678/mcp"
101+
"mcpServers": {
102+
"Deephaven VS Code": {
103+
"type": "http",
104+
"url": "http://localhost:<port>/mcp"
105+
},
106+
"Deephaven Documentation": {
107+
"type": "http",
108+
"url": "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
98109
}
99110
}
100111
}
101112
```
102113

103-
Replace `45678` with the actual port shown in the `MCP:<port>` status bar item.
114+
> **Note:** This configuration should work for Claude running in any VS Code-based IDE that supports the Deephaven extension (VS Code, Cursor, Windsurf, etc.).
115+
116+
**Other IDEs:**
117+
118+
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.
119+
120+
> **Note:** After configuration changes, you may need to restart agent sessions or clear MCP tool caches.
104121
105122
## Available Tools
106123

107124
The MCP server provides tools for:
108125

109126
- **Server Management** - Connect to and list configured Deephaven servers.
110-
111127
- `connectToServer` - Create a connection to a server.
112128
- `listServers` - List all configured servers.
113129

114130
- **Connection Management** - Query active connections.
115-
116131
- `listConnections` - List active connections, optionally filtered by URL.
117132

118133
- **Code Execution** - Run Python and Groovy code.
119-
120134
- `runCode` - Execute arbitrary code text.
121135
- `runCodeFromUri` - Execute code from workspace files.
122136

123137
- **Variables** - Query and interact with Deephaven variables.
124-
125138
- `listVariables` - List all variables on a connection.
126139
- `openVariablePanels` - Open variable panels for specific variables.
127140

128141
- **Table Data & Statistics** - Fetch and analyze table data.
129-
130142
- `getTableData` - Fetch paginated data from a table.
131143
- `getTableStats` - Get schema information and basic statistics.
132144
- `getColumnStats` - Get statistical information for a column.
133145

134146
- **Remote File Sources** - Manage server file source paths.
135-
136147
- `addRemoteFileSources` - Add folders as remote file sources.
137148
- `listRemoteFileSources` - List current remote file sources.
138149
- `removeRemoteFileSources` - Remove remote file sources.
@@ -143,14 +154,13 @@ The MCP server provides tools for:
143154

144155
For detailed documentation on each tool including parameters, return types, and examples, see [MCP Tool Reference](mcp-tools.md).
145156

146-
## Chat Skills
157+
## Agent Skills
147158

148-
In addition to MCP tools, the extension provides Chat Skills that can be registered with supported AI assistants (e.g., GitHub Copilot, Windsurf) to provide domain-specific knowledge and capabilities.
159+
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.
149160

150-
### Available Chat Skills
161+
### Provided Skills
151162

152163
1. **Deephaven VS Code Usage** (`deephaven-vscode-using`)
153-
154164
- Manages Deephaven server connections and code execution through VS Code MCP tools.
155165
- Handles connecting to DHC/DHE servers, executing Python/Groovy code.
156166
- Provides workflows for opening variable panels and troubleshooting connection issues.
@@ -162,17 +172,23 @@ In addition to MCP tools, the extension provides Chat Skills that can be registe
162172
- Supports both Python and Groovy.
163173
- Does NOT require a running server or connection - purely documentation queries.
164174

165-
### Chat Skills Configuration
166-
167-
Chat Skills are automatically registered when the extension loads. They are available in supported AI assistants like GitHub Copilot and Windsurf.
175+
### Installation Options
168176

169-
The Deephaven Documentation Searching skill connects to the [Deephaven Docs MCP server](https://deephaven.io/enterprise/docs/clients/mcp/#docs-server), which is automatically configured by the extension when enabled. The extension provides the auto-configuration and the chat skill to make AI assistants aware of the documentation capabilities. For more information about the Deephaven Docs MCP server itself, see the [official documentation](https://deephaven.io/enterprise/docs/clients/mcp/#docs-server).
177+
> Note: GitHub Copilot users should have access to the skills automatically and don't need to install anything.
170178
171-
The documentation server can be independently enabled/disabled via the `deephaven.mcp.docsEnabled` setting:
179+
1. **Using `npx skills` (recommended if you have Node.js installed):**
172180

173-
**Setting**: `deephaven.mcp.docsEnabled` (default: `true`)
181+
```bash
182+
npx skills add deephaven/vscode-deephaven -g -s deephaven-vscode-using
183+
npx skills add deephaven/vscode-deephaven -g -s deephaven-docs-searching
184+
```
174185

175-
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.
186+
1. **Manual installation:**
187+
- Navigate to the [skills folder](https://github.com/deephaven/vscode-deephaven/tree/main/skills) in the vscode-deephaven repository.
188+
- Download the `SKILL.md` file from each skill you want to use:
189+
- [deephaven-vscode-using/SKILL.md](https://github.com/deephaven/vscode-deephaven/tree/main/skills/deephaven-vscode-using/SKILL.md) - For interacting with Deephaven through the VS Code extension's MCP tools
190+
- [deephaven-docs-searching/SKILL.md](https://github.com/deephaven/vscode-deephaven/tree/main/skills/deephaven-docs-searching/SKILL.md) - For querying Deephaven documentation
191+
- Install the skill(s) according to your AI assistant's documentation.
176192

177193
## Tool Response Format
178194

@@ -207,14 +223,15 @@ All MCP tools follow a consistent response structure:
207223

208224
## Supported IDEs
209225

210-
The MCP server provided by this extension is designed specifically for VS Code and IDEs built on top of VS Code:
226+
The MCP server is designed specifically for VS Code and IDEs built on top of VS Code. See the [IDE-Specific Configuration](#ide-specific-configuration) table above for details on which IDEs require manual configuration.
227+
228+
**Tested and Fully Supported:**
211229

212-
- **VS Code with GitHub Copilot** - Fully supported and tested.
213-
- **Windsurf** - Fully supported and tested.
214-
- **Other VS Code-based IDEs** (e.g., Cursor) - May work but untested; requires manual MCP server configuration.
230+
- VS Code with GitHub Copilot
231+
- Windsurf
215232

216-
### AI Assistant Support
233+
**Supported with Manual Configuration:**
217234

218-
- **GitHub Copilot** - Automatically configured.
219-
- **Windsurf's built-in agent** - Automatically configured.
220-
- **Other AI assistants** (e.g., VS Code-based IDEs, AI extensions like Cline) - Automatic configuration not implemented; requires manual MCP server configuration (untested).
235+
- Claude in VS Code-based IDEs (VS Code, Cursor, Windsurf, etc.)
236+
- Cursor
237+
- Other VS Code-based IDEs (untested, configuration format may vary)

0 commit comments

Comments
 (0)