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

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](https://stacks.steamfield.io/docs/agents.md) 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:

```sh title="Terminal"
npx -y @steamfield/stacks-mcp
```

### Claude Code

```sh title="Terminal"
claude mcp add stacks -- npx -y @steamfield/stacks-mcp
```

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):

```json title="claude_desktop_config.json"
{
  "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 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`:

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

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](https://stacks.steamfield.io/docs/concepts/registries-and-trust.md).

`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](https://stacks.steamfield.io/docs/reference/output.md) 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](https://stacks.steamfield.io/docs/reference/configuration.md), 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

- [Use stacks with your agent](https://stacks.steamfield.io/docs/agents.md): the skill, for agents that have a shell.
- [Verify: the definition of done](https://stacks.steamfield.io/docs/concepts/verify.md): what `stacks_verify` runs and how outcomes are decided.
- [Registries and trust](https://stacks.steamfield.io/docs/concepts/registries-and-trust.md): which entries `stacks_new` treats as untrusted.