Using MCP with the Claude Code VS Code Extension | CLI and /mcp Setup Guide

Prerequisites: The Two-Pronged Approach — CLI for Adding, /mcp for Managing {#prerequisite}

The Claude Code VS Code extension clearly divides MCP operations between the CLI and the chat panel. The official documentation's feature comparison table explicitly states that "MCP server configuration" is "Yes" for the CLI and "Partial (add servers via CLI; manage existing servers using /mcp in the chat panel)" for the VS Code extension — meaning you must always add servers through the integrated terminal.

Prerequisites include VS Code 1.98.0 or later and an Anthropic account. Even right after installing the extension, there is no need to install the claude binary separately, as it is bundled with the extension. You can run claude mcp add the moment you open the integrated terminal with Ctrl+\`` / Cmd+``. Conversely, the inability to add servers via a GUI panel is by design — avoid bringing habits from other extensions like Cursor.

Source: Using Claude Code in VS Code — Claude Code Docs

CLI Steps for Adding an MCP Server {#cli-add}

Run claude mcp add in the VS Code integrated terminal. The basic syntax is as follows.

claude mcp add --transport <stdio|http|sse> <name> <url-or-command> [--header "Key: Value"]

Here is the command for adding a remote HTTP MCP server, as shown in the official documentation.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

There are three key points to keep in mind.

1. Always specify --transport explicitly (stdio can be omitted, but explicit is recommended for team sharing)
2. <name> becomes the prefix mcp__<name>__<tool> inside the chat, so keep it short and unique
3. Multiple --header flags are allowed for authentication. Wrapping in double quotes like "Authorization: Bearer $GITHUB_PAT" causes the shell to expand $GITHUB_PAT (single quotes '...' will pass the string literally without expansion, so be careful)

After adding, no restart of the extension is required — just tell Claude the tool name and it can be called immediately.

Source: Using Claude Code in VS Code — Claude Code Docs / Connecting to External Tools with MCP

Managing State with the /mcp Dialog {#mcp-panel}

After adding a server, enabling/disabling, reconnecting, and re-authorizing via OAuth can all be handled from the chat panel without leaving VS Code. Typing /mcp in the prompt box opens the "MCP Management Dialog," which displays a list of registered servers and their connection status (connected / failed / needs auth).

The main operations available in this dialog are:

1. Toggle individual servers on/off (per workspace)
2. Manually reconnect a dropped connection
3. Resume an OAuth flow (when a token has expired)
4. View the list of tools (only those visible to the model)

If a server added via claude mcp add does not appear in /mcp, the most common cause is that it is being suppressed by enabledMcpjsonServers or disabledMcpjsonServers in ~/.claude/settings.json. Since the extension and CLI share the same settings file, disabling something in one is reflected in the other.

Project Sharing with Scopes and .mcp.json {#scope-mcpjson}

claude mcp add supports three scopes. If you plan to distribute to a team, decide on the scope before adding.

1. --scope user (default) — saved to ~/.claude.json, active across all projects
2. --scope project — generates a .mcp.json at the repository root, shareable via git
3. --scope local — scoped to that repository for yourself only (for PoCs you do not want to share with the team)

An example command for project sharing:

claude mcp add --scope project --transport stdio mydb \
  -- node ./mcp-servers/mydb/index.js

By committing .mcp.json, any developer who opens the same repository with Claude Code will be prompted with the MCP server, and they can start using it after approving it in their own /mcp. The golden rule is to never write secrets directly in .mcp.json; reference them using the ${env:VAR} format instead. Combined with plugin-based MCP additions, you can create an experience where the MCP environment is fully set up the moment someone clones the repository.

Switching Configurations with --mcp-config {#mcp-config}

When you want to switch between a full development configuration and a minimal CI configuration, you can pass --mcp-config <file> at startup to swap the MCP settings file. Launch it from the VS Code integrated terminal like this:

claude --mcp-config ./.claude/mcp.lightweight.json

Since this flag reads the specified file instead of .mcp.json, you can switch between the following with a single key:

1. Full production investigation config (GitHub, Sentry, Datadog — all included)
2. Lightweight coding-focused config (only Figma and filesystem)
3. Zero-config for CI/offline (no MCP, pure code assistance only)

This is a usage pattern also featured in articles on zenn.dev/kuxu, and it is effective for reducing token consumption and latency. Registering a command like Claude Code (light) in VS Code tasks or keybindings lets you switch configurations in under a second.

Source: Comfortable MCP Configuration with Claude Code Using --mcp-config (zenn.dev/kuxu)

The Built-in ide Server and Hook Configuration {#ide-server}

While the VS Code extension is active, the CLI side automatically connects to a local MCP server named ide. Launching the diff viewer, retrieving selected ranges during @-mentions, and executing cells in Jupyter notebooks all go through this ide server.

It is not visible in /mcp by design, but if your organization uses PreToolUse hooks to whitelist MCP tools, you need to add the following two to the allow list:

1. mcp__ide__getDiagnostics — returns data from the VS Code Problems panel (errors/warnings), read-only
2. mcp__ide__executeCode — executes a cell in the active Jupyter notebook, with a Quick Pick confirmation every time

executeCode is designed not to run silently — VS Code shows a Quick Pick asking Execute/Cancel every time. Even if the hook permits it, this confirmation cannot be skipped, so it stays on the safe side even when dealing with untrusted code. The transport is limited to 127.0.0.1 using a random high port, and the auth token is written under ~/.claude/ide/ with 0600 permissions, making it inaccessible to other users on the same machine.

Source: Using Claude Code in VS Code — Claude Code Docs / Built-in IDE MCP Server

Common Connector Recipes {#recipes}

Here are four commonly used MCP add commands for Claude Code in VS Code.

1. GitHub (remote HTTP)

   claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
     --header "Authorization: Bearer $GITHUB_PAT"
   

2. Figma (remote HTTP, post-login context)

   claude mcp add --transport http figma https://api.figma.com/v1/mcp \
     --header "X-Figma-Token: $FIGMA_TOKEN"
   

3. filesystem (local stdio, faster search)

   claude mcp add --transport stdio fs -- npx -y @modelcontextprotocol/server-filesystem .
   

4. Postgres (local stdio, development DB)

   claude mcp add --transport stdio pg \
     -- npx -y @modelcontextprotocol/server-postgres "postgres://user:pass@localhost/dev"
   

For practical combination examples, the Qiita article on Figma MCP integration goes into great detail. It covers a VS Code + Claude Code + Figma MCP setup that lets you convert design comps directly into code.

Source: AI Coding Environment Setup Guide with VSCode + Claude Code + Figma MCP (Qiita) / Complete Guide to Integrating Claude Code and Serena MCP in VSCode on Windows (Qiita)

Troubleshooting Checklist {#troubleshooting}

If tools are "not visible to Claude" or /mcp shows "failed," working through the following checklist in order resolves 90% of issues.

1. Expired auth token — if /mcp shows needs auth, re-run OAuth from the dialog
2. Wrong transport type — run claude mcp list to check whether a remote API was accidentally registered as stdio
3. Disabled in settings — review enabledMcpjsonServers / disabledMcpjsonServers in ~/.claude/settings.json
4. Missing env var expansion in .mcp.json — check that references like ${env:GITHUB_PAT} have not been written as literals
5. Reload VS Code — run "Developer: Reload Window" from the command palette (this regenerates the ide server)
6. Restricted Mode — if Workspace Trust is in restricted mode, extensions are disabled; enable workspace trust
7. Extension logs — run "Claude Code: Show Logs" from the command palette; auth errors and port conflicts appear here

If you want to step outside VS Code and use the CLI directly, running claude in the integrated terminal continues the current session. Using claude --resume brings up a history picker, so you can pick up a session that got stuck in the extension and continue debugging MCP behavior on the CLI side.

Source: Using Claude Code in VS Code — Claude Code Docs / Fixing Common Issues

The key to working with MCP in the Claude Code VS Code extension comes down to five points: add via CLI, manage via /mcp, share via .mcp.json, switch with --mcp-config, and treat the built-in ide server as a separate category. Run claude mcp add just once following the steps in this article, and you can manage your entire MCP environment from the chat panel without ever returning to the terminal.