Skip to content

Commit 80609b0

Browse files
ntroghntrogh
authored
MCP content updates (#8925)
* Add python exampe for MCP dev mode * Content refresh * Restructure content
1 parent bbbff52 commit 80609b0

3 files changed

Lines changed: 136 additions & 126 deletions

File tree

‎api/extension-guides/ai/mcp.md‎

Lines changed: 105 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -29,73 +29,24 @@ You might consider implementing a language model tool with the [Language Model A
2929
- You want to deeply integrate with VS Code by using extension APIs.
3030
- You want to distribute your tool and updates by using the Visual Studio Marketplace.
3131

32-
## Add MCP servers to VS Code
33-
34-
Users can add MCP servers within VS Code in several ways:
35-
36-
- Workspace configuration: Specify the server configuration in a `.vscode/mcp.json` file in the workspace.
37-
- Global configuration: Define servers globally in the user [profile](https://code.visualstudio.com/docs/configure/profiles).
38-
- Autodiscovery: VS Code can discover servers from other tools like Claude Desktop.
39-
- Extension: VS Code extensions can register MCP servers programmatically.
40-
41-
In addition, users can trigger MCP installation by opening a [special URL](#mcp-url-handler) (`vscode:mcp/install`), which is used in the [MCP gallery on the VS Code website](https://code.visualstudio.com/mcp). Users can access the gallery directly from the MCP view in the Extensions view.
42-
43-
Finally, install MCP servers from the [command line](/docs/copilot/chat/mcp-servers#_command-line-configuration) with the `--add-mcp` command-line option.
44-
45-
## Manage MCP servers
46-
47-
You can manage the list of installed MCP servers from the Extension view (`kb(workbench.view.extensions)`) in VS Code.
48-
49-
![Screenshot showing the MCP servers in the Extensions view.](../images/ai/mcp/extensions-view-mcp-servers.png)
50-
51-
Right-click on an MCP server or select the gear icon to perform the following actions:
52-
53-
- **Start/Stop/Restart**: Start, stop, or restart the MCP server.
54-
- **Disconnect Account**: Disconnect the account for authentication with the MCP server.
55-
- **Show Output**: View the server logs to diagnose issues.
56-
- **Show Configuration**: View the MCP server configuration.
57-
- **Configure Model Access**: Configure which models the MCP server can access (sampling).
58-
- **Show Sampling Requests**: View the sampling requests made by the MCP server.
59-
- **Browse Resources**: View the resources provided by the MCP server.
60-
- **Uninstall**: Uninstall the MCP server from your environment.
61-
62-
Alternatively, run the **MCP: List Servers** command from the Command Palette to view the list of configured MCP servers. You can then select a server and perform actions on it.
63-
64-
> [!TIP]
65-
> When you open the `.vscode/mcp.json` file, VS Code shows commands to start, stop, or restart a server directly from the editor.
66-
67-
![MCP server configuration with lenses to manage server.](../images/ai/mcp/mcp-server-config-lenses.png)
68-
69-
### MCP URL handler
70-
71-
VS Code provides a URL handler for installing an MCP server from a link. To form the URL, construct an `obj` object in the same format as you would provide to `--add-mcp`, and then create the link by using the following logic:
72-
73-
```typescript
74-
// For Insiders, use `vscode-insiders` instead of `code`
75-
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;
76-
```
77-
78-
This link can be used in a browser, or opened on the command line, for example via `xdg-open $LINK` on Linux.
79-
8032
## MCP features supported by VS Code
8133

82-
VS Code supports the following transport methods for MCP servers:
83-
84-
- Standard input/output (`stdio`): Run a server as a local process that communicates over standard input and output
85-
- Streamable HTTP (`http`): Communicate with a (remote) server using HTTP POST and GET
86-
- Server-sent events (`sse`, legacy): Supported with a (remote) server over HTTP using server-sent events
34+
VS Code supports the following MCP capabilities:
8735

88-
The following MCP features are supported in VS Code:
36+
* [Transports](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports):
37+
* Local standard input/output (`stdio`)
38+
* Streamable HTTP (`http`)
39+
* Server-sent events (`sse`) - legacy support.
8940

90-
- Tools: Executable actions that can be used in [agent mode](/docs/copilot/chat/chat-agent-mode)
91-
- Prompts: Reusable chat prompt templates, optionally with parameters, which users can invoke through slash commands(`/mcp.servername.promptname`) in chat
92-
- Resources: Data and content which users can add as chat context or interact with directly in VS Code
93-
- Authorization: Authorize access to an MCP server using OAuth
94-
- Sampling _(Preview)_: Make language model requests using the user's configured models and subscription
95-
- Elicitation: Request input from the user
96-
- Workspace roots: Information about the user's workspace structure
97-
98-
For complete specification details, see the [Model Context Protocol documentation](https://modelcontextprotocol.io/).
41+
* [Features](https://modelcontextprotocol.io/specification/2025-06-18#features):
42+
* Tools: extend [agent mode](/docs/copilot/chat/chat-agent-mode) with extra tools
43+
* Prompts: add reusable prompts as slash commands in chat
44+
* Resources: provide data and content that users can add as chat context or interact with directly in VS Code
45+
* Elicitation: request input from the user
46+
* Sampling: make language model requests using the user's configured models and subscription
47+
* Authentication: authorize access to an MCP server using OAuth
48+
* Server instructions
49+
* Roots: provide information about the user's workspace root folder(s)
9950

10051
### Tools
10152

@@ -197,15 +148,15 @@ When DCR is not supported by the MCP server, users will go through the fallback
197148
> [!NOTE]
198149
> VS Code still supports MCP servers that behave as an authorization server, but it is recommended to use the latest specification for new servers.
199150
200-
### Sampling (Preview)
151+
### Sampling
201152

202-
VS Code provides access to [sampling](https://modelcontextprotocol.io/docs/concepts/sampling) for MCP servers. This allows your MCP server to make language model requests using the user's configured models and subscriptions. Sampling can be used to summarize large data or extract information before sending it to the client, or to implement smarter agentic decision in tool logic.
153+
VS Code provides access to [sampling](https://modelcontextprotocol.io/docs/concepts/sampling) for MCP servers. This allows your MCP server to make language model requests using the user's configured models and subscriptions. For example, use sampling to summarize large data sets, to extract information before sending it to the client, or to implement agentic decision logic in a tool.
203154

204155
The first time an MCP server performs a sampling request, the user is prompted to authorize the server to access their models.
205156

206157
![Screenshot that shows the authorization prompt for an MCP server to access models.](../images/ai/mcp/mcp-allow-sampling.png)
207158

208-
Users can specify which models they allow the MCP server to use for sampling by using the **MCP: List Servers** > **Configure Model Access** command in the Command Palette. You can specify `modelPreferences` in your MCP server to provide hints about which models to use for sampling, and VS Code will pick from the allowed models when evaluating the server's preferences
159+
When making sampling requests with specific models, consider that users can restrict which models an MCP server can use with the **MCP: List Servers** > **Configure Model Access** command in the Command Palette. When you specify `modelPreferences` in your MCP server to provide hints about which models to use for sampling, VS Code will pick from the allowed models.
209160

210161
![Screenshot that shows the Configure Model Access dialog for an MCP server.](../images/ai/mcp/mcp-configure-model-access.png)
211162

@@ -215,6 +166,45 @@ Users can view the sampling requests made by an MCP server with the **MCP: List
215166

216167
VS Code provides the MCP server with the user's workspace root folder information.
217168

169+
## Add MCP servers to VS Code
170+
171+
Users can add MCP servers within VS Code in several ways:
172+
173+
- Install directly from the web: use a special MCP installation URL (`vscode:mcp/install`) on your website.
174+
- Workspace configuration: Specify the server configuration in a `.vscode/mcp.json` file in the workspace.
175+
- Global configuration: Define servers globally in the user [profile](/docs/configure/profiles).
176+
- Autodiscovery: VS Code can discover servers from other tools like Claude Desktop.
177+
- Extension: VS Code extensions can register MCP servers programmatically.
178+
- Command line: Install MCP servers from the command line with the `--add-mcp` VS Code command-line option.
179+
180+
Learn more about the different ways to [add MCP servers to VS Code](/docs/copilot/customization/mcp-servers#add-an-mcp-server).
181+
182+
## Manage MCP servers
183+
184+
You can manage the list of installed MCP servers from the Extension view (`kb(workbench.view.extensions)`) in VS Code.
185+
186+
![Screenshot showing the MCP servers in the Extensions view.](../images/ai/mcp/extensions-view-mcp-servers.png)
187+
188+
Right-click on an MCP server or select the gear icon to perform different management actions on the server. Alternatively, run the **MCP: List Servers** command from the Command Palette to view the list of configured MCP servers. You can then select a server and perform actions on it.
189+
190+
> [!TIP]
191+
> When you open the `.vscode/mcp.json` file, VS Code shows commands in the editor to start, stop, or restart a server directly from the editor.
192+
>
193+
> ![MCP server configuration with lenses to manage server.](../images/ai/mcp/mcp-server-config-lenses.png)
194+
195+
## Create an MCP installation URL
196+
197+
VS Code provides a URL handler for installing an MCP server from a link: `vscode:mcp/install?{json-configuration}` (Insiders: `vscode-insiders:mcp/install?{json-configuration}`).
198+
199+
Provide the JSON server configuration in the form `{\"name\":\"server-name\",\"command\":...}` and then perform a JSON-stringify and URL encode on it. For example, use the following logic to create the installation URL:
200+
201+
```typescript
202+
// For Insiders, use `vscode-insiders` instead of `code`
203+
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;
204+
```
205+
206+
This link can be used in a browser, or opened on the command line, for example via `xdg-open $LINK` on Linux.
207+
218208
## Register an MCP server in your extension
219209

220210
To register an MCP server in your extension, you need to perform the following steps:
@@ -322,31 +312,61 @@ export function activate(context: vscode.ExtensionContext) {
322312
323313
### MCP development mode in VS Code
324314
325-
When developing MCP servers, you can enable MCP development mode in VS Code. To enable development mode, add the `dev` property to your MCP server configuration and specify the following properties:
315+
When developing MCP servers, you can enable _development mode_ for MCP servers by adding a `dev` key to the MCP server configuration. This is an object with two properties:
326316
327-
- `watch`: A glob pattern to watch for file changes to files and automatically restart the server
328-
- `debug`: Debugger to attach to your MCP server process when starting it (currently only supported for servers launched with `node` or `python`)
317+
* `watch`: A file glob pattern to watch for files change that will restart the MCP server.
318+
* `debug`: Enables you to set up a debugger with the MCP server. Currently, VS Code supports debugging Node.js and Python MCP servers.
329319
330-
The following example shows how to configure a Node.js MCP server that watches for changes to TypeScript files in the `src` directory and uses the Node.js debugger:
320+
<details>
321+
<summary>Node.js MCP server</summary>
331322
332-
```json
333-
{
334-
"servers": {
335-
"my-mcp-server": {
336-
"type": "stdio",
337-
"command": "node",
338-
"cwd": "${workspaceFolder}",
339-
"args": [
340-
"./build/index.js"
341-
],
342-
"dev": {
343-
"watch": "src/**/*.ts",
344-
"debug": { "type": "node" }
323+
To debug a Node.js MCP server, set the `debug.type` property to `node`.
324+
325+
```json
326+
{
327+
"servers": {
328+
"my-mcp-server": {
329+
"type": "stdio",
330+
"command": "node",
331+
"cwd": "${workspaceFolder}",
332+
"args": [ "./build/index.js" ],
333+
"dev": {
334+
"watch": "src/**/*.ts",
335+
"debug": { "type": "node" }
336+
}
345337
}
346338
}
347339
}
348-
}
349-
```
340+
```
341+
342+
</details>
343+
344+
<details>
345+
<summary>Python MCP server</summary>
346+
347+
To debug a Python MCP server, set the `debug.type` property to `debugpy`, and optionally set the `debug.debugpyPath` property to the path of the `debugpy` module if it is not installed in the default Python environment.
348+
349+
```json
350+
{
351+
"servers": {
352+
"my-python-mcp-server": {
353+
"type": "stdio",
354+
"command": "python",
355+
"cwd": "${workspaceFolder}",
356+
"args": [ "./server.py" ],
357+
"dev": {
358+
"watch": "**/*.py",
359+
"debug": {
360+
"type": "debugpy",
361+
"debugpyPath": "/path/to/debugpy"
362+
}
363+
}
364+
}
365+
}
366+
}
367+
```
368+
369+
</details>
350370
351371
### MCP output log
352372

‎api/extension-guides/images/ai/mcp/mcp-allow-sampling.png‎

Lines changed: 2 additions & 2 deletions
Loading

‎docs/copilot/customization/mcp-servers.md‎

Lines changed: 29 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,20 @@ By standardizing this interaction, MCP eliminates the need for custom integratio
3030

3131
VS Code supports the following MCP capabilities:
3232

33-
* MCP Server transport: local standard input/output (`stdio`), HTTP Stream (`http`), and server-sent events (`sse`, legacy support).
34-
* [MCP features](https://modelcontextprotocol.io/specification/2025-03-26#features): tools, prompts, resources, elicitation, sampling, and authentication.
35-
* VS Code provides servers with the current workspace folders using `roots` ([spec](https://modelcontextprotocol.io/docs/concepts/roots)).
33+
* [Transports](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports):
34+
* Local standard input/output (`stdio`)
35+
* Streamable HTTP (`http`)
36+
* Server-sent events (`sse`) - legacy support.
37+
38+
* [Features](https://modelcontextprotocol.io/specification/2025-06-18#features):
39+
* Tools
40+
* Prompts
41+
* Resources
42+
* Elicitation
43+
* Sampling
44+
* Authentication
45+
* Server instructions
46+
* [Roots](https://modelcontextprotocol.io/docs/concepts/roots)
3647

3748
</details>
3849

@@ -167,6 +178,19 @@ Configure autodiscovery with the `setting(chat.mcp.discovery.enabled)` setting.
167178

168179
</details>
169180

181+
<details>
182+
<summary>Install an MCP server from the command line</summary>
183+
184+
You can also use the VS Code command-line interface to add an MCP server to your user profile or to a workspace.
185+
186+
To add an MCP server to your user profile, use the `--add-mcp` VS Code command line option, and provide the JSON server configuration in the form `{\"name\":\"server-name\",\"command\":...}`.
187+
188+
```bash
189+
code --add-mcp "{\"name\":\"my-server\",\"command\": \"uvx\",\"args\": [\"mcp-server-fetch\"]}"
190+
```
191+
192+
</details>
193+
170194
When VS Code starts the MCP server for the first time, it discovers the server's capabilities and tools. You can then [use these tools in agent mode](#use-mcp-tools-in-agent-mode). VS Code caches the list of tools for an MCP server. To clear the cached tools, use the **MCP: Reset Cached Tools** command in the Command Palette.
171195

172196
## View installed MCP servers
@@ -286,27 +310,6 @@ Alternatively, manually restart the MCP server from the Chat view, or by selecti
286310

287311
![Screenshot showing the Refresh button in the Chat view.](../images/mcp-servers/chat-view-mcp-refresh.png)
288312

289-
### Command-line configuration
290-
291-
You can also use the VS Code command-line interface to add an MCP server to your user profile or to a workspace.
292-
293-
To add an MCP server to your user profile, use the `--add-mcp` command line option, and provide the JSON server configuration in the form `{\"name\":\"server-name\",\"command\":...}`.
294-
295-
```bash
296-
code --add-mcp "{\"name\":\"my-server\",\"command\": \"uvx\",\"args\": [\"mcp-server-fetch\"]}"
297-
```
298-
299-
### URL handler
300-
301-
VS Code also includes a URL handler that you can use to install an MCP server. To form the URL, construct an `obj` object in the same format as you would provide to `--add-mcp`, and then create the link by using the following logic:
302-
303-
```typescript
304-
// For Insiders, use `vscode-insiders` instead of `code`
305-
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;
306-
```
307-
308-
This link can be used in a browser, or opened on the command line, for example via `xdg-open $LINK` on Linux.
309-
310313
## Find MCP servers
311314

312315
MCP is still a relatively new standard, and the ecosystem is rapidly evolving. As more developers adopt MCP, you can expect to see an increasing number of servers and tools available for integration with your projects.
@@ -491,22 +494,9 @@ Select the error notification in the Chat view, and then select the **Show Outpu
491494
You can enable _development mode_ for MCP servers by adding a `dev` key to the MCP server configuration. This is an object with two properties:
492495

493496
* `watch`: A file glob pattern to watch for files change that will restart the MCP server.
494-
* `debug`: Enables you to set up a debugger with the MCP server.
497+
* `debug`: Enables you to set up a debugger with the MCP server. Currently, VS Code supports debugging Node.js and Python MCP servers.
495498

496-
```json
497-
{
498-
"servers": {
499-
"gistpad": {
500-
"command": "node",
501-
"args": ["build/index.js"],
502-
"dev": {
503-
"watch": "build/**/*.js",
504-
"debug": { "type": "node" }
505-
},
506-
```
507-
508-
> [!NOTE]
509-
> We currently only support debugging Node.js and Python servers launched with `node` and `python` respectively.
499+
Learn more about [MCP development mode](/api/extension-guides/ai/mcp.md#mcp-development-mode-in-vs-code) in the MCP Dev Guide.
510500

511501
## Frequently asked questions
512502

0 commit comments

Comments
 (0)