Models & configuration

Models

Cluster Build runs against Cluster's hosted gateway, which serves both Claude and GPT models. List what's available:

cluster models

This prints the current set with each model's owner, supported reasoning levels, and the default. Prefer running this over hard-coding a model id copied from elsewhere — the catalog changes over time.

Pick a model per run, or set a default:

cluster exec --model <model-id> "explain this module"   # one run
cluster config set default_model <model-id>              # persist as default

In an interactive session, /model <id> switches mid-conversation.

Reasoning effort

Reasoning-capable models accept an effort hint — one of minimal, low, medium, high, xhigh, max. Set it per run, persist it, or change it live:

cluster exec --effort high "plan this refactor"
cluster config set reasoning_effort medium

In a session, use /effort <level>. Effort levels are validated per model — a model that doesn't support a given level is rejected by the gateway, and non-reasoning models ignore the hint.

config.toml

Settings live in ~/.cluster/config.toml. Inspect and change them with:

cluster config show              # print your current settings
cluster config get default_model
cluster config set <key> <value>

Set every key below with cluster config set <key> <value> — it validates the value and writes config.toml for you, including keys that live in a nested table.

Context compaction

As a conversation grows, Cluster Build automatically summarizes older turns to free up room (controlled by the auto_compact_* keys above). You can also trigger it manually with /compact in a session.

Environment variables

• CLUSTER_TERM_BG — override the terminal background (light or dark) for one run, taking precedence over term_bg.
• CLUSTER_REDUCED_MOTION — set to any value to disable the spinner animation.
• SEARCH_API_V2_URL — override the web_search / web_fetch backend for one run, taking precedence over search_api_url.

MCP servers

Connect the assistant to Model Context Protocol servers by declaring them in config.toml:

[mcp.servers.example]
transport = "stdio"            # or "streamable_http"
command = "npx"                # stdio: executable to launch
args = ["@example/mcp-server"]
# enabled = false                          # keep the server listed but skip discovery and tools (default: true)
# env_vars = ["API_KEY"]                   # stdio: forward named parent env vars to the child (preferred for secrets)
# url = "https://mcp.example.com"   # streamable_http instead of command/args
# bearer_token_env_var = "MCP_TOKEN"       # streamable_http: env var holding the bearer token (preferred)
# auth_token = "${env:MCP_TOKEN}"          # streamable_http: sent as Authorization: Bearer <token>
# env_http_headers = { x-api-key = "MCP_KEY" } # streamable_http: header values read from env vars (preferred)
# headers = { x-api-key = "${env:MCP_KEY}" } # streamable_http: extra headers on every request
# oauth_audience = "tasks"                 # streamable_http: per-user OAuth token managed by the CLI
# oauth_client = "cluster-mcp"             # streamable_http: OAuth client id used to mint that token
auto_approve = []              # tool names auto-approved without a prompt (default: none)
read_only_tools = []           # tool names treated as read-only (default: none)

For stdio servers, Cluster Build starts the configured command as a child process when the server is needed. It does not require a daemon or a listening port, but the executable must be on PATH in the shell where you start cluster. Python MCP servers commonly use uvx; Node MCP servers commonly use npx.

Pass credentials to a stdio server with env_vars — a list of environment variable names. Cluster Build reads each value from the parent process at startup and forwards it to the child under the same name, so only the names live in config.toml. Use the nested env table for non-secret literals (or, for backwards compatibility, ${env:VAR} templates). For example, a UPS-style Node server keeps its credentials in env_vars and its plain settings in env:

