Debug an MCP Server in VSCode

Start with the output log, then the config, then run the server by hand. To debug mcp server in vscode problems, move from the editor outward. Most failures come from a wrong command, a missing environment variable or a token with too narrow a scope. Once the server starts alone, any remaining fault sits in the editor config or in the permissions you granted.

Where should you look first when an MCP server fails?

Begin with the symptom, because it points to a layer. If the server never appears in the editor, the config file is the likely cause. If it appears but its tools are missing, the process probably started and then exited. If the tools show up but return empty or denied results, the fault is usually in credentials rather than in the editor.

That ordering saves time. When you debug mcp server in vscode, resist the urge to reinstall first. Reinstalling rewrites the same config you have not yet read, so the same error comes back with a fresh timestamp.

A short checklist keeps the order honest:

1. Read the server's output log for the first error line.
2. Open the config file and check the command, arguments and paths.
3. Run the same command in a terminal, outside the editor.
4. Check tokens, environment variables and transport type.

For the file format itself, the guide VS Code mcp.json: the full schema, with examples covers every field.

How do you read the MCP output log?

The editor captures what a server prints while it starts and runs. Open the output view and pick your server from the channel list. The exact menu wording can change between VS Code releases, so look for the channel named after the server rather than relying on a remembered path.

Read from the top, not the bottom. The first error line is the useful one, because later lines are often consequences of it. A command that cannot be found, a module that fails to load or an authentication refusal each leaves a distinct first line, and it usually names the cause directly.

If the log is empty, the process may never have launched. That points back to the command or path in the config rather than to the server's own code. An empty log together with a server that shows no tools is a strong hint that the editor could not start the executable at all.

How do you check the config file and paths?

Most startup failures are small mistakes in the config: a typo in the command, an argument split wrongly, or a relative path that resolves from a different folder than you expected. Open the file and read the command exactly as the editor will run it, character by character.

The publisher's install instructions give a known-good reference. The official GitHub server's published setup runs npx -y @modelcontextprotocol/server-github, and the Playwright server's setup runs npx -y @playwright/mcp. If your entry differs from the published command in ways you did not intend, fix that first.

Also check that the tool behind the command is installed and reachable. An editor launched from a menu may not see the same environment as your shell, so a command that works in a terminal can still fail inside the editor. Use absolute paths when in doubt. The guide How to Add an MCP Server to VS Code shows a clean starting entry.

Can you test the server outside the editor?

Yes, and it is the fastest way to split the problem in two. Copy the command and arguments from your config and run them in a terminal with the same environment variables. If the server starts and waits for input, the editor config is the suspect. If it fails there too, the editor is innocent.

For a server in the catalogue, the install command is a useful control. Running mcpizy install github sets up the GitHub server, and the publisher's page lists the same server as exposing nine tools, including get_repository, list_issues and list_pull_requests. Seeing those tools appear tells you the server side works.

When you debug mcp server in vscode this way, change one thing at a time. Run the command, note the result, adjust the config, reload and compare. Changing the command, the token and the transport at once makes the outcome impossible to attribute.

What are the common failures: auth, env vars and transport?

Authentication causes many silent failures, because the server starts fine and then returns nothing useful. The GitHub server's listing warns that fine-grained tokens have surprising scope limits: the all-repositories toggle does not include private repos by default. If list_pull_requests returns empty for a private repository, the listing advises regenerating the token with that repository explicitly selected.

Environment variables are the second cause. A token set in your shell is not necessarily visible to a server launched by the editor. Put the variable in the server's own config entry, and never paste a real secret into a file you commit.

Transport is the third. A local server started by command and a remote server reached by URL are configured differently, so a URL placed in a command field, or the reverse, fails at once. The article Local vs Remote MCP Servers: What Changes explains how the two differ in setup.

What will logs not tell you?

Logs show whether a server started and what it printed. They do not show whether the data it returns is complete. The GitHub server's listing notes that search_code uses an index that is eventually consistent and lossy, and that recently pushed code can take five to thirty minutes to appear. An empty search result there is not a bug in your setup.

Logs also hide rate limits until you hit them. The same listing states a limit of 5,000 requests per hour for an authenticated personal access token, so a repository-wide audit across many repos can reach it. When calls start failing late in a long session, count requests before blaming the config.

Finally, a clean log says nothing about safety. A server that starts correctly may still hold broader permissions than you intended. Before you trust one, read How to Audit an MCP Server Before Install, and review what each tool can write.

Which servers with documented setup should you try next?

Practice on a server whose setup is well documented, so you can tell your mistakes from the server's. The GitHub server is a sensible first choice: it lists its install command and nine tools, and its listing spells out the token and rate-limit pitfalls above.

The Playwright server is a good second. The CheckMCP audit of microsoft/playwright-mcp scored it 100 out of 100, grade A, with an Apache-2.0 licence and 4 open issues, and its listing shows seven tools such as browser_navigate and browser_snapshot. A well-maintained, well-documented server makes a clean control when you debug mcp server in vscode.

Once both run, add your own server and compare its log against theirs. The step-by-step guide How to Use GitHub MCP with Claude Code offers another working reference.