MCP developer guide

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 implements the full MCP specification, enabling you to create MCP servers that provide tools, prompts, and resources for extending the capabilities of AI agents in VS Code.

This guide covers everything you need to know to build MCP servers that work seamlessly with VS Code and other MCP clients.

Add MCP servers to VS Code

Users can add MCP servers within VS Code in several ways:

• Workspace configuration: Specify the server configuration in a .vscode/mcp.json file in the workspace.
• User or remote settings: Define servers globally in VS Code user settings, or for a remote machine or container in its remote settings.
• Autodiscovery: VS Code can discover servers from other tools like Claude Desktop.
• Extension: VS Code extensions can register MCP servers programmatically.

In addition, you can trigger MCP installation by opening a special URL (vscode:mcp/install), or from the command line (--add-mcp).

Manage MCP servers

Run the MCP: List Servers command from the Command Palette to view the list of configured MCP servers. You can then select a server and perform actions on it like starting, stopping, viewing the logs, and more.

MCP URL handler

VS Code provides a URL handler for installing an MCP server from a link. To form the URL, construct an obj object in the same format as you would provide to --add-mcp, and then create the link by using the following logic:

// For Insiders, use `vscode-insiders` instead of `code`
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;

This link can be used in a browser, or opened on the command line, for example via xdg-open $LINK on Linux.

MCP features supported by VS Code

VS Code supports the following transport methods for MCP servers:

• Standard input/output (stdio): Run a server as a local process that communicates over standard input and output
• Streamable HTTP (http): Communicate with a (remote) server using HTTP POST and GET
• Server-sent events (sse, legacy): Supported with a (remote) server over HTTP using server-sent events

The following MCP features are supported in VS Code:

• Tools: Executable actions that can be used in agent mode
• Prompts: Reusable chat prompt templates, optionally with parameters, which users can invoke through slash commands(/mcp.servername.promptname) in chat
• Resources: Data and content which users can add as chat context or interact with directly in VS Code
• Authorization: Authorize access to an MCP server using OAuth
• Sampling (Preview): Make language model requests using the user's configured models and subscription
• Elicitation: Request input from the user
• Workspace roots: Information about the user's workspace structure

For complete specification details, see the Model Context Protocol documentation.

Tools

Tool definition

VS Code supports MCP tools in agent mode, where they are invoked as needed based on the task. Users can enable and configure them with the tools picker. The tool description is shown in the tools picker, alongside the tool name, and in the dialog when asking for confirmation before running a tool.

Users can edit model-generated input parameters in the tool confirmation dialog. The confirmation dialog will be shown for all tools that are not marked with the readOnlyHint annotation.

Dynamic tool discovery

VS Code also supports dynamic tool discovery, allowing servers to register tools at runtime. For example, a server can provide different tools based on the framework or language detected in the workspace, or in response to the user's chat prompt.

Tool annotations

To provide extra metadata about a tool's behavior, you can use tool annotations:

• title: Human-readable title for the tool, shown in the Chat view when a tool is invoked
• readOnlyHint: Optional hint to indicate that the tool is read-only. VS Code doesn't ask for confirmation to run read-only tools.

Resources

Resources enable you to provide data and content to users in a structured way. Users can directly access resources in VS Code, or use them as context in chat prompts. For example, an MCP server could generate screenshots and make them available as resources, or provide access to log files, which are then updated in real-time.

When you define an MCP resource, the resource name is shown in the MCP Resources Quick Picks. Resources can be opened via the MCP: Browse Resources command or attached to a chat request with Add Context and then selecting MCP Resource. Resources can contain text or binary content.

VS Code supports resource updates, enabling users to see changes to the contents of a resource in real-time in the editor.

Resource templates

VS Code also supports resource templates, enabling users to provide input parameters when referencing a resource. For example, a database query tool could ask for the database 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.

Prompts

Prompts are reusable chat prompt templates that users can invoke in chat by using a slash command (mcp.servername.promptname). Prompts can be useful for onboarding users to your servers by highlighting various tools or providing built-in complex workflows that adapt to the user's local context and service.

