How to Add an MCP Server to Claude Code (CLI and VS Code)

Claude Code can read your files and run shell commands out of the box, but it cannot see your issue tracker, your database, or your image generator until you connect them. That connection is an MCP server. MCP, short for Model Context Protocol, is the open standard that lets Claude Code call outside services as if they were built in. Adding one takes a single command, and the same server then shows up in the terminal and in the VS Code extension.

This article shows the exact commands, the three scopes that decide who gets a server, the OAuth and token details that trip people up, and a real example using PicassoIA's image and video connection. The commands and flags below were checked against the current Claude Code documentation on 6 October 2026, so they match what you will see in your own terminal.

💡 The short version: for a hosted server run claude mcp add --transport http <name> <url>. For a local one run claude mcp add --transport stdio <name> -- <command>. Then type /mcp inside Claude Code and confirm the server says Connected.

Before You Add Anything

What You Need Installed

You need Claude Code itself. For the VS Code route you also need VS Code 1.94.0 or later with the Claude Code extension. Check the CLI version with claude --version, because a few features depend on it:

• Adding or removing servers from the VS Code dialog needs v2.1.261 or later
• The /mcp reconnect all command needs v2.1.284 or later

An old install is the first thing to rule out when a step below does nothing. You also need the server's details, and they depend on where the server runs. A remote server gives you a URL plus either a token or a browser sign-in. A local server gives you a command that launches it, usually through npx, so Node.js has to be installed.

Pick a Transport First

The --transport flag tells Claude Code how to talk to the server. There are three choices.

A quick rule: a URL ending in /mcp means HTTP, a URL ending in /sse means the older SSE transport (check whether the vendor now offers an HTTP URL), and an npx command means stdio.

Add a Server From the CLI

The CLI is the fastest route, and everything you do here is also what the VS Code extension reads. Open a terminal in your project folder, or any folder if you plan to use the user scope described later.

Remote HTTP Servers

The pattern is claude mcp add --transport http <name> <url>. Here is a real hosted server:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Copy Prompt

The word notion is the name you choose. It appears in tool names as mcp__notion__<tool>, so keep it short and lowercase. When the server wants a token, pass it as a header:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Copy Prompt

💡 Watch out: claude mcp add saves the configuration without checking your credentials. A placeholder token is accepted, and the failure only appears later when the server tries to connect.

Local Stdio Servers

A stdio server is a program on your own machine that Claude Code starts and talks to through standard input and output. The pattern is claude mcp add [options] <name> -- <command> [args...]:

claude mcp add --transport stdio files -- npx -y @modelcontextprotocol/server-filesystem ~/projects

Copy Prompt

The double dash is mandatory. Everything after it goes to the server untouched, and every Claude Code option (--env, --scope, --transport) has to come before the name. To pass an environment variable to the server process, use --env:

claude mcp add --transport stdio --env MY_SERVICE_TOKEN=paste-here myservice -- npx -y your-server-package

Copy Prompt

Replace your-server-package with the package the vendor documents. On native Windows (not WSL), npx often needs a wrapper so the shell can launch it:

claude mcp add --transport stdio files -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Users\you\projects

Copy Prompt

Check That It Connected

Three commands handle day-to-day management:

claude mcp list
claude mcp get files
claude mcp remove files

Copy Prompt

list shows every configured server, get shows one server's details, and remove deletes it. If you already have a server definition as JSON, claude mcp add-json <name> '<json>' saves you from translating it into flags. Inside a Claude Code session, /mcp shows live status and handles sign-in.

Add a Server in VS Code

The Claude Code extension and the CLI share one MCP configuration, so there are two routes and neither locks you in.

Use the /mcp Dialog

1. Open the Claude Code panel in VS Code.
2. Type /mcp in the chat box.
3. In the dialog, add a server, or remove one saved at the local, user, or project scope.
4. Enable or disable servers, reconnect one, or manage OAuth sign-in from the same place.
5. Start a new conversation, type /mcp again, and check the server reads Connected.

Step 5 matters. Changes take effect in conversations you start afterwards, so an already open chat will not see the new server.

Or Use the Terminal

Open the integrated terminal with Ctrl+` (or Cmd+` on Mac) and run the same claude mcp add command you would use anywhere else. The dialog and the terminal command save to the same configuration. Here is GitHub's remote server with a personal access token:

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

Copy Prompt

A server with bad credentials shows Failed in /mcp, while a working one shows Connected.

💡 Two config files, two products: VS Code has its own MCP support with a file at .vscode/mcp.json. That file belongs to VS Code's built-in chat and uses a different format. Claude Code keeps its own configuration, so a server declared only in .vscode/mcp.json will not appear in Claude Code's /mcp list.

You may also hear about a server named ide. The extension runs it automatically to open diffs and read your selection, and it stays hidden from /mcp because there is nothing to configure.

