Skip to main content
This page is a working reference for the mcps: block. For the conceptual model, see Concepts → MCP servers.

​
Filesystem server (inline)

mcps:
  - name: filesystem
    target: ~/.config/claude/claude_desktop_config.json
    inline:
      command: uvx
      args:
        - mcp-server-filesystem
        - ~/projects
Becomes: 
{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["mcp-server-filesystem", "~/projects"]
    }
  }
}

​
Server with environment variables

mcps:
  - name: github
    target: ~/.config/claude/claude_desktop_config.json
    inline:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
${GITHUB_TOKEN} is not expanded by gaal, the literal string ${GITHUB_TOKEN} is written into the JSON. The agent process is responsible for resolving environment variables when it launches the server. See Environment & secrets.

​
Same server, multiple agents

Each entry has exactly one target. Repeat the entry per target file: 
mcps:
  - name: filesystem
    target: ~/.config/claude/claude_desktop_config.json
    inline:
      command: uvx
      args: [mcp-server-filesystem, ~/projects]

  - name: filesystem
    target: ~/.cursor/mcp.json
    inline:
      command: uvx
      args: [mcp-server-filesystem, ~/projects]

  - name: filesystem
    target: ~/.codex/mcp.json
    inline:
      command: uvx
      args: [mcp-server-filesystem, ~/projects]

​
Pull config from a remote URL

mcps:
  - name: github
    source: https://raw.githubusercontent.com/github/mcp-servers/main/config.json
    target: ~/.config/claude/claude_desktop_config.json
The remote file must contain an mcpServers object. gaal downloads it and merges the named entry into the target. source: and inline: are mutually exclusive.

​
VS Code (Copilot, Cline, Roo)

VS Code MCP entries live under the workspace or user settings.json: 
mcps:
  - name: sequential-thinking
    target: ~/.vscode/settings.json
    inline:
      command: npx
      args:
        - -y
        - "@modelcontextprotocol/server-sequential-thinking"
gaal upserts under the mcpServers key while leaving every other VS Code setting in place.

​
Common targets

AgentCanonical target
Claude Desktop~/.config/claude/claude_desktop_config.json
Cursor~/.cursor/mcp.json
Codex~/.codex/mcp.json
Windsurf~/.codeium/windsurf/mcp_settings.json
Continue~/.continue/config.json
VS Code (Copilot, Cline, Roo)~/.vscode/settings.json
Goose~/.config/goose/config.yaml
See Agent integrations for the full list.

​
Removing an entry

Removing an mcps[] entry from gaal.yaml does not remove it from the target file unless you pass --prune. Without --prune, gaal stops managing it but leaves the JSON intact.

Concepts: MCP servers

Environment & secrets

Pruning

Schema: mcps