Skip to content
stacks
Docs menu

Use stacks over MCP

Connect the stacks MCP server to Claude Desktop, Claude Code or any MCP client so the agent can list stacks, create a project and run verify as tool calls.

View as MarkdownOpen in ClaudeOpen in ChatGPT

This page connects the stacks MCP server to an MCP client, so your agent can list stacks, create a project and run its verify steps as tool calls. It covers the tools the server exposes, how to configure it, and what it can't do that the CLI can.

When to use the MCP server

Use the server when your agent can't run shell commands, as in Claude Desktop, or when you'd rather approve stacks as named tool calls than as terminal commands.

When your agent has a shell, the stacks skill is the better fit. The agent runs the CLI directly and gets every command, including search, show and add. The server covers the core loop of picking a stack, creating the project and running verify until it's green.

How the server works

The server is a separate npm package, @steamfield/stacks-mcp, and depends on @steamfield/stacks, the CLI. Each tool call runs that CLI with --json and returns its result, so a tool behaves exactly like the matching command. You don't need stacks installed globally, and the server never looks for it on your PATH.

It talks to the client over stdio and supports both the current MCP revision (2026-07-28) and the previous one (2025-11-25), so older clients work too. It needs Node 22 or newer.

Connect a client

The command every client runs is the same:

npx -y @steamfield/stacks-mcp
Terminal

Claude Code

claude mcp add stacks -- npx -y @steamfield/stacks-mcp
Terminal

Add --scope user to make it available in every project, or --scope project to write it to the repository's .mcp.json for your team.

Claude Desktop

Add the server to claude_desktop_config.json (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "stacks": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@steamfield/stacks-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}
claude_desktop_config.json

Claude Desktop doesn't start servers from your shell, so it doesn't see your shell's PATH. Use the absolute path that which npx prints, and set env.PATH to cover every tool the project's verify steps call, such as git, bun or go. Restart Claude Desktop after editing the file.

Codex and other clients

Codex reads servers from ~/.codex/config.toml:

[mcp_servers.stacks]
command = "npx"
args = ["-y", "@steamfield/stacks-mcp"]
~/.codex/config.toml

Any other MCP client needs the same two things: the command npx with the arguments -y @steamfield/stacks-mcp, over stdio.

Tools

Tool What it does Matches
stacks_list Lists stacks, fragments or apps. Takes an optional group stacks list --json
stacks_new Creates a project from a stack in dir, with an optional preset and fragments to add or drop through with and without stacks new <stack> <dir> --no-launch --json
stacks_verify Runs the verify steps of the project in dir stacks verify --json, run in dir

Paths must be absolute. A relative dir is rejected before anything runs, because the server's working directory is whatever the client started it in, which is rarely the folder you mean.

stacks_list and stacks_new read entry metadata and stats from the stacks API, as the CLI does, so clients see all three tools as reaching outside your machine. They run in the server's working directory. That decides which project entries they see: any under .stacks/stacks/ and .stacks/fragments/ in that directory, which are untrusted.

stacks_new never launches an agent, since the agent calling the tool is already running. The project's .stacks/BRIEF.md is the agent's next read, as it would be after stacks new at a terminal.

Reading verify results

A red verify is a normal result. stacks_verify returns the full verify report with its outcome:

Outcome What the agent does next
green Done. Every step passed
failed Read the failed steps in the report, fix them, and call stacks_verify again
changed Stop and ask you. The verify steps changed since you last accepted them

While verify runs, the server sends a progress notification as each step starts and finishes, if the client asked for progress. Clients that show progress display the step name and its status.

When a call fails outright, for example because dir isn't a stacks project, the tool result is an error whose first line says what happened and whose second line starts with Next: and says what to do. A JSON object follows for programs that parse it, with the CLI's error tag, retryable and the exit code. Output, JSON and exit codes lists the tags.

Changes that need you

The server never passes --accept-changes. When verify returns changed, its next field tells the agent that a person has to review the steps and run stacks verify --accept-changes at a terminal in the project. The CLI refuses that command from an agent, and the server can't prompt you, because it runs the CLI with no terminal attached.

Resources

The server also exposes the CLI's guides as resources, read fresh from the CLI each time:

Resource Content
stacks://guide The agent guide that stacks guide prints
stacks://guide/author The authoring guide from stacks guide author
stacks://guide/author/{topic} One authoring topic. Clients that support completion suggest the topic names

The guides describe the whole CLI, so they mention commands the server doesn't expose as tools.

Configuration

Set these in the env block of the client's server config:

Variable Default What it does
STACKS_MCP_TIMEOUT_SECONDS 900 How long one tool call may run before the server stops the CLI. Raise it for projects with slow verify steps
STACKS_MCP_LOG_LEVEL info Server log level: all, trace, debug, info, warn, error, fatal or none. Logs go to stderr, which most clients save to a log file
STACKS_MCP_CLI The bundled CLI Absolute path to a different CLI entry, such as packages/cli/dist/stacks in a stacks checkout
PATH The client's Every verify step runs with the server's environment, so PATH has to include the tools the steps run

The CLI's own settings apply as usual: ~/.config/stacks/config.json and the variables in Configuration, including STACKS_TELEMETRY_DISABLED.

Note

The server passes its whole environment to every verify step. Keep secrets you don't want a project's steps to see out of the client's env block.

Known limits

The server exposes three commands. Use the CLI for search, show, add, create and validate.

stacks_verify runs the default set of steps and takes no --only, --skip-tag or --all. In a sandboxed project, the prod steps that stacks verify --all adds only run from a terminal.

On stdio, the MCP library the server is built on always advertises the logging, completions and resource-subscription capabilities. The server accepts those requests but has no subscription updates to send, since the guides only change when the CLI is upgraded.

Next steps