If you define completions to suggest values for prompt input arguments, then VS Code shows a dialog to collect input from the user.

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!` }
      }
    ]
  })
);

When you include a resource type in the prompt response, VS Code attaches that resource as context to the chat prompt.

Authorization

VS Code supports MCP servers that require authentication, allowing users to interact with an MCP server that operates on behalf of their user account for that service.

The authorization specification cleanly separates MCP servers as Resource Servers from Authorization Servers, allowing developers to delegate authentication to existing identity providers rather than building their own OAuth implementations from scratch.

VS Code has built-in authentication support for GitHub and Microsoft Entra. If your MCP server implements the latest specification and uses GitHub or Microsoft Entra as the authorization server, users can manage which MCP servers have access to their account through the Accounts menu > Manage Trusted MCP Servers action for that account.

If your MCP server uses a different authorization server, VS Code also supports Dynamic Client Registration. Users can then view their authentication status also through the Accounts menu. To remove dynamic client registrations, users can use the Authentication: Remove Dynamic Authentication Providers command in the Command Palette.

VS Code still supports MCP servers that behave as an authorization server, but it is recommended to use the latest specification for new servers.

Sampling (Preview)

VS Code provides access to sampling for MCP servers. This allows your MCP server to make language model requests using the user's configured models and subscriptions. Sampling can be used to summarize large data or extract information before sending it to the client, or to implement smarter agentic decision in tool logic.

The first time an MCP server performs a sampling request, the user is prompted to authorize the server to access their models.

Users can specify which models they allow the MCP server to use for sampling by using the MCP: List Servers > Configure Model Access command in the Command Palette. You can specify modelPreferences in your MCP server to provide hints about which models to use for sampling, and VS Code will pick from the allowed models when evaluating the server's preferences

Users can view the sampling requests made by an MCP server with the MCP: List Servers > Show Sampling Requests command in the Command Palette.

Workspace roots

VS Code provides the MCP server with the user's workspace root folder information.

Register MCP servers in VS Code extensions

If you're building a VS Code extension that includes or depends on an MCP server, you can register it programmatically using the VS Code API. This approach avoids requiring users to manually configure your server.

For complete details and code examples, see the MCP servers API guide.

Troubleshoot and debug MCP servers

MCP development mode in VS Code

When developing MCP servers, you can enable MCP development mode in VS Code. To enable development mode, add the dev property to your MCP server configuration and specify the following properties:

• watch: A glob pattern to watch for file changes to files and automatically restart the server
• debug: Debugger to attach to your MCP server process when starting it (currently only supported for servers launched with node or python)

The following example shows how to configure a Node.js MCP server that watches for changes to TypeScript files in the src directory and uses the Node.js debugger:

{
  "servers": {
    "my-mcp-server": {
      "type": "stdio",
      "command": "node",
      "cwd": "${workspaceFolder}",
      "args": ["./build/index.js"],
      "dev": {
        "watch": "src/**/*.ts",
        "debug": { "type": "node" }
      }
    }
  }
}

MCP output log

When VS Code encounters an issue with an MCP server, it shows an error indicator in the Chat view.

Select the error notification in the Chat view, and then select the Show Output option to view the server logs. Alternatively, run MCP: List Servers from the Command Palette, select the server, and then choose Show Output.

Best practices

• Naming conventions to ensure unique and descriptive names
• Implement proper error handling and validation with descriptive error messages
• Use progress reporting to inform users about long-running operations
• Keep tool operations focused and atomic to avoid complex interactions
• Document your tools clearly with descriptions that help users understand when to use them
• Handle missing input parameters gracefully by providing default values or clear error messages
• Set MIME types for resources to ensure proper handling of different content types in VS Code
• Use resource templates to allow users to provide input parameters when accessing resources
• Cache resource content to improve performance and reduce unnecessary network requests
• Set reasonable token limits for sampling requests to avoid excessive resource usage
• Validate sampling responses before using them

Naming conventions

The following naming conventions are recommended for MCP servers and their components:

Get started to create an MCP server

VS Code has all the tools you need to develop your own MCP server. While MCP servers can be written in any language that can handle stdout, the MCP's official SDKs are a good place to start:

• TypeScript SDK
• Python SDK
• Java SDK
• Kotlin SDK
• C# SDK

You might also find the MCP for Beginners curriculum helpful to get started with building your first MCP server.

Related resources

• Use MCP in agent mode in VS Code
• Use agent mode in Visual Studio Code
• VS Code curated list of MCP servers
• Model Context Protocol Documentation