Configuration¶
| Variable | Default | Description |
|---|---|---|
GATE_URL |
http://localhost:8084 |
Spinnaker Gate API endpoint (without trailing /) |
GATE_TOKEN |
(empty) | Bearer token for authentication |
GATE_USER |
(empty) | Basic auth username (alternative to token) |
GATE_PASS |
(empty) | Basic auth password |
GATE_CERT_FILE |
(empty) | Path to x509 client certificate (PEM) |
GATE_KEY_FILE |
(empty) | Path to x509 client key (PEM) |
GATE_INSECURE |
false |
Skip TLS certificate verification |
GATE_COOKIE |
(empty) | Session cookie for a Gate behind SSO, SESSION=... or the bare value, see Gate behind SSO |
GATE_COOKIE_FILE |
(per host) | File holding that cookie; default $XDG_CONFIG_HOME/spinnaker-mcp/cookies/<host>, which spinnaker-mcp login writes |
TRANSPORT |
(empty = HTTP) | Set to stdio for stdio transport |
MCP_PORT |
8085 |
HTTP transport port (ignored when TRANSPORT=stdio) |
MCP_BIND_ADDR |
127.0.0.1 |
HTTP transport bind address; anything but loopback needs MCP_AUTH_TOKEN |
MCP_AUTH_TOKEN |
(empty) | Bearer token every /mcp request must carry, see HTTP transport |
MCP_ALLOWED_ORIGINS |
(empty) | Browser origins allowed to call /mcp cross-origin, comma-separated (https://host[:port]) |
TOOLSETS |
readonly |
Tool groups to register, see Toolsets |
SPINNAKER_MCP_ENV_FILE |
(empty) | A dotenv file to load at start |
Authentication priority: Bearer token > Basic auth > Session cookie > No auth. An x509 client certificate
(GATE_CERT_FILE and GATE_KEY_FILE) is presented on top of whichever of those applies.
Set them in the environment, or put them in a file (from .env.example) and name it in
SPINNAKER_MCP_ENV_FILE. The server never reads a .env from the working directory on its own: MCP clients
start it inside whatever project is open, and a stray .env there could redirect it to another Gate. The npm package always runs
with TRANSPORT=stdio, and the Docker image sets TRANSPORT=stdio unless you override it.
A value that is nothing but an unexpanded placeholder, such as ${GATE_TOKEN}, counts as unset. Some MCP
clients write that placeholder when an optional field is left blank; the server ignores it rather than send it
to Gate as a token or reject it as a toolset.
Gate behind SSO¶
A Gate that sits behind a single sign-on login (OAuth2, SAML) accepts no token and no password from an API
client: every call without its browser session is answered with a redirect to /login, and the server
reports it as gate requires a login session. What Gate does accept is the SESSION cookie it sets in the
browser after you sign in, so the server replays that cookie.
Sign in once per Gate:
spinnaker-mcp login --gate=https://spin-gate.example.com # or: npx -y spinnaker-mcp login --gate=...
It opens the Gate login page in your browser. Sign in, then copy the SESSION cookie for the Gate host
(browser DevTools, Application tab, Cookies) and paste it at the prompt. The command checks the cookie
against GET /auth/user, prints the user it belongs to, and stores it with mode 0600 in
$XDG_CONFIG_HOME/spinnaker-mcp/cookies/<host> (~/.config/... by default). From then on the server
picks it up on its own whenever GATE_URL points at that host, so the client configuration needs only
GATE_URL. When the session expires the tools fail with the same gate requires a login session message:
run login again.
The prompt does not echo what you paste. --cookie=VALUE skips the prompt but leaves the cookie in your
shell history and the process list, so prefer the prompt or piping it on stdin; --cookie-file=PATH stores it elsewhere, --no-browser only prints
the URL. GATE_COOKIE and GATE_COOKIE_FILE set the cookie directly for a server that cannot run
login, for example in a container. The cookie is a credential: whoever holds it is you on that Gate
until it expires, so keep it out of shared configuration and version control.
Toolsets¶
TOOLSETS, or the --toolsets= flag (the flag wins), chooses which tools the server registers. A tool that
is not registered does not exist for the client. Resources and prompts are registered whatever it says.
| Value | Tools |
|---|---|
readonly (default) |
the 27 that only read |
all |
all 38 |
mutating |
the 11 that change Spinnaker |
applications |
2 |
pipelines |
7 |
executions |
9 |
strategies |
3 |
infrastructure |
16 |
tasks |
1 |
Groups combine with commas: TOOLSETS=pipelines,executions. all, readonly and mutating stand alone;
combined with each other or with a group, the server exits at start with Invalid toolsets.
With no TOOLSETS the server is read-only: an assistant cannot trigger, cancel, edit, delete or judge
anything, even if text inside a Gate response tells it to. To let it, add "TOOLSETS": "all" (or the groups
it needs) to the env block of your client configuration. Usage lists which tools change
Spinnaker.
HTTP transport¶
When TRANSPORT is anything but stdio, the server listens on MCP_BIND_ADDR:MCP_PORT
(127.0.0.1:8085 by default) and serves:
| Path | Answers |
|---|---|
/mcp |
MCP over stateless Streamable HTTP, both protocol eras |
/healthz |
200 with {"status":"ok","version":"..."} |
/readyz |
200 when Gate answers a HEAD /applications within 5 s with any status below 500, otherwise 503; the body is {"status":...,"gate_reachable":...} |
/readyz proves Gate is reachable, not that the credentials work: a 401 from Gate still counts as ready.
Anyone who reaches /mcp acts with the Gate credentials the server holds, so it is guarded:
- Bearer token. With
MCP_AUTH_TOKENset, every/mcprequest must sendAuthorization: Bearer <token>; anything else gets401. The server refuses to start on an address that is not loopback without it. Generate one withopenssl rand -hex 32./healthzand/readyzstay open for probes and reveal nothing about Gate. - Origin. A browser request from another site gets
403, so a web page cannot drive a server on your machine. Clients that are not browsers send noOriginand are unaffected.MCP_ALLOWED_ORIGINSlets named browser origins through. - Size and time. Request bodies are capped at 4 MiB; headers must arrive within 10 s.
In Docker, 127.0.0.1 is the container's own loopback, so the HTTP transport needs 0.0.0.0 and therefore
a token: -e TRANSPORT=http -e MCP_BIND_ADDR=0.0.0.0 -e MCP_AUTH_TOKEN -p 127.0.0.1:8085:8085.