Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getgaal.com/llms.txt

Use this file to discover all available pages before exploring further.

This page is a working reference for the mcps: block. For the conceptual model, see Concepts → MCP servers. Every recipe below uses the registry-resolved form: list the target agents and the scope, and let gaal find the right JSON file. The legacy target: field is deprecated — see the migration recipe at the bottom.

​
Filesystem server (inline stdio)

mcps:
  - name: filesystem
    agents: [claude-code]
    global: true
    inline:
      command: uvx
      args:
        - mcp-server-filesystem
        - ~/projects
Becomes (in ~/.claude.json): 
{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["mcp-server-filesystem", "~/projects"]
    }
  }
}

​
Server with environment variables

mcps:
  - name: github
    agents: [claude-code]
    global: true
    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 resolves environment variables when it launches the server. See Environment & secrets.

​
Install one server in many agents

List the agents in a single entry. gaal fans the entry out to each one’s MCP config file. 
mcps:
  - name: filesystem
    agents: [claude-code, cursor, codex, windsurf]
    global: true
    inline:
      command: uvx
      args: [mcp-server-filesystem, ~/projects]
Or use the wildcard to install in every agent registered on this machine that exposes a global MCP config: 
mcps:
  - name: git
    agents: ["*"]
    global: true
    inline:
      command: uvx
      args: [mcp-server-git, --repository, ~/projects/gaal]

​
Native HTTP server

For agents that accept remote MCP entries, write the endpoint directly: 
mcps:
  - name: linear
    agents: [claude-code, cursor]
    global: true
    inline:
      type: http
      url: https://mcp.linear.app/mcp

​
HTTP server with headers

mcps:
  - name: memory
    agents: [claude-code, codex]
    global: true
    inline:
      type: http
      url: https://memory.example.com/mcp
      headers:
        X-Team: platform
        Authorization:
          env: MEMORY_TOKEN
Scalar headers are written as static values. Use env: for secrets; gaal writes the environment variable name for target formats that support env-backed headers.

​
SSE (HTTP+SSE) server

For servers still on the older HTTP+SSE transport: 
mcps:
  - name: sentry
    agents: [claude-code]
    global: true
    inline:
      type: sse
      url: https://mcp.sentry.dev/sse
If your target agent does not support native remote MCP servers yet, keep using a stdio bridge such as mcp-remote under command and args.

​
Pull config from a remote URL

When the upstream maintainer publishes the canonical JSON, point at it instead of duplicating the spec. 
mcps:
  - name: github
    source: https://raw.githubusercontent.com/github/mcp-servers/main/config.json
    agents: [claude-code, github-copilot]
    global: true
The remote file must contain an mcpServers object. gaal downloads it and merges the matching entry into each target. source: and inline: are mutually exclusive.

​
VS Code (Copilot, Cline, Roo)

VS Code-family agents share ~/.vscode/settings.json as their MCP config. Just list them like any other agent — gaal resolves all three to the same file and writes once. 
mcps:
  - name: sequential-thinking
    agents: [github-copilot]
    global: true
    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

The destination file is resolved from the agent registry. For reference:
AgentResolved target (global: true)
Claude Code~/.claude.json
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json
Cursor~/.cursor/mcp.json
Codex~/.codex/config.toml
Windsurf~/.codeium/windsurf/mcp_settings.json
Continue~/.continue/config.json
VS Code (Copilot, Cline, Roo)~/.vscode/settings.json
Goose~/.config/goose/config.yaml
Gemini CLI~/.gemini/settings.json
Warp~/.warp/launch_configurations/mcp.json
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.

​
Migrating from target:

Earlier versions required an explicit target: path on every entry. That field still works but logs a deprecation warning. Replace each entry with agents: + global:: 
# Before
mcps:
  - name: filesystem
    target: ~/.claude.json
    inline:
      command: uvx
      args: [mcp-server-filesystem, ~/projects]

# After
mcps:
  - name: filesystem
    agents: [claude-code]
    global: true
    inline:
      command: uvx
      args: [mcp-server-filesystem, ~/projects]

Concepts: MCP servers

Environment & secrets

Pruning

Schema: mcps