Skip to main content

MCP Configuration

The Atmos MCP server exposes Atmos AI tools via the Model Context Protocol. It must be explicitly enabled separately from AI features, since it opens a communication channel that external clients can connect to.

Experimental

Quick Start​

atmos.yaml

mcp:
  enabled: true       # Required — MCP is off by default
ai:
  enabled: true
  tools:
    enabled: true
Opt-In Only

The MCP server is disabled by default and must be explicitly enabled with mcp.enabled: true. Enabling AI features (ai.enabled: true) does not enable MCP. The default stdio transport runs as a local subprocess with no network exposure.

Configuration Reference​

Minimal Setup​

Three settings are required to start the MCP server:

atmos.yaml

mcp:
  enabled: true       # Enable the MCP server
ai:
  enabled: true       # Enable AI features
  tools:
    enabled: true     # Enable tool execution

Full Configuration​

For more control, you can specify providers, tool restrictions, and confirmation behavior:

atmos.yaml

mcp:
  enabled: true
ai:
  enabled: true
  default_provider: "anthropic"
  providers:
    anthropic:
      model: "claude-sonnet-4-6"
      api_key: !env "ANTHROPIC_API_KEY"

  tools:
    enabled: true
    require_confirmation: true
    allowed_tools:
      - atmos_describe_component
      - atmos_list_stacks
      - atmos_validate_stacks
    blocked_tools:
      - execute_bash_command

MCP Settings​

mcp.enabled
Enable the MCP server (default: false). Must be explicitly set to true before atmos mcp start will work.
note

The MCP server itself does not require an API key. The tools it exposes use your configured AI provider settings. Provider configuration is only needed if you also use atmos ai chat or atmos ai ask.

Tool Settings​

The MCP server exposes all tools configured in ai.tools. See AI Tools Configuration for the full reference of tool settings including:

tools.enabled
Enable or disable tool execution (default: false). Must be true for the MCP server to expose any tools.
tools.require_confirmation
When accessed via MCP, tools execute without interactive confirmation prompts. Use allowed_tools and blocked_tools to control access.
tools.allowed_tools
Tools available for execution. Supports wildcards like atmos_describe_* (default: [] = all tools).
tools.blocked_tools
Tools completely blocked from execution (default: []).

Available Tools​

When connected, the MCP server exposes all enabled Atmos AI tools:

atmos_describe_component
Get detailed component configuration for a stack.
atmos_list_stacks
List and filter stacks.
atmos_validate_stacks
Validate stack configurations.
describe_affected
Show components affected by git changes.
read_component_file
Read a component source file.
read_stack_file
Read a stack configuration file.
write_component_file
Modify a component file.
write_stack_file
Modify a stack file.

All tools respect your configured permission settings.

Guides​

  • MCP Server Integration — Client setup guides for Claude Desktop, VS Code, Cursor, and other MCP clients
  • AI Tools — Full tool configuration reference