skip to content

In Claude Code, how do you add a local stdio MCP server that needs an API key, and why does the `--` separator matter?

level: juniorimportance: must knowfreq 22%

answer

  1. a process Claude Code starts itself
  2. stdio is the default transport
  3. --env before the name, not right before it
  4. everything after -- goes to the server
  5. claude mcp get shows the saved command

basics

~20 s

Run claude mcp add with --env KEY=value, the server name, then -- and the launch command. Everything after -- reaches the server untouched; without it, Claude Code parses the server's flags, such as -y or --port, as its own.

solid answer

~50 s

A stdio server is a program Claude Code launches as a subprocess, so you register the command that starts it: `claude mcp add --env DB_URL=... --transport stdio orders-db -- npx -y @example/db-mcp-server`. `stdio` is the default transport, so `--transport stdio` is optional. The `--` separates Claude's own options (`--transport`, `--env`, `--scope`) from the server's command line; everything after it is passed through untouched, while without it Claude Code tries to read flags like `-y` or `--port 8080` as its own. One more trap: `--env` takes several `KEY=value` pairs, so if the server name comes straight after it the CLI reads the name as another pair and rejects it — put another option between them. The entry lands at local scope by default, and `Added ...` only means it was saved: check it with `claude mcp list` or `claude mcp get`.

code

bash · 7 lines
bash
# stdio is the default transport; --transport stdio also keeps --env away from the name
claude mcp add --env DB_URL=postgres://localhost:5432/orders --transport stdio \
  orders-db -- npx -y @example/db-mcp-server

# 'Added ...' means saved, not running: check the command and the connection
claude mcp get orders-db
claude mcp list

go deeper

for a junior

Recall the shape: claude mcp add, options, the name, then -- and the command that starts the server. Know that stdio is the default transport.

for a middle

Explain why the separator exists: Claude Code's parser would otherwise claim the server's own flags. Mention the --env ordering trap and that local scope is where the entry lands.

for a senior

Show the debugging loop: claude mcp get to compare the stored command, running that command by hand, MCP_TIMEOUT for slow first starts, and keeping credentials in --env at local scope.

for a principal

Frame stdio servers as code you run with your own privileges: decide which launch commands a team standardises on and how credentials reach them without landing in shared files.

## What a stdio server is An **MCP server** gives Claude Code extra tools, resources and prompts. A **stdio server** is one that Claude Code starts itself, as a child process on your machine, and talks to over that process's standard input and output. That makes it the natural choice for anything that needs local access: a database socket, your filesystem, a browser, an internal script. Because Claude Code launches it, what you register is not a URL but **the command that starts the server**. Claude Code also sets `CLAUDE_PROJECT_DIR` in the spawned server's environment, pointing at the project root, so a server can resolve project-relative paths without depending on the working directory it happens to start in. ## The command and its parts The general shape is `claude mcp add [options] <name> -- <command> [args...]`: 1. `claude mcp add` — the subcommand that writes a server entry to configuration. 2. **Options for Claude Code**: `--transport stdio` (optional, because `stdio` is the default transport), `--env KEY=value` for environment variables the server needs, `--scope local|project|user` for where the entry is stored. 3. **The server name** — only letters, numbers, hyphens and underscores. 4. `--` — the separator. 5. **The server's own command line**, passed untouched: `npx -y @example/db-mcp-server`, `python server.py --port 8080`, a binary path. ## Why `--` matters Without the separator, Claude Code's argument parser sees every flag on the line as a candidate option of `claude mcp add`. A server command such as `python server.py --port 8080` or `npx -y some-package` carries flags of its own, and Claude Code would try to interpret `--port` or `-y` itself. With `--`, the parser stops at the separator and stores everything after it as the server's command and arguments. | You type | Claude Code runs | |---|---| | `claude mcp add --transport stdio myserver -- npx server` | `npx server` | | `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` | `python server.py --port 8080`, with `KEY=value` in its environment | The same rule applies when you translate setup instructions written for another MCP client: a launch command such as `npx -y @example/mcp-server` goes after `--`, and any environment variables the instructions mention go in `--env`, after the server name and before `--`. ## The `--env` ordering trap `--env` accepts **multiple** `KEY=value` pairs. If you write `claude mcp add --env API_KEY=abc airtable -- npx -y airtable-mcp-server`, the CLI reads `airtable` as another pair and rejects it. The fix is ordering, not a different flag: place at least one other option, such as `--transport stdio`, between `--env` and the name, or put `--env` after the name and before `--`. ## Where the entry goes and how to check it - With no `--scope`, the entry is written at **local scope**: `~/.claude.json`, under the current project's path, private to you. That is the right home for a server whose `--env` value is a credential, because nothing lands in the repository. - The `Added stdio MCP server ...` line means the configuration was **saved**, not that the command runs. - `claude mcp list` shows a health status per server (`✔ Connected`, `✘ Failed to connect`); a first check can fail while `npx` is still downloading the package. - `claude mcp get <name>` shows the stored command. If it differs from what you typed, the usual cause is a missing `--`: remove the server with `claude mcp remove <name>` and add it again. - A slow first start can exceed the 30-second startup timeout; raise it with `MCP_TIMEOUT` (milliseconds). - Inside a session, `/mcp` shows the same status and lets you reconnect. ## Common mistakes - Leaving out `--` and wondering why `-y` or `--port` vanished or caused an error. - Putting the name immediately after an `--env` pair. - Passing a value the server reads from its environment as an argument after `--`, instead of through `--env`. - Adding the server from a different directory and then not finding it: local-scope servers belong to the project (the repository root, or the exact directory outside a repository) where you added them. - Writing the server into a shared file when it carries a personal credential; local scope keeps it out of version control.

  • `claude mcp get orders-db` shows a command without the `-y` you typed. What happened and how do you fix it?
    The `--` separator was missing, so Claude Code parsed `-y` as one of its own options instead of storing it with the server's command. A server's scope and command are fixed once added, so run `claude mcp remove orders-db` and add it again with `--` before the launch command.
  • The first `claude mcp list` after adding an `npx`-launched server shows `✘ Failed to connect`. What do you check before debugging the server?
    Whether `npx` was still downloading the package: the first start can be slow, so wait and run `claude mcp list` again. If it persists, run the stored command yourself in a terminal to see its error, and if startup is merely slow, raise `MCP_TIMEOUT` above its 30-second default.

  • Claude Code passes every flag after the server name to the server automatically
  • A stdio server always needs --transport stdio spelled out
  • The Added line proves the server started and connected
  • --env can sit directly before the server name without problems
  • A local-scope server appears in every project you open