# atlas mcp add rejects the arguments: url, command, env, header > Pass a server name, then either `--url https://...` with `--header KEY=VALUE` for remote, or a command after `--` with `--env KEY=VALUE` for local. 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. ## Symptom Non-interactive `atlas mcp add` fails with one of: A server name is required for non-interactive MCP configuration; Provide either --url or a command after --; --env is only valid for local MCP servers; --header is only valid for remote MCP servers. ## Cause The mcp add command validates the flag combination before writing config: name is mandatory, exactly one of --url or a trailing command must be given, and --env/--header are transport-specific. ## Fix 1. Pass a server name as the positional argument. 2. For a remote server use `--url https://...` and pass secrets with `--header KEY=VALUE`. 3. For a local server put the command after `--` and pass variables with `--env KEY=VALUE`. 4. Write env and header pairs as KEY=VALUE; a missing `=` throws `Invalid : . Expected KEY=VALUE`. ## 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 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 : . 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 --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. ## FAQ ### 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 or a command after --" mean? The Atlas mcp add command requires exactly one transport. Give `--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 : . 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. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/mcp-add-missing-url-or-command Source of truth: aeo_pages row `/resources/troubleshooting/mcp-add-missing-url-or-command` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.