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.

mcps:
  - name: <string>
    agents: <[string] | ["*"]>
    global: <bool>           # optional, default false (set true for current agents)
    source: <url>            # mutually exclusive with inline
    inline:                  # mutually exclusive with source
      type: <stdio|http|sse> # optional
      command: <string>
      args: <[string]>
      env: <map[string,string]>
      url: <string>
      headers: <map>
    merge: <bool>            # optional, default true
    target: <path>           # deprecated — use agents instead

​
Type

array[McpEntry]

​
Required

No. Omit mcps: if you don’t manage any.

​
Entry fields

​
name

FieldTypeRequired
namestringyes
The identifier the entry is upserted under inside the target’s mcpServers object.

​
agents

FieldTypeRequired
agentsarray of stringsyes (when target is not set)
Either a list of registry names ([claude-code, cursor, codex]) or the wildcard ["*"]. ["*"] resolves at sync time to every registered agent that has a non-empty MCP config for the requested scope. Agents whose registry entry has no MCP config for that scope are skipped silently. The destination JSON file is then looked up in the agent registry — global_mcp_config_file for global: true, project_mcp_config_file for global: false.

​
global

FieldTypeRequiredDefault
globalboolnofalse
ValueResolved path
trueglobal_mcp_config_file from the registry — the agent’s user-global MCP config (e.g. ~/.claude.json).
falseproject_mcp_config_file from the registry — the agent’s workspace-scoped MCP config.
In the current registry every built-in agent only ships a global_mcp_config_file. Set global: true on every entry until per-project MCP configs land. With global: false (the YAML default) gaal silently skips the entry for every agent that has no project-scoped MCP path.

​
source

FieldTypeRequired
sourceURLconditionally
A URL returning a JSON document with an mcpServers object. gaal downloads the file and merges the entry whose key matches name into each resolved target. Mutually exclusive with inline.

​
inline

FieldTypeRequired
inlineobjectconditionally
The MCP server spec, written directly in gaal.yaml. Inline entries can describe stdio servers or native HTTP/SSE endpoints, depending on what the target agent supports.
SubfieldTypeRequired
typestringno
commandstringconditionally
argsarray of stringsno
envmap[string]stringno
urlstringconditionally
headersmap[string, HeaderValue]no
Use command for stdio servers. Use url for HTTP or SSE servers. type defaults to stdio when command is set, and HTTP when url is set. Header values may be plain scalars or objects: 
headers:
  X-Team: platform
  Authorization:
    env: LINEAR_API_KEY
Prefer env: for secrets. gaal writes the environment variable name into formats that support env-backed headers. Mutually exclusive with source. Exactly one of source or inline must be set per entry.

​
merge

FieldTypeRequiredDefault
mergeboolnotrue
Whether to merge the entry into the existing mcpServers object (preserving siblings) or overwrite it. The default keeps every server gaal didn’t author.

​
target (deprecated)

FieldTypeRequired
targetstringno
Explicit path to the JSON file. Deprecated — set agents: and global: instead so the path comes from the registry. When both target and agents are set, target wins and gaal logs a deprecation warning.

​
Example

mcps:
  # Inline stdio server, fanned out to two agents.
  - name: filesystem
    agents: [claude-code, cursor]
    global: true
    inline:
      command: uvx
      args: [mcp-server-filesystem, ~/projects]

  # Native HTTP server with an env-backed header.
  - name: linear
    agents: [claude-code]
    global: true
    inline:
      type: http
      url: https://mcp.linear.app/mcp
      headers:
        Authorization:
          env: LINEAR_API_KEY

  # SSE server.
  - name: sentry
    agents: [claude-code]
    global: true
    inline:
      type: sse
      url: https://mcp.sentry.dev/sse

  # Remote source, every detected agent.
  - name: github
    source: https://raw.githubusercontent.com/github/mcp-servers/main/config.json
    agents: ["*"]
    global: true

​
Behaviour

  • gaal upserts under the mcpServers object of every resolved target file.
  • Other top-level keys in the target are preserved.
  • Other entries inside mcpServers that gaal didn’t author are preserved.
  • Removing an entry from gaal.yaml does not remove it from the target unless you pass --prune.
  • gaal does not expand ${VAR} references in args: or env:. The agent process resolves them when launching the server.
  • Header env: values name environment variables; they do not contain the secret itself.
  • When the resolved target’s parent directory is missing, gaal silently skips the entry — it never creates an agent’s config directory as a side effect.

Concepts: MCP servers

Configure MCP servers

Environment & secrets