Choose the Right Scope

The scope decides who sees the server and where it is stored. Pick it with --scope (short form -s).

Local, Project, or User

claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Copy Prompt

My rule of thumb: use local for experiments and anything holding a personal token, project for tools the whole team needs, and user for the handful of servers you want in every repository.

Share Servers With .mcp.json

A project-scope server lives in a .mcp.json file at the repo root, which you commit. It supports environment variable expansion, so the file never has to contain a secret:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Copy Prompt

${VAR} expands to the environment variable, and ${VAR:-default} falls back to a default when the variable is unset. Each teammate sets API_TOKEN on their own machine.

Teammates see an approval prompt before Claude Code uses a server from .mcp.json in an interactive session. To reset those choices, run claude mcp reset-project-choices. Non-interactive runs such as claude -p load project servers without prompting, which is worth remembering for CI jobs.

Handle Tokens and OAuth Safely

A server can authenticate three ways, and the right one depends on what the vendor supports.

For OAuth, open /mcp, select the server, and follow the browser login. From the command line, claude mcp login <name> does the same, and claude mcp login <name> --no-browser prints what you need on an SSH or headless machine. To clear saved credentials, run claude mcp logout <name>. A few servers need pre-registered credentials, which you pass with --client-id, --client-secret, and --callback-port when adding the server.

Two habits prevent most leaks. First, never commit a literal token. Put ${VAR} in .mcp.json and keep the real value in your shell environment. Second, keep servers that carry a personal token at the local or user scope, where the file stays out of the repository.

Connect PicassoIA as a Real Example

A concrete server makes all this less abstract. PicassoIA offers an MCP connection that lets an AI client create images and videos from a chat. It exposes four models: PicassoIA Image for text to image, PicassoIA Image Editor Pro for edits, PicassoIA Video for clips from text or an image, and Seedance 2.5 Lite for video with audio.

The tools are built around asynchronous jobs. A generate call returns a prediction ID as soon as a GPU accepts the job, and the client then polls get_generation until the status is succeeded or failed. Other tools include edit_image, list_generations, cancel_generation, list_models, and get_account. An account can run 5 predictions at once, and that limit is shared across all its MCP connections. MCP access depends on your plan, so confirm it on the PicassoIA pricing page before you rely on it.

Add It and Test It

1. Sign in to PicassoIA and open your MCP connections page. It shows the server URL for your account.
2. Run the command with that URL:

claude mcp add --transport http picassoia YOUR_PICASSOIA_MCP_URL

Copy Prompt

3. Open Claude Code, type /mcp, and select picassoia. If it asks you to sign in, follow the browser flow. If your connections page gave you a token instead, add --header "Authorization: Bearer YOUR_TOKEN" to the command.
4. Confirm the server shows Connected.

I am not printing a URL here on purpose. PicassoIA shows yours after you sign in, so use the exact one from your account rather than a copy from an article.

A Prompt Worth Trying

Because you named the server picassoia, its tools appear as mcp__picassoia__<tool>. Try something that uses two of them:

Use PicassoIA to generate a 16:9 photograph of a wooden desk at sunrise with a laptop and a coffee cup, then animate it into a short video.

Claude Code asks for permission before it calls a new tool, so expect a prompt on the first run. If you also want to compare how different language models read the same instruction, PicassoIA lists Claude Sonnet 5 and Claude Fable 5 among its large language models.

Fix a Server That Won't Connect

Most failures come from a short list of causes. Start with /mcp to read the status, then use claude mcp get <name> to see exactly what was saved.

Common Failures and Fixes

Timeouts and Big Outputs

Three settings handle slow servers. MCP_TIMEOUT sets the server startup timeout in milliseconds, which helps when the first npx download is slow:

export MCP_TIMEOUT=10000

Copy Prompt

On Windows PowerShell the same thing is $env:MCP_TIMEOUT = "10000". MAX_MCP_OUTPUT_TOKENS raises the cap on tool output. The default is 25,000 tokens, and Claude Code warns you at 10,000. Finally, a per-server timeout in .mcp.json (also in milliseconds) gives slow tools more room, which suits image and video generators:

{
  "mcpServers": {
    "slow-tool": {
      "type": "http",
      "url": "https://example.com/mcp",
      "timeout": 600000
    }
  }
}

Copy Prompt

Try It With Your Own Images

You now have the whole loop: pick a transport, add the server, choose a scope, sign in safely, and fix it when it misbehaves. The quickest way to feel the payoff is to connect a server that produces something you can see.

Sign in to PicassoIA, connect it to Claude Code, and ask for a photograph. Generate it with PicassoIA Image, refine it with PicassoIA Image Editor Pro, then bring it to life with PicassoIA Video or Seedance 2.5 Lite. Browse every model at picassoia.com/en/all-models, and start with one prompt of your own.