Adding an MCP Server to VS Code

What the configuration actually says

An MCP entry is a small declaration with three parts, whatever the exact file name and key structure in your editor version.

The command. The executable to run. This is a program on your machine, so it needs to exist and be runnable by you.

The arguments. Usually the package or script to execute, followed by any scope arguments the server accepts, such as which directory it may read.

The environment. Variables the server needs, typically credentials or connection strings.

When the editor starts a session, it runs that command, holds the process open, and exchanges protocol messages with it over standard input and output. When you close the editor, the process dies.

That model explains the debugging rules that follow. You are not configuring a connection to a remote service. You are declaring a program to launch, and everything that would go wrong launching a program manually can go wrong here, with less visible output.

Configuration usually exists at two levels: user, which applies everywhere you work, and workspace, which lives in the repository. The distinction matters more than it appears, and it is covered below.

The failures, in the order you will hit them

The command is not found. The editor launches the process without your shell's initialization, so a runtime installed through a version manager frequently is not on the path it sees. Your terminal finds it; the editor does not. Use an absolute path to the executable, or point at the specific installed version rather than a shim.

Relative paths resolve somewhere unexpected. The working directory of the child process is not reliably the folder you have open. Any directory argument should be absolute.

A required environment variable is missing. Same cause as the first: the process gets the environment the editor gives it, not the one your shell exports. Declare every variable the server needs explicitly in the configuration.

The server starts and exposes nothing. Usually it started, failed during initialization and exited, or it is waiting on something. The editor's MCP or output panel is where the error text goes, and it is the first place to look rather than the last.

The tools appear and never get used. Not a configuration failure. The descriptions are too vague for the model to know when they apply, which is a property of the server rather than your setup.

It works for you and not a colleague. Almost always an absolute path in shared configuration that only exists on your machine.

Scoping it properly

The default instinct is to grant the broadest access that makes the error go away, and it is worth resisting once at setup rather than repeatedly later.

Point file servers at the project, not the parent. Granting a home directory takes the same single argument as granting one repository, and it puts credentials, other clients' code and personal files inside the boundary. The agent will not usually go looking, and that is not the same as it being unable to.

Give database servers a read-only role. Write access should follow a workflow that actually needs it, not precede one.

Prefer per-project credentials. A key scoped to one project limits what a mistake can reach.

Install for a task, not for a catalogue. Every configured server adds its tool descriptions to every request in that workspace, so unused servers cost tokens continuously and add options the model can choose wrongly among.

One closing note on what configuration cannot fix. Connecting an agent to a repository lets it read files; it does not let it understand the codebase, and an agent that can read everything will still guess when it cannot find the relevant part. That is a retrieval problem rather than a configuration one, and it is where an index earns its place next to the servers you install.