API guide: register MCP server

api/extension-guides/mcp.md

@@ -0,0 +1,69 @@
+---
+# DO NOT TOUCH — Managed by doc writer
+ContentId: e655f324-ed0b-452d-aff3-52cdca3978a5
+DateApproved: 04/03/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 an `.vscode/mcp.json` file in the workspace, user settings, or can automatically discover them from other tools like Claude Desktop. VS Code extensions can also register MCP server configurations programmatically. This is useful if you already have an MCP server and want to register it as part of your extension.
+
+Alternatively, you can [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. Learn more about why you might want to [contribute a language model tool](/api/extension-guides/tools.md#why-implement-a-language-model-tool-in-your-extension).
+
+> [!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.registerMcpConfigurationProvider` 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 `McpConfigurationProvider` object.
+
+The `McpConfigurationProvider` object has two properties:
+
+- `onDidChange`: An event that is triggered when the MCP server configurations change.
+- `provideMcpServerDefinitions`: A function that returns an array of MCP server configurations (`vscode.McpServerDefinition[]`).
+
+The following example demonstrates how to register an MCP server in an extension.
+
+```ts
+import * as vscode from 'vscode';
+
+export function activate(context: vscode.ExtensionContext) {
+    const didChangeEmitter = new vscode.EventEmitter<void>();
+
+    context.subscriptions.push(vscode.lm.registerMcpConfigurationProvider('exampleGist', {
+        onDidChange: didChangeEmitter.event,
+        provideMcpServerDefinitions: async () => {
+            let servers: vscode.McpServerDefinition[] = [
+                {
+                    label: 'my-server',
+                    command: 'node',
+                    args: ['server.js'],
+                    cwd: vscode.Uri.file('/path/to/server'),
+                    env: {
+                        API_KEY: process.env['API_KEY'] || ''
+                    }
+                }
+            ];
+            return servers;
+        }
+    }));
+}
+```
+
+## 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: 04/03/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.md)
+- [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

@@ -1464,6 +1464,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>