Skip to main content

atmos mcp add

Use this command to add an MCP server to mcp.servers in atmos.yaml without hand-editing YAML.

Experimental
atmos mcp add --help

Description​

The atmos mcp add command writes a new entry under mcp.servers in atmos.yaml. The target can be:

  • A built-in preset — self (Atmos's own MCP server) or atmos-pro (the Atmos Pro MCP server).
  • An http(s):// URL — added as a remote HTTP server.
  • A stdio command — added as a local subprocess server, optionally with arguments (e.g. "npx -y @org/mcp-server --flag value").

Running atmos mcp add with no target defaults to atmos mcp add self.

Only atmos.yaml is written — add never touches an AI client's config file. Use --install to also push the new server into detected AI clients in the same step, or run atmos mcp install separately.

If the target resolves to the self preset and mcp.enabled is false in atmos.yaml, add prompts (when running interactively) to enable it — the self entry won't work at runtime until Atmos can run as an MCP server itself. Non-interactively, it errors with the exact atmos config set command to run instead.

Usage​

atmos mcp add [preset-name|url|command] [flags]
preset-name|url|command
Optional. A built-in preset name (self, atmos-pro), an http(s):// URL, or a stdio command. Defaults to self when omitted.
--name, -n
Server name. Auto-inferred from the URL or command if not provided (presets use their own default name, e.g. self → atmos).
--transport, -t
Transport for a URL target. Only http is supported today; other values (e.g. sse) are rejected.
--env
Environment variable for a stdio server, KEY=VALUE (repeatable).
--header, -H
HTTP header for a remote server, "Key: Value" (repeatable).
--description
Human-readable description shown in atmos mcp list/status.
--identity
Atmos Auth identity (from the auth section) for credential injection.
--timeout
Connection timeout, as a Go duration string (e.g. 30s).
--auto-start
Start the server automatically when Atmos starts.
--install
Also install into detected AI clients immediately after adding.
--yes, -y
Skip confirmation prompts.
--force
Overwrite an existing entry without prompting.

Examples​

# Add Atmos's own MCP server (also the default target with no argument).
atmos mcp add self

# Add the Atmos Pro MCP server.
atmos mcp add atmos-pro

# Add a remote HTTP server with an auth header.
atmos mcp add https://mcp.example.com/mcp --header "Authorization: Bearer ${TOKEN}"

# Add a local stdio server and immediately install it into detected AI clients.
atmos mcp add "uvx awslabs.aws-documentation-mcp-server@latest" --install

# Add a server with an explicit name, description, and Atmos Auth identity.
atmos mcp add uvx --name aws-docs --description "AWS Documentation" --identity readonly