#### Supported syntax #### Expansion locations #### Example with variable expansion #### Unset variables without a default #### How references appear in `/mcp` and CLI output
The whole hunk
from line 135, old and new numbered
/
lines
from line 135
135135
136136 Without `--`, Claude Code would try to parse the server's flags, like `--port` above, as its own options.
137137
138 `--env` accepts multiple `KEY=value` pairs. If the server name comes directly after `--env`, the CLI reads the name as another pair and rejects it, so place at least one other option between `--env` and the server name, as in the examples above.
138 `--env` accepts multiple `KEY=value` pairs. If the server name comes directly after `--env`, the CLI reads the name as another pair and rejects it, so place at least one other option, such as `--transport stdio`, between `--env` and the server name.
139139</Note>
140140
141141### Option 4: Add a remote WebSocket server
from line 153
153153
154154### Add a server from setup instructions written for another client
155155
156MCP servers aren't specific to Claude Code, so a server's setup instructions may be written for Claude Desktop, Cursor, or another MCP client and give no `claude mcp add` command. To add the server anyway, look in those instructions for one of these three things:
156MCP servers aren't specific to Claude Code, so a server's setup instructions may be written for Claude Desktop, Cursor, or another MCP client and give no `claude mcp add` command. To add the server anyway, look in those instructions for a URL, a launch command, or a JSON block:
157157
158158* **A URL** such as `https://mcp.example.com/mcp`: the server is remote.
159159* **A launch command** such as `npx -y @example/mcp-server`: the server runs on your machine.
from line 605
605605
606606Claude Code supports environment variable expansion in `.mcp.json` files, allowing teams to share configurations while maintaining flexibility for machine-specific paths and sensitive values like API keys.
607607
608**Supported syntax:**
608#### Supported syntax
609609
610610* `${VAR}`: expands to the value of environment variable `VAR`
611611* `${VAR:-default}`: expands to `VAR` if set, otherwise uses `default`
612612
613**Expansion locations:**
613#### Expansion locations
614
614615Environment variables can be expanded in:
615616
616617* `command`: the server executable path
from line 620
619620* `url`: for HTTP server types
620621* `headers`: for HTTP server authentication
621622
622**Example with variable expansion:**
623#### Example with variable expansion
623624
624625```json theme={null}
625626{
from line 636
635636}
636637```
637638
639#### Unset variables without a default
640
638641If a referenced environment variable isn't set and has no default value, the config still loads: Claude Code reports a missing-variable warning for that server in `claude mcp list` output and uses the unexpanded `${VAR}` text as-is. Set the variable or add a `:-default` fallback so the server starts with the value you intend. In a remote server's `url` and `headers`, some credential variables [read as empty](#credential-variables-that-read-as-empty) instead, with no warning.
639642
640643#### Credential variables that read as empty
from line 656
653656
654657When a remote server's `url` or `headers` references a covered variable you have set, Claude Code names it in a debug-log line. To read the line, run `claude --debug-file /tmp/claude-debug.log` and search that file for `never expanded toward a remote server`.
655658
659#### How references appear in `/mcp` and CLI output
660
661For a server in the local, project, or user [scope](#mcp-installation-scopes), the following surfaces show a `${VAR}` reference by name rather than as its resolved value:
662
663* The URL or command line in a server's `/mcp` detail view
664* `claude mcp list` and `claude mcp get` output
665
666The `/mcp` detail view shows references this way in Claude Code v2.1.268 or later.
667
668For a server your organization provides through the `managedMcpServers` setting, these surfaces show [the URL's host only](/docs/en/managed-mcp#what-users-can-see-and-change).
669
670To check what `claude mcp list`, `claude mcp get`, and `/mcp` show when a connection fails, see [Server status detail](#server-status-detail).
671
656672## Practical examples
657673
658674### Example: Connect to GitHub for code reviews
from line 739
723739A custom server that returns a `WWW-Authenticate` header pointing to its authorization server gets the same automatic discovery as any other remote server.
724740
725741Claude Code also shows a startup notice when one or more configured servers need authentication, so you don't have to open `/mcp` to discover which servers need sign-in. The notice requires Claude Code v2.1.193 or later. It counts only servers you can sign in to from Claude Code. Before v2.1.218, it also counted [claude.ai connectors](#use-mcp-servers-from-claude-ai) that weren't connected in claude.ai, which you can connect only from claude.ai settings.
742
743The notice announces each server once and leaves it out of the count at later launches until that server has connected and needs sign-in again. `/mcp` still lists every server that needs sign-in.
726744
727745In non-interactive mode there's no `/mcp` panel, so Claude Code can't run the OAuth flow for you. As of v2.1.196, when a configured server needs authentication during a `claude -p` or Agent SDK run with [tool search](#scale-with-mcp-tool-search) enabled, which is the default, Claude Code tells Claude that the server's tools are unavailable until you authorize it. Claude can then name the server that needs sign-in instead of responding as if the server weren't configured. Complete the sign-in from an interactive session with `/mcp` or `claude mcp login <name>`.
728746