> ## 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.

# Configure MCP servers

> Cookbook for the mcps: block of gaal.yaml.

This page is a working reference for the `mcps:` block. For the conceptual model, see [Concepts → MCP servers](/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](#migrating-from-target) at the bottom.

## Filesystem server (inline stdio)

```yaml theme={"theme":"nord"}
mcps:
  - name: filesystem
    agents: [claude-code]
    global: true
    inline:
      command: uvx
      args:
        - mcp-server-filesystem
        - ~/projects
```

Becomes (in `~/.claude.json`):

```json theme={"theme":"nord"}
{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["mcp-server-filesystem", "~/projects"]
    }
  }
}
```

## Server with environment variables

```yaml theme={"theme":"nord"}
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](/configure/environment-and-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.

```yaml theme={"theme":"nord"}
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:

```yaml theme={"theme":"nord"}
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:

```yaml theme={"theme":"nord"}
mcps:
  - name: linear
    agents: [claude-code, cursor]
    global: true
    inline:
      type: http
      url: https://mcp.linear.app/mcp
```

## HTTP server with headers

```yaml theme={"theme":"nord"}
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:

```yaml theme={"theme":"nord"}
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.

```yaml theme={"theme":"nord"}
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.

```yaml theme={"theme":"nord"}
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](/agents/overview) 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:`:

```yaml theme={"theme":"nord"}
# 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]
```

## Related

<CardGroup cols={2}>
  <Card title="Concepts: MCP servers" icon="plug" href="/concepts/mcp-servers" />

  <Card title="Environment & secrets" icon="key" href="/configure/environment-and-secrets" />

  <Card title="Pruning" icon="scissors" href="/workflows/pruning" />

  <Card title="Schema: mcps" icon="file-code" href="/schema/mcps" />
</CardGroup>