|
| 1 | +--- |
| 2 | +# DO NOT TOUCH — Managed by doc writer |
| 3 | +ContentId: e655f324-ed0b-452d-aff3-52cdca3978a5 |
| 4 | +DateApproved: 05/08/2025 |
| 5 | + |
| 6 | +# Summarize the whole topic in less than 300 characters for SEO purpose |
| 7 | +MetaDescription: A guide to registering an MCP server in a VS Code extension. |
| 8 | +--- |
| 9 | + |
| 10 | +# MCP servers |
| 11 | + |
| 12 | +Model Context Protocol (MCP) is an open standard that enables AI models to interact with external tools and services through a unified interface. Visual Studio Code can act as an MCP client, which enables users to [access MCP tools in agent mode](/docs/copilot/chat/mcp-servers.md). This article guides you through registering an MCP server in a VS Code extension. |
| 13 | + |
| 14 | +VS Code retrieves MCP server configurations from `.vscode/mcp.json` files in workspace folders and the `mcp` section of workspace, remote, and user settings. It can also automatically discover them from other tools' configuration, including Claude Desktop. |
| 15 | + |
| 16 | +VS Code extensions can also register MCP server configurations programmatically to avoid that users need to manually configure them. This is useful if you already have an MCP server and want to register it as part of your extension activation, or if your extension has a dependency on an MCP server. |
| 17 | + |
| 18 | +Instead of using MCP servers to extend the chat functionality, you can also [contribute language model tools](/api/extension-guides/tools.md) directly within your extension. This approach is useful if you want to deeply integrate with VS Code by using extension APIs or to avoid that users have to install and run an MCP server in a separate process. |
| 19 | + |
| 20 | +> [!IMPORTANT] |
| 21 | +> MCP support in VS Code is in preview and the API for registering an MCP server in a VS Code extension is currently in a proposed state. |
| 22 | +
|
| 23 | +## Register an MCP server |
| 24 | + |
| 25 | +To register an MCP server in your extension, use the `vscode.lm.registerMcpServerDefinitionProvider` API to provide the [MCP configuration](/docs/copilot/chat/mcp-servers.md#configuration-format) for the server. The API takes a `providerId` string and a `McpServerDefinitionProvider` object. |
| 26 | + |
| 27 | +Before calling this method, extensions must contribute the `contributes.mcpServerDefinitionProviders` extension point in the `package.json` with the `id` of the provider. |
| 28 | + |
| 29 | +The `McpServerDefinitionProvider` object has three properties: |
| 30 | + |
| 31 | +- `onDidChangeMcpServerDefinitions`: event that is triggered when the MCP server configurations change. |
| 32 | +- `provideMcpServerDefinitions`: function that returns an array of MCP server configurations (`vscode.McpServerDefinition[]`). |
| 33 | +- `resolveMcpServerDefinition`: function that the editor calls when the MCP server needs to be started. Use this function to perform additional actions that may require user interaction, such as authentication. |
| 34 | + |
| 35 | +An `McpServerDefinition` object can be one of the following types: |
| 36 | + |
| 37 | +- `vscode.McpStdioServerDefinition`: represents an MCP server available by running a local process and operating on its stdin and stdout streams. |
| 38 | +- `vscode.McpHttpServerDefinition`: represents an MCP server available using the Streamable HTTP transport. |
| 39 | + |
| 40 | +The following example demonstrates how to register MCP servers in an extension and prompt the user for an API key when starting the server. |
| 41 | + |
| 42 | +```ts |
| 43 | +import * as vscode from 'vscode'; |
| 44 | + |
| 45 | +export function activate(context: vscode.ExtensionContext) { |
| 46 | + const didChangeEmitter = new vscode.EventEmitter<void>(); |
| 47 | + |
| 48 | + context.subscriptions.push(vscode.lm.registerMcpServerDefinitionProvider('exampleProvider', { |
| 49 | + onDidChangeMcpServerDefinitions: didChangeEmitter.event, |
| 50 | + provideMcpServerDefinitions: async () => { |
| 51 | + let servers: vscode.McpServerDefinition[] = []; |
| 52 | + |
| 53 | + // Example of a simple stdio server definition |
| 54 | + servers.push(new vscode.McpStdioServerDefinition( |
| 55 | + { |
| 56 | + label: 'myServer', |
| 57 | + command: 'node', |
| 58 | + args: ['server.js'], |
| 59 | + cwd: vscode.Uri.file('/path/to/server'), |
| 60 | + env: { |
| 61 | + API_KEY: '' |
| 62 | + }, |
| 63 | + version: '1.0.0' |
| 64 | + }); |
| 65 | + |
| 66 | + // Example of an HTTP server definition |
| 67 | + servers.push(new vscode.McpHttpServerDefinition( |
| 68 | + { |
| 69 | + label: 'myRemoteServer', |
| 70 | + uri: 'http://localhost:3000', |
| 71 | + headers: { |
| 72 | + 'API_VERSION': '1.0.0' |
| 73 | + }, |
| 74 | + version: '1.0.0' |
| 75 | + })); |
| 76 | + |
| 77 | + return servers; |
| 78 | + }, |
| 79 | + resolveMcpServerDefinition: async (server: vscode.McpServerDefinition) => { |
| 80 | + |
| 81 | + if (server.label === 'myServer') { |
| 82 | + // Get the API key from the user, e.g. using vscode.window.showInputBox |
| 83 | + // Update the server definition with the API key |
| 84 | + } |
| 85 | + |
| 86 | + // Return undefined to indicate that the server should not be started or throw an error |
| 87 | + // If there is a pending tool call, the editor will cancel it and return an error message |
| 88 | + // to the language model. |
| 89 | + return server; |
| 90 | + } |
| 91 | + })); |
| 92 | +} |
| 93 | +``` |
| 94 | +
|
| 95 | +The `package.json` file should include the corresponding `contributes/mcpServerDefinitionProviders` section: |
| 96 | +
|
| 97 | +```json |
| 98 | +{ |
| 99 | + ... |
| 100 | + "contributes": { |
| 101 | + "mcpServerDefinitionProviders": [ |
| 102 | + { |
| 103 | + "id": "exampleProvider", |
| 104 | + "label": "Example MCP Server Provider" |
| 105 | + } |
| 106 | + ] |
| 107 | + } |
| 108 | + ... |
| 109 | +} |
| 110 | +``` |
| 111 | +
|
| 112 | +## Getting started |
| 113 | +
|
| 114 | +Get started with a full example of how to register an MCP server in a VS Code extension: |
| 115 | +
|
| 116 | +- [MCP extension sample](https://github.com/microsoft/vscode-extension-samples/blob/main/mcp-extension-sample) |
| 117 | +
|
| 118 | +## Related content |
| 119 | +
|
| 120 | +- [Model Context Protocol Documentation](https://modelcontextprotocol.io/) |
| 121 | +- [Use MCP tools in agent mode](/docs/copilot/chat/mcp-servers.md) |
| 122 | +- [Contribute a language model tool](/api/extension-guides/tools.md) |
| 123 | +- [Language Model API reference](/api/references/vscode-api.md#lm) |
0 commit comments