[mcp.servers.ups]
transport = "stdio"
command = "npx"
args = ["-y", "ups-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
env_vars = ["UPS_CLIENT_ID", "UPS_CLIENT_SECRET", "UPS_ACCOUNT_NUMBER"]

[mcp.servers.ups.env]
UPS_ENVIRONMENT = "production" # or "sandbox"

A stdio MCP child receives only a small default environment allowlist (such as PATH and HOME) plus the values from env_vars and env — it does not inherit arbitrary variables from the shell that started cluster. If an env_vars entry is unset or empty, that server is marked unavailable until you fix the environment and restart.

For a local checkout, replace command and args with the built executable, such as command = "node" and args = ["/path/to/ups-mcp/dist/index.js"].

Before using that server, export the referenced environment variables and test the handshake:

export UPS_CLIENT_ID=...
export UPS_CLIENT_SECRET=...
export UPS_ACCOUNT_NUMBER=...
cluster mcp test ups

Unless a server's behavior is known to be safe, leave auto_approve empty so tool calls prompt for confirmation.

To keep a server in your config but stop Cluster from connecting to it, set enabled = false on its [mcp.servers.<name>] table. It stays listed in /mcp and cluster mcp list but skips discovery and registers no tools; flip it back with enabled = true or from the /mcp manager. The built-in browser provider is disabled the same way through browser_enabled (stored as [browser] enabled) rather than an [mcp.servers.*] entry.

For a streamable_http server behind authentication, supply a bearer token with bearer_token_env_var (the name of an environment variable holding the token) and/or env-backed headers with env_http_headers (a table mapping header names to environment variable names). As with stdio env_vars, only the variable names are stored in config.toml; the values are read from the parent process at startup.

[mcp.servers.tasks]
transport = "streamable_http"
url = "https://tasks.example/mcp"
bearer_token_env_var = "TASKS_MCP_TOKEN"

[mcp.servers.tasks.env_http_headers]
X-Api-Key = "TASKS_API_KEY"

The older auth_token (sent as an Authorization: Bearer <token> header) and headers (arbitrary extra headers, such as a non-bearer API key) fields still work and accept ${env:VAR} templates resolved at startup, but the name-only fields above are preferred. All of these are streamable-HTTP-only — setting them on a stdio server is an error. Set at most one bearer source (bearer_token_env_var, auth_token, or oauth_audience), and don't combine bearer auth with an explicit Authorization header. A missing or empty referenced variable marks just that one server unavailable rather than taking down the rest of the CLI — see Inspecting servers below.

cluster doctor warns when a server stores a likely secret inline (in auth_token, env, or a secret-looking header) and points you at the name-only fields, without printing the secret value.

For a server whose tools gate on the caller's identity, the CLI can manage a per-user OAuth token for you instead of a static auth_token. Set oauth_audience and oauth_client (both required together, streamable-HTTP-only, and mutually exclusive with auth_token/bearer_token_env_var or an explicit Authorization header), then run a browser login once:

cluster mcp login <server>    # browser PKCE login; stores a per-user token
cluster mcp logout <server>   # remove the stored token

The token is stored per server under ~/.cluster/mcp-auth/<server>.json, separate from your main cluster login, and is refreshed and injected as the bearer automatically when the server connects. Until you log in, an OAuth-configured server connects unauthenticated and fails its handshake.

Inspect what's configured and test a server in isolation:

cluster mcp list            # lists every configured server; an unresolvable one shows as `crashed` with its error
cluster mcp test <server>   # connects to one server; exits non-zero if its config can't resolve or it fails to connect

A single server whose config can't resolve (such as a missing ${env:VAR} or an unset or empty env_vars, bearer_token_env_var, or env_http_headers variable) no longer takes down the CLI: it's listed as crashed with the underlying error, while every healthy server — and your native tools — keep working. cluster mcp test <server> stays strict and exits non-zero so you can diagnose the failing server directly.

Inside a session, /mcp opens a live manager for your MCP servers — including any reported as crashed and any you've disabled. It groups user-configured servers separately from built-in providers and lets you reconnect, enable or disable a server, authenticate or clear OAuth credentials, and inspect a server's tools, all without restarting Cluster. A built-in browser provider is available out of the box through Playwright MCP (toggle with browser_enabled).

Skills

Skills are reusable instructions the assistant can pull in on demand. Drop a SKILL.md (with YAML frontmatter and a markdown body) into its own directory under ~/.cluster/skills/:

~/.cluster/skills/
  my-skill/
    SKILL.md

Cluster Build discovers skills at startup; the assistant loads a skill's body when it's relevant. Manage discovery with a [skills] section:

[skills]
enabled = true        # master switch
disabled = []         # skill directory names to skip

Inspect them with cluster skills list / cluster skills show <name>, or /skills in a session.

Next steps

• Cloud features — set managed_agents_url to unlock /ultraplan and /ultrareview.
• Interactive sessions — where most of these settings come into play.