Integrate MCP servers with Copilot
This reference helps Model Context Protocol (MCP) server and plugin authors integrate their tools with Copilot in VS Code. It covers configuration, supported capabilities, and editor-specific integrations.
The Copilot harness uses the Copilot SDK, the shared agent runtime used by VS Code, GitHub Copilot CLI, and the GitHub Copilot app. Building for its MCP support makes the same server usable across these compatible Copilot experiences, not only in the editor. Your server implements MCP and doesn't need to depend on the Copilot SDK.
- Make your server available: choose a delivery method.
- Check compatibility: review Copilot capability support and connected-client requirements.
- Maintain an existing Local integration: expand the deprecated Local compatibility appendix The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation. .
For protocol and server implementation guidance, use the MCP documentation and SDKs.
For information about using MCP servers as an end user, see Use MCP servers in VS Code.
Make your server available to Copilot
Use a managed connection for a supported service, or distribute your own server configuration or integration:
| Delivery method | When to use it |
|---|---|
| Copilot connector Copilot connectors is in preview and might change before it becomes generally available. | Use a GitHub-managed MCP connection for a supported service. GitHub handles configuration and authentication, with no local server setup. |
| Native configuration | Provide a launch command or HTTP endpoint that compatible Copilot clients can use without an editor extension. |
| Agent plugin | Bundle the server with skills and other customizations for a reusable workflow. Servers load through the plugin, not as copies in an editor profile. |
| Connected-editor integration | Offer an installation URL or register the server from an extension. Eligible editor-provided definitions can be forwarded to the runtime. |
Connectors reuse the managed connection across supported Copilot clients signed in with the same account. For self-managed servers, prefer native configuration or an agent plugin for cross-client reuse. Each execution host needs the required dependencies, credentials, and service access. Editor-dependent features don't automatically transfer to another client.
Native configuration
In VS Code, users add servers through Chat: Open Customizations > MCP Servers > Add Server. Global > Copilot Global selects the native user configuration. Link your installation instructions to the connection walkthrough.
For manual configuration, provide an entry using the portable mcpServers format. This example connects to an HTTP server:
{
"mcpServers": {
"myService": {
"type": "http",
"url": "https://example.com/mcp",
"tools": ["*"]
}
}
}
Replace the example URL with your server's MCP endpoint and document any authentication requirements. Don't include credentials in shared configuration.
The harness reads native configuration directly on the host where it runs:
- Workspace:
.mcp.jsonat the workspace root. - User:
$COPILOT_HOME/mcp-config.json, or~/.copilot/mcp-config.jsonwhenCOPILOT_HOMEis unset.
For stdio commands, supported fields, secrets, and remote hosts, see the MCP configuration reference. Don't use the deprecated Local servers format for new native configurations.
Before distributing an integration, verify an actual tool call in the intended Copilot experience. Adding configuration alone doesn't confirm that the session can use its tools. For failures, see MCP troubleshooting.
MCP support in Copilot
Start with tools, then add capabilities that your integration needs. Support depends on both the Copilot harness that runs the session and the client that presents it. Some capabilities require a connected client, such as the editor that renders MCP Apps or handles authentication.
| Capability | Support and limitations in Copilot |
|---|---|
| Tools | Invokes server tools under the session's tool availability and approval policies. |
| Sampling | Deprecated in MCP. Supported on compatible connections during an active turn, with per-server approval. |
| Elicitation | Presents form and URL requests through host-rendered input during an active turn. |
| MCP Apps | Displays interactive tool UI in a connected client that renders MCP Apps. This integration is Experimental. |
| Authorization | Supports MCP OAuth with authentication handled by the connected client. |
| Resources | Reads resources for MCP Apps. Native servers don't automatically appear in the editor's resource browser. |
| Roots | Deprecated in MCP. Existing integrations must check the runtime's negotiated capability and returned roots. |
| Prompts | The editor's /mcp.<server>.<prompt> completion flow isn't exposed in Copilot sessions. Use skills to distribute reusable workflows. |
This table describes available integrations, not full MCP specification conformance. Check the capabilities negotiated with the target client and match your implementation to the SDK's protocol-version guidance. Sampling and roots are deprecated in MCP 2026-07-28, so prefer their alternatives for new integrations.
For stdio, Streamable HTTP, and legacy SSE transport configuration, see the MCP configuration reference.
Tools
For native servers, tool availability depends on the server's tools filter and the controls for the selected harness. See native MCP configuration and tool management.
Tool approval depends on session permissions, organization policy, and existing approvals. Don't assume every call prompts the user or that readOnlyHint bypasses approval. Tool annotations describe behavior, not permission grants.
If your server uses dynamic tool discovery, verify tool-list changes in each target Copilot client. Clients can refresh their tool catalogs differently, and discovered tools still need to pass the session's availability filters.
Resources
In Copilot sessions, MCP Apps can read resources, but native servers don't automatically appear in the editor's resource browser. Return content in a tool result when the agent needs it to complete a task, rather than relying on resource discovery. For editor-managed browsing, see the Local compatibility appendix.
Prompts
To distribute reusable workflows for Copilot, bundle skills in an agent plugin. Skills are separate from the MCP prompts protocol.
The editor's /mcp.<server>.<prompt> picker and argument dialogs aren't exposed in Copilot sessions. For existing integrations that still need this workflow, expand the Local compatibility appendix and see Local prompt commands.
Authorization
Copilot sessions support MCP servers that require OAuth authentication. For directly configured servers, the runtime requests authentication through the connected client. VS Code stores these credentials, rather than relying on the runtime's keychain store.
Choose an authentication method that works with your configuration source. An editor input variable or an extension's SecretStorage value isn't automatically forwarded to a native server. See authentication and secrets.
Connected-editor OAuth integration
The connected editor provides OAuth integration for Copilot sessions, including built-in authentication support for GitHub and Microsoft Entra. It also supports other OAuth identity providers through Dynamic Client Registration (DCR) or a pre-registered OAuth client.
For your server integration:
- Implement the MCP authorization specification.
- Choose an identity provider that supports DCR, or provide instructions for a pre-registered client ID and, when required, a client secret. This isn't the OAuth client credentials grant.
- Include
http://127.0.0.1:33418andhttps://vscode.dev/redirectin the client's allowed redirect URLs. - Test sign-in from the intended Copilot session. For setup and credential handling, follow authentication and secrets.
Sampling
Copilot handles sampling during an active turn with per-server approval. Autopilot requires prior approval. Handle rejected or canceled requests without blocking the server.
The runtime executes the model request. Treat modelPreferences as hints, not a guarantee of a particular model or access to every model configured in the editor. The Local harness's model-access controls don't configure this runtime path.
Elicitation
Copilot supports form and URL elicitation during an active turn. Requests are canceled in Autopilot and declined when there is no active turn. Handle both outcomes without continuing the action that needs input.
The connected host renders the input UI. For your own HTML interface, use MCP Apps. Keep sensitive input, such as credentials, in a browser-based flow rather than a form.
If you're replacing a chat participant that collects user input, see the participant migration guidance for choosing between elicitation and MCP Apps.
Workspace roots
For existing integrations using roots, check the runtime's negotiated capability and returned roots. The editor's workspace folders don't establish which roots a native Copilot connection receives. Don't treat those roots, the server's working directory, and the harness's working directory as interchangeable.
MCP Apps
Use MCP Apps (Experimental) when a tool needs an interactive visualization or custom form. VS Code renders the UI for Copilot sessions. A connected client with MCP Apps support is required.
Include a useful text result for clients that don't render Apps. For ordinary questions, use elicitation instead.
For implementation, use the MCP Apps SDK's server helpers and plain JavaScript example.
VS Code behavior and limitations
The following describes the editor renderer, including when it displays an App from a Copilot session. Other MCP clients can provide different UI capabilities.
| Feature | VS Code Support |
|---|---|
| Display modes | inline only (not fullscreen or pip) |
| Send message | Fills chat input box; does not auto-send |
| Context updates | Appear as attachments |
| Clipboard write | Supported |
| Camera, microphone, geolocation | Not supported |
Security
MCP Apps run in sandboxed iframes with Content Security Policy (CSP) enforcement. Declare only the domains the UI resource needs: connectDomains for network requests, resourceDomains for assets, and frameDomains for embedded frames.
Create an MCP installation or lookup URL
VS Code provides URL handlers for installing an MCP server directly from configuration or looking it up in an active MCP registry or gallery.
Install an MCP server from configuration
Use vscode:mcp/install?{json-configuration} (Insiders: vscode-insiders:mcp/install?{json-configuration}) to prompt the user to add an MCP server configured with JSON:
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:
// For Insiders, use `vscode-insiders` instead of `vscode`
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;
This link opens the MCP server details editor in VS Code so the user can review the configuration before choosing to install.
Open an MCP server from a registry or gallery
If your MCP server is listed in an active MCP registry or gallery, you can provide deep links that resolve the server against the gallery and open its details view in VS Code:
-
Lookup by name:
vscode:mcp/by-name/<registry-server-name>Resolves the exact registry name against the active MCP gallery and opens the server details page for user review. For example, GitHub's server uses the registry name
io.github.github/github-mcp-server:vscode:mcp/by-name/io.github.github/github-mcp-server -
Lookup by gallery metadata URL:
vscode:mcp/<https-server-url-without-scheme>Opens a server using its HTTPS metadata URL in the active MCP gallery (omitting the
https://prefix). The URL must be within the configured gallery's origin and path; it is not the server's MCP connection endpoint or an arbitrary project website. For example, for a gallery hosted athttps://example.com/mcp, a server metadata resource might be:vscode:mcp/example.com/mcp/server
Both lookup routes open the server details page in VS Code so the user can review tools and permissions before choosing to install; they do not silently install the server or execute tools.
Shareable web badges and redirect wrapper
To embed installation or lookup links on websites or documentation badges, use the HTTPS redirect wrapper:
https://vscode.dev/redirect?url=<url-encoded-vscode-URL>
For example, to link to the GitHub server by its exact registry name:
https://vscode.dev/redirect?url=vscode%3Amcp%2Fby-name%2Fio.github.github%2Fgithub-mcp-server
For VS Code Insiders, use the vscode-insiders: scheme prefix (for example, vscode-insiders:mcp/by-name/<registry-server-name>). For more information about URL schemes across extensions, plugins, and workspaces, see URL handling.
Register an MCP server in your extension
Use this API when your server needs integration with an installed VS Code extension. Registration requires a connected editor and its extension host. Eligible extension-provided definitions can be forwarded to Copilot sessions. The extension isn't available in a standalone runtime.
For an integration that must work independently of the editor, prefer native configuration or an agent plugin. For forwarding limitations, see editor forwarding to Copilot.
To register an MCP server in your extension, you need to perform the following steps:
- Define the MCP server definition provider in the
package.jsonfile of your extension. - Implement the MCP server definition provider in your extension code by using the
vscode.lm.registerMcpServerDefinitionProviderAPI.
You can get started with a basic example of how to register an MCP server in a VS Code extension.
1. Static configuration in package.json
Extensions that want to register MCP servers must contribute the contributes.mcpServerDefinitionProviders extension point in the package.json with the id of the provider. This id should match the one used in the implementation.
{
...
"contributes": {
"mcpServerDefinitionProviders": [
{
"id": "exampleProvider",
"label": "Example MCP Server Provider"
}
]
}
...
}
2. Implement the provider
To register an MCP server in your extension, use the vscode.lm.registerMcpServerDefinitionProvider API to provide the MCP configuration for the server. The API takes a providerId string and a McpServerDefinitionProvider object.
The McpServerDefinitionProvider object has three properties:
onDidChangeMcpServerDefinitions: An event that signals a change to the server definitions.provideMcpServerDefinitions: A function that returns server definitions (vscode.McpServerDefinition[]). Keep discovery noninteractive.resolveMcpServerDefinition: An optional function for an editor-managed launch. Don't use it as the setup path for a native Copilot server. See interactive resolution for Local.
Don't rely on an interactive resolver running during background forwarding to Copilot. Provide a complete, safely usable definition, or perform setup through an explicit user action before publishing the updated definition. Input and command variables aren't a workaround: forwarding rejects configurations that require them before resolving variables.
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.
Local harness compatibility (deprecated)
Use this appendix only to maintain an existing Local harness integration. For new integrations, use the Copilot delivery methods.
Maintain an editor-managed Local integration
The Local harness uses the editor's MCP client directly. The workflows below describe that editor-managed connection, not a native Copilot connection. Some editor UI can also be available outside Local harness sessions; its availability doesn't imply that native servers use the same connection or discovery path.
Shared integrations that serve Copilot, including OAuth, MCP Apps, and extension registration, remain in the main guidance.
Local harness configuration
Users can retain .vscode/mcp.json and user-profile mcp.json. These are deprecated destinations in the guided flow, not native Copilot configuration files. Eligible definitions can be forwarded by the connected editor, but editor-specific behavior doesn't automatically carry over. See editor forwarding and its restrictions.
Local harness tool controls
The following screenshots show the Local harness's The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation. editor-managed tools picker and confirmation UI. They aren't the native Copilot tool controls for other harnesses.


In Local harness
The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation.
sessions, readOnlyHint affects default pre-execution confirmation, and openWorldHint affects confirmation of tool results. The editor's MCP client also supports dynamic tool discovery. Don't infer identical approval or refresh behavior in another harness.
Editor resource browsing
These browsing, attachment, and template workflows use servers discovered by the editor's MCP client in Local harness The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation. sessions. They are separate from native resource reads for MCP Apps.
For an editor-discovered server, the resource name appears in the MCP Resources picker. Users can open resources with MCP: Browse Resources. In sessions that support MCP resource attachments, users can also select Add Context > MCP Resources. Resources can contain text or binary content.

The editor client supports resource updates so users can see changes to a resource's contents in the editor.
Resource templates
The editor client also supports resource templates, which collect input parameters when referencing a resource. For example, a database resource can ask for the table name.
When accessing a resource with a template, users are prompted for the required parameters in a Quick Pick. You can provide completions to suggest values for the parameter.
Editor-managed workspace roots
The editor's MCP client provides workspace root folders to servers it connects to and notifies them when the roots change. This describes the editor-managed connection used by Local. It doesn't establish which roots a separate native Copilot connection receives.
Icons
The editor's MCP client supports icons provided on servers, resources, and tools. Don't rely on the same presentation in every harness or client. MCP icons have a src property that identifies the image:
- MCP servers using the HTTP or SSE transports can serve images from the same authority the MCP server is hosted on. For example, a server configured at
https://example.com/mcpcan serve images fromexample.com. - MCP servers using the stdio transport can serve images from the file system using
file:///URIs. - Any MCP server can embed images as data URIs beginning with
data:.
Interactive extension-provider resolution
For an editor-managed launch used by the Local harness
The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation.
, an extension can use resolveMcpServerDefinition to request missing information, such as an API key, before starting its server:
- Return the server definitions from
provideMcpServerDefinitionswithout prompting the user. - In
resolveMcpServerDefinition, complete any required authentication or input collection and update the definition before returning it. - If resolution is canceled or credentials are unavailable, return
undefinedor throw an appropriate error rather than starting an incomplete definition.
Don't write secrets to a workspace configuration or log them. This interactive launch flow isn't a native Copilot setup mechanism. For Copilot forwarding, publish a complete definition after an explicit setup action instead.
Local harness prompt commands
Prompts are reusable templates that can introduce your server's tools or describe a workflow. In Local harness
The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation.
sessions, users invoke /mcp.<server>.<prompt> and supply any arguments in the editor.
Define completions to suggest values in the editor's prompt argument dialog:
server.prompt(
'teamGreeting',
'Generate a greeting for team members',
{
name: completable(z.string(), value => {
return ['Alice', 'Bob', 'Charlie'].filter(n => n.startsWith(value));
})
},
async ({ name }) => ({
messages: [
{
role: 'assistant',
content: { type: 'text', text: `Hello ${name}, welcome to the team!` }
}
]
})
);

Users can enter a terminal command in the prompt dialog and use the command output as input for the prompt.
When you include a resource type in the prompt response, this editor workflow attaches the resource as context to the chat prompt in Local harness The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation. sessions.
Local harness sampling controls
For editor-managed sampling in the Local harness
The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation.
, the user authorizes access to models. MCP: List Servers > Configure Model Access restricts the models available to that server. The editor selects from the allowed models when applying modelPreferences.


MCP: List Servers > Show Sampling Requests opens the editor-managed sampling log. These controls don't configure Copilot runtime sampling in other harnesses.
MCP development mode in VS Code
For editor-managed server development, add a dev key to the VS Code configuration format. These restart and debugger controls apply to the editor-managed process used by Local, not to the native Copilot runtime. Forwarding a definition doesn't transfer this development mode.
The dev object has two properties:
-
watch: A glob pattern, or an array of glob patterns, to watch for file changes that restart the MCP server. -
debug: Enables you to set up a debugger with the MCP server. Currently, VS Code supports debugging Node.js and Python MCP servers.Node.js MCP server
To debug a Node.js MCP server, set the
debug.typeproperty tonode.{ "servers": { "my-mcp-server": { "type": "stdio", "command": "node", "cwd": "${workspaceFolder}", "args": ["./build/index.js"], "dev": { "watch": "src/**/*.ts", "debug": { "type": "node" } } } } }Python MCP server
To debug a Python MCP server, set the
debug.typeproperty todebugpy, and optionally set thedebug.debugpyPathproperty to the path of thedebugpymodule if it is not installed in the default Python environment.{ "servers": { "my-python-mcp-server": { "type": "stdio", "command": "python", "cwd": "${workspaceFolder}", "args": ["./server.py"], "dev": { "watch": "**/*.py", "debug": { "type": "debugpy", "debugpyPath": "/path/to/debugpy" } } } } }
Local server output
The following screenshots show errors and output for an editor-managed Local harness The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation. connection:

Select the error notification and Show Output, or run MCP: List Servers, select the editor-managed server, and choose Show Output. Its log doesn't describe a separate native connection to the same server.
