Configure MCP servers

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:

Agent	Resolved 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]

Get started

Concepts

Configure

Workflows

Agent integrations

Troubleshooting

Configure MCP servers

Filesystem server (inline stdio)

Server with environment variables

Install one server in many agents

Native HTTP server

HTTP server with headers

SSE (HTTP+SSE) server

Pull config from a remote URL

VS Code (Copilot, Cline, Roo)

Common targets

Removing an entry

Migrating from `target:`

Concepts: MCP servers

Environment & secrets

Pruning

Schema: mcps

​Filesystem server (inline stdio)

​Server with environment variables

​Install one server in many agents

​Native HTTP server

​HTTP server with headers

​SSE (HTTP+SSE) server

​Pull config from a remote URL

​VS Code (Copilot, Cline, Roo)

​Common targets

​Removing an entry

​Migrating from target:

​Related

Concepts: MCP servers

Environment & secrets

Pruning

Schema: mcps

Filesystem server (inline stdio)

Server with environment variables

Install one server in many agents

Native HTTP server

HTTP server with headers

SSE (HTTP+SSE) server

Pull config from a remote URL

VS Code (Copilot, Cline, Roo)

Common targets

Removing an entry

Migrating from `target:`

Related