API guide: register MCP server

api/extension-guides/mcp.md

@@ -0,0 +1,123 @@
+---
+# DO NOT TOUCH — Managed by doc writer
+ContentId: e655f324-ed0b-452d-aff3-52cdca3978a5
+DateApproved: 05/08/2025
+
+# Summarize the whole topic in less than 300 characters for SEO purpose
+MetaDescription: A guide to registering an MCP server in a VS Code extension.
+---
+
+# MCP servers
+
+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.
+
+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.
+
+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.
+
+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.
+
+> [!IMPORTANT]
+> 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.
+
+## Register an MCP server
+
+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.
+
+Before calling this method, extensions must contribute the `contributes.mcpServerDefinitionProviders` extension point in the `package.json` with the `id` of the provider.
+
+The `McpServerDefinitionProvider` object has three properties:
+
+- `onDidChangeMcpServerDefinitions`: event that is triggered when the MCP server configurations change.
+- `provideMcpServerDefinitions`: function that returns an array of MCP server configurations (`vscode.McpServerDefinition[]`).
+- `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.
+
+An `McpServerDefinition` object can be one of the following types:
+
+- `vscode.McpStdioServerDefinition`: represents an MCP server available by running a local process and operating on its stdin and stdout streams.
+- `vscode.McpHttpServerDefinition`: represents an MCP server available using the Streamable HTTP transport.
+
+The following example demonstrates how to register MCP servers in an extension and prompt the user for an API key when starting the server.
+
+```ts
+import * as vscode from 'vscode';
+
+export function activate(context: vscode.ExtensionContext) {
+    const didChangeEmitter = new vscode.EventEmitter<void>();
+
+    context.subscriptions.push(vscode.lm.registerMcpServerDefinitionProvider('exampleProvider', {
+        onDidChangeMcpServerDefinitions: didChangeEmitter.event,
+        provideMcpServerDefinitions: async () => {
+            let servers: vscode.McpServerDefinition[] = [];
+
+            // Example of a simple stdio server definition
+            servers.push(new vscode.McpStdioServerDefinition(
+            {
+                label: 'myServer',
+                command: 'node',
+                args: ['server.js'],
+                cwd: vscode.Uri.file('/path/to/server'),
+                env: {
+                    API_KEY: ''
+                },
+                version: '1.0.0'
+            });
+
+            // Example of an HTTP server definition
+            servers.push(new vscode.McpHttpServerDefinition(
+            {
+                label: 'myRemoteServer',
+                uri: 'http://localhost:3000',
+                headers: {
+                    'API_VERSION': '1.0.0'
+                },
+                version: '1.0.0'
+            }));
+
+            return servers;
+        },
+        resolveMcpServerDefinition: async (server: vscode.McpServerDefinition) => {
+
+            if (server.label === 'myServer') {
+                // Get the API key from the user, e.g. using vscode.window.showInputBox
+                // Update the server definition with the API key
+            }
+
+            // Return undefined to indicate that the server should not be started or throw an error
+            // If there is a pending tool call, the editor will cancel it and return an error message
+            // to the language model.
+            return server;
+        }
+    }));
+}
+```
+
+The `package.json` file should include the corresponding `contributes/mcpServerDefinitionProviders` section:
+
+```json
+{
+    ...
+    "contributes": {
+        "mcpServerDefinitionProviders": [
+            {
+                "id": "exampleProvider",
+                "label": "Example MCP Server Provider"
+            }
+        ]
+    }
+    ...
+}
+```
+
+## Getting started
+
+Get started with a full example of how to register an MCP server in a VS Code extension:
+
+- [MCP extension sample](https://github.com/microsoft/vscode-extension-samples/blob/main/mcp-extension-sample)
+
+## Related content
+
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- [Use MCP tools in agent mode](/docs/copilot/chat/mcp-servers.md)
+- [Contribute a language model tool](/api/extension-guides/tools.md)
+- [Language Model API reference](/api/references/vscode-api.md#lm)

api/extension-guides/tools.md

@@ -7,7 +7,7 @@ DateApproved: 05/08/2025
 MetaDescription: A guide to creating a language model tool and how to implement tool calling in a chat extension
 ---
 
-# LanguageModelTool API
+# Language Model Tool API
 
 Language model tools enable you to extend the functionality of a large language model (LLM). VS Code surfaces tools contributed by extensions in Copilot [agent mode](/docs/copilot/chat/chat-agent-mode.md). By contributing a tool in a VS Code extension, you can combine the power of agentic coding with deep VS Code integration via its extension APIs.
 
@@ -267,6 +267,6 @@ Get more best practices for creating tools in the [OpenAI documentation](https:/
 
 ## Related content
 
-- [Get started with the Language Model API](/api/extension-guides/language-model)
-- [Use Prompt-tsx](/api/extension-guides/prompt-tsx)
-- [Add MCP servers to chat](/docs/copilot/chat/mcp-servers)
+- [Language Model API reference](/api/references/vscode-api.md#lm)
+- [Register an MCP server in a VS Code extension](/api/extension-guides/mcp.md)
+- [Use MCP tools in agent mode](/docs/copilot/chat/mcp-servers.md)

api/toc.json

@@ -32,6 +32,7 @@
       ["Language Model", "/api/extension-guides/language-model"],
       ["Language Model Tutorial", "/api/extension-guides/language-model-tutorial"],
       ["Language Model Tools", "/api/extension-guides/tools"],
+      ["MCP", "/api/extension-guides/mcp"],
       ["Prompt TSX", "/api/extension-guides/prompt-tsx"],
       ["Tree View", "/api/extension-guides/tree-view"],
       ["Webview", "/api/extension-guides/webview"],

build/sitemap.xml

@@ -1469,6 +1469,16 @@
         <changefreq>weekly</changefreq>
         <priority>0.8</priority>
     </url>
+    <url>
+        <loc>https://code.visualstudio.com/api/extension-guides/tools</loc>
+        <changefreq>weekly</changefreq>
+        <priority>0.8</priority>
+    </url>
+    <url>
+        <loc>https://code.visualstudio.com/api/extension-guides/mcp</loc>
+        <changefreq>weekly</changefreq>
+        <priority>0.8</priority>
+    </url>
     <url>
         <loc>https://code.visualstudio.com/api/extension-guides/prompt-tsx</loc>
         <changefreq>weekly</changefreq>

docs/copilot/copilot-extensibility-overview.md

@@ -1,53 +1,55 @@
 ---
 ContentId: e375ec2a-43d3-4670-96e5-fd25a6aed272
 DateApproved: 05/08/2025
-MetaDescription: Overview of how to extend GitHub Copilot in your Visual Studio Code extension by using the Chat API or Language Model API.
+MetaDescription: Overview of how to extend the AI features in your Visual Studio Code extension by using the Chat API or Language Model API.
 MetaSocialImage: images/shared/github-copilot-social.png
 ---
-# GitHub Copilot extensibility in VS Code
+# AI extensibility in VS Code
 
-Visual Studio Code has many AI features powered by GitHub Copilot to improve your coding experience, such as code completions, or natural language chat. You can further extend the built-in capabilities of Copilot, for example by contributing tools for [agent mode](/docs/copilot/chat/chat-agent-mode.md), or adding AI-powered features to your VS Code extension.
+Visual Studio Code has many AI features to improve your coding experience, such as code completions, or natural language chat. You can further extend the built-in capabilities, for example by contributing tools for [agent mode](/docs/copilot/chat/chat-agent-mode.md), or adding AI-powered features to your VS Code extension.
 
-Depending on your use case, you have the following options for extending Copilot in your VS Code extension:
+Depending on your use case, you have the following options for extending AI in your VS Code extension:
 
 - **Agent mode tool**: use the [Language Model Tool API](/api/extension-guides/tools.md) to contribute a tool for [agent mode](/docs/copilot/chat/chat-agent-mode.md) that is invoked automatically based on the user's prompt. Integrate deeply in VS Code by using other extension APIs in your tool.
 
-- **MCP tool**: automatically register external [MCP tools](/docs/copilot/chat/mcp-servers.md) that can then be used in [agent mode](/docs/copilot/chat/chat-agent-mode.md). MCP tools run outside of the VS Code extension host and don't have access to the VS Code extension APIs.
+- **MCP tool**: automatically register external [MCP tools](/docs/copilot/chat/mcp-servers.md) that can then be used in [agent mode](/docs/copilot/chat/chat-agent-mode.md). As an extension developer, you can [register an MCP tool](/api/extension-guides/mcp.md) as part of your extension. MCP tools run outside of the VS Code extension host and don't have access to the VS Code extension APIs.
 
 - **Chat participant**: use the [Chat](/api/extension-guides/chat.md) and [Language Model](/api/extension-guides/language-model.md) APIs to create a chat participant for [ask mode](/docs/copilot/chat/chat-ask-mode.md) that enables users to ask domain-specific questions by using natural language.
 
-- **Use Copilot's LLM**: use the [Language Model API](/api/extension-guides/language-model.md) and the [VS Code extension APIs](/api/extension-guides/overview.md) to build custom AI-powered features into your extension and enhance editor-specific interactions.
+- **Use AI model**: use the [Language Model API](/api/extension-guides/language-model.md) and the [VS Code extension APIs](/api/extension-guides/overview.md) to build custom AI-powered features into your extension and enhance editor-specific interactions.
 
-Alternatively, you can also build a **Copilot Extension**, implemented as a GitHub App with additional capabilities. Copilot Extensions work across all supported IDEs and GitHub, but don't have access to functionalities specific to VS Code. Get more info about [Copilot Extensions](https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions) in the GitHub documentation.
+Alternatively, you can also build a GitHub Copilot Extension, implemented as a GitHub App with additional capabilities. Copilot Extensions work across all supported IDEs and GitHub, but don't have access to functionalities specific to VS Code. Get more info about [Copilot Extensions](https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions) in the GitHub documentation.
 
 ## Use cases
 
-You can use Copilot's capabilities to enhance the development experience in VS Code by integrating AI-powered features into your extension. Here are some examples of how you can use Copilot in your VS Code extension:
+Here are some examples of how you can use AI in your VS Code extension:
 
 - **Docs querying**: use Retrieval-Augmented Generation (RAG) to query a third-party documentation service and generate responses based on the retrieved information.
 
-- **AI-assisted coding**: use the Copilot LLM to provide editor annotations to provide coding suggestions.
+- **AI-assisted coding**: use the AI model to provide editor annotations to provide coding suggestions.
 
-- **AI-powered reviews**: use the Copilot LLM to review your code for security vulnerabilities or performance improvements.
+- **AI-powered reviews**: use the AI model to review your code for security vulnerabilities or performance improvements.
 
 - **Data retrieval**: query a database or third-party data service to retrieve information about a specific topic.
 
 - **Enterprise coding assistant**: get chat responses that are grounded in the data of your enterprise and are aware of the specific coding guidelines your company follows.
 
 - **Enhance extensions**: use the Language Model API to add AI-powered features to your existing VS Code extensions.
 
-There are several examples already available in the Visual Studio Marketplace that extend Copilot in VS Code:
+There are several examples already available in the Visual Studio Marketplace that extend AI in VS Code:
 
 - Agent mode tools: Go to the [Marketplace](https://marketplace.visualstudio.com/search?term=tag%3Alanguage-model-tools&target=VSCode&category=All%20categories&sortBy=Relevance) or search for the `language-model-tools` tag in the [Extensions view](/docs/getstarted/extensions.md).
 
 - Chat participants: Go to the [Marketplace](https://marketplace.visualstudio.com/search?term=tag%3Achat-participant&target=VSCode&category=All%20categories&sortBy=Relevance) or search for the `chat-participant` tag in the [Extensions view](/docs/getstarted/extensions.md).
 
-## Get started with Copilot extensibility in VS Code
+## Get started with AI extensibility in VS Code
 
-To get started with extending Copilot in your VS Code extension, explore the following resources:
+To get started with extending AI in your VS Code extension, explore the following resources:
 
 - [**Chat sample**](https://github.com/microsoft/vscode-extension-samples/tree/main/chat-sample): sample code for building a VS Code extension that contributes an agent mode tool and chat participant.
 
+- [**MCP extension sample**](https://github.com/microsoft/vscode-extension-samples/blob/main/mcp-extension-sample): sample code for building a VS Code extension that registers an MCP tool.
+
 - [**Tutorial: AI-powered code annotations**](/api/extension-guides/language-model-tutorial.md): step-by-step guide to implement a VS Code extension that uses the Language Model API to generate code annotations in the editor to help improve your code.
 
 - [**Tutorial: Code tutor chat participant**](/api/extension-guides/chat-tutorial.md): step-by-step guide to implement a code tutor chat participant that enables users to ask for explaining a technical topic by using natural language in the Chat view in VS Code.

docs/toc.json

@@ -152,7 +152,7 @@
       }
       ],
       ["Tips and Tricks", "/docs/copilot/copilot-tips-and-tricks"],
-      ["Copilot Extensibility", "/docs/copilot/copilot-extensibility-overview"],
+      ["AI Extensibility", "/docs/copilot/copilot-extensibility-overview"],
       ["FAQ", "/docs/copilot/faq"],
       ["", "", {
         "name": "Reference",