VS Code · MCP

VS Code Copilot doesn't show your MCP server's tools: a checklist

The server is in your config. VS Code lists no tools from it, or the chat acts as if the server does not exist.

Work through the steps below in order. Most cases end at step 2 or 3. Checked against the VS Code docs on 21 November 2026.

The short answer

"Configured" and "running" are two different states. A config entry only tells VS Code how to start the server. The tools appear after it has started, and only for requests that include them. Each step below checks one link in that chain.

The VS Code docs changed in 2026: they now describe a Local and a Copilot harness (the part of VS Code that runs the agent) and mark the older editor-managed files as the Local one. Where the two differ, this page says so.

1. Pick an agent that uses tools

Tools are for agents that can act, not for plain questions. The VS Code page on tools says to choose a harness and an agent that can implement changes, such as Agent. For the Local harness, select Agent from the agent picker in the chat.

The docs do not call this a strict requirement for MCP tools, so treat it as the first thing to rule out, not as the proven cause.

2. Check the config key

This is the most common mistake, and it comes from copying a snippet written for another tool. Claude Code and Cursor read mcpServers. VS Code's .vscode/mcp.json reads servers. We shipped this exact error in our own copy-paste snippets once, so it is easy to miss:

.vscode/mcp.json (wrong key)
{
  "mcpServers": {
    "my-server": { "command": "npx", "args": ["-y", "my-mcp-server"] }
  }
}
.vscode/mcp.json
{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

The configuration reference lists the type values stdio (runs a command), http (Streamable HTTP) and sse (legacy). It does not say that type is required, but setting it removes any doubt. A remote server looks like this:

.vscode/mcp.json (remote server)
{
  "servers": {
    "my-remote": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Two more details from the reference. First, the portable files use the mcpServers key: .mcp.json in the project folder, which VS Code offers in guided setup only when the experimental setting chat.mcp.workspaceRootConfig.enabled is on, and mcp-config.json under ~/.copilot. Second, a stdio entry needs command. args and env are optional.

3. Is the server running and trusted?

  1. Run MCP: List Servers from the Command Palette. Select your server. The actions include Start Server, Stop Server and Restart Server, and Show Output.
  2. Check Workspace Trust. Servers from .vscode/mcp.json and .mcp.json inherit it. In Restricted Mode they cannot start. In a trusted workspace they start without a separate MCP trust prompt.
  3. Servers from other sources, such as your user configuration, use a separate trust decision and might prompt on first start or after a change. MCP: Reset Trust clears those decisions. It does not reset Workspace Trust.

Stopping a server ends only the current run. A later request can start it again. If the server is not in the list at all, the file was not read: go back to step 2.

4. Read the server output

In MCP: List Servers, select the server and choose Show Output. The Output view opens with that server's channel selected. Errors from the start show up here.

For a stdio server, the docs name four things to check:

  • the command and its args
  • the runtime is installed (for example Node.js for npx)
  • PATH in the environment where the server runs. A command available locally might be missing in a remote or container session.
  • for a Docker server, no detached mode (-d): the server must stay attached to VS Code

Run the same command in a terminal first. If it prints an error there, VS Code will not do better. The docs say nothing special about npx on Windows, so we do not claim a cause there.

5. Check the tool list

A running server can still be filtered out of the request. Where you see the tools depends on the harness:

  • Local harness: select Configure Tools in the chat input and check that the server's tools are ticked.
  • Copilot harness: the Tools tab in the Agent Customizations editor controls which tools a session can use. The selection persists across windows and profiles.

There is also a limit. A Local request can fail with "Cannot have more than 128 tools per request". The docs say to deselect tools or servers you do not need. An experimental setting, github.copilot.chat.virtualTools.threshold, controls when tools are grouped for on-demand discovery. Setting it to 0 turns the grouping off. The docs do not say whether the 128 limit applies to the Copilot harness.

6. The tool exists but is not called

The VS Code troubleshooting page gives these steps:

  1. Run MCP: List Servers and check that the server is running.
  2. Open the Chat Debug view (Developer: Show Chat Debug View, or the overflow menu in the Chat view) and check whether the tool is in the available tool definitions.
  3. If it is missing, the problem is the server (steps 2 to 5). If it is there, look at the Agent Debug Logs for tool calls and errors.
  4. Name the tool and the action in your prompt, then repeat the request.

7. An organization policy

On a managed machine, an administrator can restrict which MCP servers start. The docs describe a managed allowlist and say that local configuration cannot override organizational restrictions. In the troubleshooting table the symptom is listed as "Enterprise restriction", and the fix is to ask an administrator to check the allowlist.

The pages we read do not name a setting for this, so we give none. Sign-in problems with an HTTP server are a separate case: the docs keep authentication apart from trusting a server and from approving single tool calls.

With cachly

cachly ships an MCP server for project memory. In VS Code the extension sets it up: it writes .vscode/mcp.json with the servers key, so step 2 is done for you. If Copilot shows a Start button above the entry the first time, click it once. See cachly for GitHub Copilot and the setup guide.

Frequently asked questions

Is it servers or mcpServers?

It depends on the file. The VS Code reference says .vscode/mcp.json and the user mcp.json use a top-level servers object. The portable files, .mcp.json in the project folder and mcp-config.json, use mcpServers.

The server runs, but the model never calls its tools. Why?

Open the Chat Debug view and look at the tool definitions of the request. If the tool is listed, the server is fine and the prompt needs to name the tool and the action. If it is missing, go back to the checklist above.

Which VS Code version do I need?

The pages checked for this article do not state a minimum version, so none is given here. Update VS Code first anyway, and check the Help menu for the version you run.

Sources

All read on 21 November 2026.

More: AGENTS.md, CLAUDE.md and copilot-instructions.md · One memory for Claude Code, Cursor and Copilot · All docs