The Atlas `atlas mcp add` command rejects your arguments because it validates the flag combination before writing config: a server name is mandatory, exactly one of --url or a trailing command must be given, and --env and --header are transport-specific. Fix it by passing the server name as the positional argument, using `--url https://...` with `--header KEY=VALUE` for a remote server, or a command after `--` with `--env KEY=VALUE` for a local server.
Why atlas mcp add rejects your arguments
The Atlas `atlas mcp add` command validates the flag combination before writing anything to config. A server name is mandatory, exactly one of --url or a trailing command must be given, and --env and --header are transport-specific, so 4 distinct error messages can come out of a single malformed invocation.
Validating up front is deliberate in Atlas. A half-formed mcp entry written to config would fail later, at connect time, with a much vaguer error, so the CLI refuses the arguments instead. The four messages map directly onto the four rules: "A server name is required for non-interactive MCP configuration" when the positional is missing, "Provide either --url <url> or a command after --" when the transport is ambiguous or absent, "--env is only valid for local MCP servers" and "--header is only valid for remote MCP servers" when the flags contradict the transport you chose.
How to add a remote MCP server in Atlas
Add a remote MCP server in Atlas by passing 2 things: a server name as the positional argument and `--url https://...` for the endpoint. Pass secrets with `--header KEY=VALUE`. Do not pass `--env` on a remote server: `atlas mcp add` rejects it with "--env is only valid for local MCP servers".
A remote server in Atlas is defined by its `url`, and its credentials travel as HTTP headers, which is why `--header KEY=VALUE` is the remote-only flag. A bearer token, an API key header, or a tenant header all go through it, and you can pass the flag more than once. The mistake people make is reaching for `--env` out of habit from local server setups. Environment variables mean nothing to a remote endpoint reached over HTTP, so Atlas rejects the flag rather than writing an entry that would silently ignore it.
How to add a local stdio MCP server in Atlas
Add a local stdio MCP server in Atlas by passing 2 things: a server name as the positional argument and the command after `--`. Pass variables with `--env KEY=VALUE`. Do not pass `--header` on a local server: `atlas mcp add` rejects it with "--header is only valid for remote MCP servers".
A local server in Atlas is a child process launched from a command array and speaking stdio, so it is configured by a command rather than a url. Everything after the `--` separator becomes that command array, which is what keeps the server's own flags from being parsed by the Atlas CLI. Credentials for a local server travel as environment variables, hence `--env KEY=VALUE` as the local-only flag. There are no HTTP headers on a stdio pipe, which is exactly why Atlas rejects `--header` here instead of accepting a value that could never be used.
How to format env and header pairs for atlas mcp add
Write every env and header pair for `atlas mcp add` as KEY=VALUE, so Atlas can split each entry into its 2 halves. A missing `=` throws `Invalid <kind>: <entry>. Expected KEY=VALUE`, and Atlas refuses the whole command rather than writing a partially parsed mcp entry into your config.
The KEY=VALUE shape applies identically to `--env KEY=VALUE` on a local Atlas MCP server and `--header KEY=VALUE` on a remote one. The usual failure is a space around the equals sign, which the shell turns into separate arguments, or a value containing a space that was never quoted. Quote the whole pair when the value has spaces. The error message names both the kind and the offending entry, so it tells you precisely which pair to fix rather than making you audit the entire command line.
How to verify the MCP server was added in Atlas
Verify the entry by running `atlas mcp` once `atlas mcp add` exits without any of its 4 argument errors. The new server appears in the listing with a status row. A remote server added with a bad url shows Invalid MCP URL, since `atlas mcp add <name> --url <url>` validates the URL and throws `Invalid URL: ...`.
A successful `atlas mcp add` in Atlas means the arguments passed validation and the mcp entry was written, not that the server works. Those are two different claims. `atlas mcp` gives you the second one: the status row shows whether the server actually connected, or landed at failed, needs_auth, needs_client_registration, or disabled. Once the server reaches connected, Atlas exposes its Model Context Protocol tools to the agent, and every one of those tool calls is permission-gated against allow, ask, and deny rules before it runs.
How to fix it
- 01Pass a server name as the positional argument.
- 02For a remote server use `--url https://...` and pass secrets with `--header KEY=VALUE`.
- 03For a local server put the command after `--` and pass variables with `--env KEY=VALUE`.
- 04Write env and header pairs as KEY=VALUE; a missing `=` throws `Invalid <kind>: <entry>. Expected KEY=VALUE`.
Frequently asked questions
- Why does atlas mcp add say a server name is required?
- Non-interactive `atlas mcp add` requires the server name as the positional argument. The command validates the flag combination before writing config, and a missing name throws "A server name is required for non-interactive MCP configuration".
- How do I add a remote MCP server with atlas mcp add?
- Pass the server name, then `--url https://...`. Pass any secrets with `--header KEY=VALUE`. Do not pass `--env`, which is only valid for local MCP servers.
- How do I add a local MCP server with atlas mcp add?
- Pass the server name, then put the command after `--`. Pass variables with `--env KEY=VALUE`. Do not pass `--header`, which is only valid for remote MCP servers.
- What does "Provide either --url <url> or a command after --" mean?
- The Atlas mcp add command requires exactly one transport. Give `--url <url>` for a remote server or a command after `--` for a local one. Giving neither, or both, fails validation before anything is written to config.
- Why does atlas mcp add say --env is only valid for local MCP servers?
- Because a remote MCP server is reached over HTTP and has no process environment. Credentials for a remote server travel as headers, so use `--header KEY=VALUE` instead.
- What is the correct format for --env and --header in Atlas?
- KEY=VALUE. A missing `=` throws `Invalid <kind>: <entry>. Expected KEY=VALUE`. Quote the whole pair when the value contains spaces, and pass the flag more than once for multiple pairs.
- How do I confirm the MCP server I added actually works?
- Run `atlas mcp` and read the status row. A successful `atlas mcp add` only means the arguments validated and the entry was written. The status row tells you whether the server connected or landed at failed, needs_auth, needs_client_registration, or disabled.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with GPT-OSS 120B (hosted): picking the right host in 2026
Run Atlas on GPT-OSS 120B (hosted) in 2026. Identical Apache weights cost $0.037 per Mtok on DeepInfra and $0.35 on Cerebras, a 9.5x input spread. Full host guide.
Atlas with Ministral 8B: The Cheap Slot That Can Still Call Tools in 2026
Ministral 8B runs 128,000 tokens at $0.10 / 1M input tokens and $0.10 / 1M output tokens, symmetric. The Atlas small_model upgrade when subagents misfire on schemas.
Atlas with Gemma 3 4B Instruct: A Triage Model, Not a Builder (2026)
Gemma 3 4B Instruct in Atlas via Amazon Bedrock: $0.04 per Mtok input, $0.08 per Mtok output, a 128K context, and a 4,096 token output cap that rules out diffs.
Atlas with Gemini 3.5 Flash: The May 2026 Latency Tier That Keeps 1M Context
Gemini 3.5 Flash in Atlas: the May 2026 release keeps the full 1,048,576 token window at $1.50 / $9 per Mtok, with reasoning and tool calling enabled.
Atlas with GPT-5 Codex: The First Codex Model of the GPT-5 Family in 2026
GPT-5 Codex in Atlas: September 2025 brought coding post training at zero premium, 400K context, 128K output, and $1.25 per Mtok input with $10 per Mtok output.
Atlas for Electron: Terminal-Native AI Coding for Main, Preload, and Renderer in 2026
Atlas is a terminal-native AI coding agent for Electron in 2026, where the main and renderer split, contextIsolation, and preload bridges are the security model.
Atlas for Rust in 2026
Adopt Atlas, the terminal-native AI coding agent, for Rust development in 2026. Tackle borrow checker errors and clippy lints with Atlas's secure, approval-gated assistance.
Atlas for Fastify in 2026
Atlas is a terminal-native AI coding agent for Fastify in 2026. It reads plugin encapsulation and JSON schemas, then runs node --test behind a permission prompt.