API guide: register MCP server

api/extension-guides/mcp.md

@@ -0,0 +1,93 @@
+---
+# 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 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 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.
+
+The `McpServerDefinitionProvider` object has two properties:
+
+- `onDidChangeMcpServerDefinitions`: event that is triggered when the MCP server configurations change.
+- `provideMcpServerDefinitions`: function that returns an array of MCP server configurations (`vscode.McpServerDefinition[]`).
+
+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 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.registerMcpServerDefinitionProvider('exampleGist', {
+        onDidChangeMcpServerDefinitions: didChangeEmitter.event,
+        provideMcpServerDefinitions: async () => {
+            let servers: vscode.McpServerDefinition[] = [];
+
+            let apiKey = vscode.workspace.getConfiguration().get<string>('apikey') || '';
+
+            // Example of a simple stdio server definition
+            servers.push(new vscode.McpStdioServerDefinition(
+            {
+                label: 'my-server',
+                command: 'node',
+                args: ['server.js'],
+                cwd: vscode.Uri.file('/path/to/server'),
+                env: {
+                    API_KEY: apiKey
+                },
+                version: '1.0.0'
+            });
+
+            // Example of an HTTP server definition
+            servers.push(new vscode.McpHttpServerDefinition(
+            {
+                label: 'my-http-server',
+                uri: 'http://localhost:3000',
+                headers: {
+                    Authorization: `Bearer ${apiKey}`
+                },
+                version: '1.0.0'
+            }));
+
+            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: 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>