# mcpstack 0.2.0 documentation Source revision: 76dec82fb89bdc04843b52833920a54986579065 --- Source: https://nuzzles.github.io/mcpstack/index.md # mcpstack Manage, share, and switch MCP server configurations across **Codex** and **Claude Code**. ```sh mcpstack import mcpstack codex export work.yaml --non-interactive mcpstack claude diff work.yaml mcpstack claude import work.yaml ``` Manages configuration; does not install or run servers. [Installation](https://nuzzles.github.io/mcpstack/getting-started.md) · [Commands](https://nuzzles.github.io/mcpstack/cli-reference.md) · [For agents](https://nuzzles.github.io/mcpstack/agents.md) --- Source: https://nuzzles.github.io/mcpstack/getting-started.md # Installation Requires [Rust 1.98+](https://www.rust-lang.org/tools/install). Install [from source](https://nuzzles.github.io/mcpstack/install-source.md) or through [Crates.io](https://nuzzles.github.io/mcpstack/install-crates.md). Keep Cargo's binary directory on your `PATH`, then check your version: ```sh mcpstack --version ``` Next: [try a stack](https://nuzzles.github.io/mcpstack/workflows.md#try-it). --- Source: https://nuzzles.github.io/mcpstack/install-source.md # From source ```sh git clone https://github.com/nuzzles/mcpstack.git cd mcpstack cargo install --path . --locked ``` --- Source: https://nuzzles.github.io/mcpstack/install-crates.md # Crates.io Install the latest release from [Crates.io](https://crates.io/crates/mcpstack): ```sh cargo install mcpstack --locked ``` Run [`mcpstack update`](https://nuzzles.github.io/mcpstack/command-update.md) to install newer releases. --- Source: https://nuzzles.github.io/mcpstack/compatibility.md # Compatibility | Harness | mcpstack 0.1.0-0.2.0 | main (source) | | --- | --- | --- | | Codex | ✅ | ✅ | | Claude Code | ✅ | ✅ | | Gemini CLI | ❌ | ❌ | ✅ Supported · 🚧 In progress · ❌ Not implemented --- Source: https://nuzzles.github.io/mcpstack/harness-claude.md # Claude Code Supports STDIO, HTTP, SSE, and WebSocket in user configuration. ```sh mcpstack claude list ``` | File | Default | Override | | --- | --- | --- | | MCP config | `~/.claude.json` | `--config` | | Permissions | `~/.claude/settings.json` | `--permissions-config` | With an explicit config path, permissions default to `settings.json` beside it. Only the selected files are managed; inherited policies are not evaluated. `list`, `show`, and `export` skip `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview`, and `Claude Browser`. Use their `--include-*` flags or `--all` to inspect/export them. Import/use reject these reserved names. Permissions reject `auto`, `writes`, default-ask with allow overrides, and server names ambiguous at `__` separators. Per-server working directories and timeouts are unsupported. [Full help](https://nuzzles.github.io/mcpstack/help-claude.txt) · [Commands](https://nuzzles.github.io/mcpstack/cli-reference.md) --- Source: https://nuzzles.github.io/mcpstack/harness-codex.md # Codex Supports STDIO and HTTP. ```sh mcpstack codex list ``` Reads `$CODEX_HOME/config.toml`, otherwise `~/.codex/config.toml`. Override with `--config `. Unrelated settings and comments are preserved. `list`, `show`, and `export` skip `computer-use` and `node_repl`. Include them with `--include-computer-use`, `--include-node-repl`, or `--all`. Permissions map allow/ask to approve/prompt, retain auto/writes, and map exact denials to disabled tools. Partial tool patterns, wildcard denials, and overlapping approval decisions are rejected. Native fields follow the bundled Codex schema. [Full help](https://nuzzles.github.io/mcpstack/help-codex.txt) · [Commands](https://nuzzles.github.io/mcpstack/cli-reference.md) --- Source: https://nuzzles.github.io/mcpstack/cli-reference.md # Commands Use `mcpstack ` for interactive harness selection or `--harness codex` or `--harness claude` for unattended runs. Namespaced `mcpstack ` forms remain available. Only `import` accepts multiple harnesses. `--config ` selects a configuration for one harness. `--non-interactive` disables prompts; `-y` approves changes. Permissions always require `--include-permissions`. ## Operations | Command | Purpose | | --- | --- | | [list](https://nuzzles.github.io/mcpstack/command-list.md) | List configured servers without running them. | | [show](https://nuzzles.github.io/mcpstack/command-show.md) | Print a portable YAML stack to stdout. | | [export](https://nuzzles.github.io/mcpstack/command-export.md) | Save a portable YAML stack. | | [diff](https://nuzzles.github.io/mcpstack/command-diff.md) | Preview a redacted import diff without writing files or running servers. | | [import](https://nuzzles.github.io/mcpstack/command-import.md) | Merge server additions and replacements; preserve servers absent from the stack. | | [use](https://nuzzles.github.io/mcpstack/command-use.md) | Replace the entire server set. **Servers absent from the stack are removed.** | | [validate](https://nuzzles.github.io/mcpstack/command-validate.md) | Check stack syntax without resolving secrets, reading client config, or running servers. | | [update](https://nuzzles.github.io/mcpstack/command-update.md) | Check for or install the latest stable release from crates.io. | | [help](https://nuzzles.github.io/mcpstack/command-help.md) | Show command help. | ## Exit statuses Zero means success, cancellation, or no change; nonzero means failure. [Full help](https://nuzzles.github.io/mcpstack/help-mcpstack.txt) · [CLI schema and error codes](https://nuzzles.github.io/mcpstack/cli-schema.json) · Version 0.2.0 --- Source: https://nuzzles.github.io/mcpstack/command-list.md # list List configured servers without running them. ```sh mcpstack list mcpstack list --harness codex --non-interactive mcpstack codex list ``` Select exact names with repeated `--server `. `--all` includes normally skipped servers but does not widen an explicit selection. [Claude Code options](https://nuzzles.github.io/mcpstack/help-claude-list.txt) · [Codex options](https://nuzzles.github.io/mcpstack/help-codex-list.txt) · [All options](https://nuzzles.github.io/mcpstack/help-list.txt) --- Source: https://nuzzles.github.io/mcpstack/command-show.md # show Print a portable YAML stack to stdout. ```sh mcpstack show mcpstack show --harness codex --non-interactive mcpstack codex show --non-interactive ``` Masks recognized credentials. Add `--include-permissions` to include policy. Use [export](https://nuzzles.github.io/mcpstack/command-export.md) to save a file. [Claude Code options](https://nuzzles.github.io/mcpstack/help-claude-show.txt) · [Codex options](https://nuzzles.github.io/mcpstack/help-codex-show.txt) · [All options](https://nuzzles.github.io/mcpstack/help-show.txt) --- Source: https://nuzzles.github.io/mcpstack/command-export.md # export Save a portable YAML stack. ```sh mcpstack export mcpstack export work.yaml --harness codex --non-interactive mcpstack codex export work.yaml --non-interactive ``` Masks recognized credentials; permissions require `--include-permissions`. Existing files require `--overwrite` in noninteractive mode. Review before sharing. [Claude Code options](https://nuzzles.github.io/mcpstack/help-claude-export.txt) · [Codex options](https://nuzzles.github.io/mcpstack/help-codex-export.txt) · [All options](https://nuzzles.github.io/mcpstack/help-export.txt) --- Source: https://nuzzles.github.io/mcpstack/command-diff.md # diff Preview a redacted import diff without writing files or running servers. ```sh mcpstack diff work.yaml --harness codex --non-interactive mcpstack codex diff work.yaml --non-interactive mcpstack codex diff https://example.com/work.yaml --non-interactive ``` Missing secrets fail in noninteractive mode. This previews merges; use [use --dry-run](https://nuzzles.github.io/mcpstack/command-use.md) to preview removals during a stack switch. [Claude Code options](https://nuzzles.github.io/mcpstack/help-claude-diff.txt) · [Codex options](https://nuzzles.github.io/mcpstack/help-codex-diff.txt) · [All options](https://nuzzles.github.io/mcpstack/help-diff.txt) --- Source: https://nuzzles.github.io/mcpstack/command-import.md # import Merge server additions and replacements; preserve servers absent from the stack. ```sh mcpstack import mcpstack import work.yaml --harness codex --harness claude --dry-run --non-interactive -y mcpstack codex import work.yaml --dry-run --non-interactive -y mcpstack codex import work.yaml --non-interactive -y mcpstack codex import https://example.com/work.yaml --dry-run --non-interactive -y ``` `-y` approves changes; `--non-interactive` prevents secret prompts. Permissions are preserved unless `--include-permissions` is supplied. HTTP(S) stack URLs work in both clients. Remote stacks cannot use stack-relative commands or working directories; use absolute paths or `path_resolution: client`. [Claude Code options](https://nuzzles.github.io/mcpstack/help-claude-import.txt) · [Codex options](https://nuzzles.github.io/mcpstack/help-codex-import.txt) · [All options](https://nuzzles.github.io/mcpstack/help-import.txt) --- Source: https://nuzzles.github.io/mcpstack/command-use.md # use Replace the entire server set. **Servers absent from the stack are removed.** ```sh mcpstack use work.yaml --harness codex --dry-run --non-interactive mcpstack codex use work.yaml --dry-run --non-interactive mcpstack codex use work.yaml --non-interactive -y mcpstack codex use https://example.com/work.yaml --dry-run --non-interactive ``` An empty stack clears all servers. Unrelated settings are preserved. Permissions require `--include-permissions`; `--server` is not supported. HTTP(S) stack URLs work in both clients. Remote stacks cannot use stack-relative commands or working directories; use absolute paths or `path_resolution: client`. [Claude Code options](https://nuzzles.github.io/mcpstack/help-claude-use.txt) · [Codex options](https://nuzzles.github.io/mcpstack/help-codex-use.txt) · [All options](https://nuzzles.github.io/mcpstack/help-use.txt) --- Source: https://nuzzles.github.io/mcpstack/command-validate.md # validate Check stack syntax without resolving secrets, reading client config, or running servers. ```sh mcpstack validate work.yaml mcpstack validate https://example.com/work.yaml ``` A valid stack may contain unsupported target settings. Use [diff](https://nuzzles.github.io/mcpstack/command-diff.md) to check harness compatibility. URL validation fetches the stack but does not resolve client settings or secrets. Successful validation prints the source URL, including any query string. [All options](https://nuzzles.github.io/mcpstack/help-validate.txt) --- Source: https://nuzzles.github.io/mcpstack/command-update.md # update Check for or install the latest stable release from crates.io. ```sh mcpstack update --check mcpstack update mcpstack update --non-interactive -y ``` `--check` only reports versions. Installation requires confirmation or `-y`, Cargo, and a working Rust toolchain. Cargo installs are updated in their original location, including custom `--root` paths. Development binaries and other package managers must be updated through their original installation method. After interactive `export`, `import`, and `use`, mcpstack checks at most daily and prints update notices to stderr. Checks take at most 750 ms of network time; offline failures are silent. Read-only commands, dry runs, redirected output, `--non-interactive`, and `--quiet` skip automatic checks. Disable automatic checks with `--skip-version-check` or `MCPSTACK_SKIP_VERSION_CHECK=true`. Explicit `update --check` still works. Updates are never installed during other commands. [All options](https://nuzzles.github.io/mcpstack/help-update.txt) --- Source: https://nuzzles.github.io/mcpstack/command-help.md # help Show command help. ```sh mcpstack import --help mcpstack help codex import mcpstack claude use --help ``` `-h` gives a shorter summary. `--version` prints the version; `--schema` prints the CLI interface. --- Source: https://nuzzles.github.io/mcpstack/references.md # References - [Everyday workflows](https://nuzzles.github.io/mcpstack/workflows.md) - [Secrets and permissions](https://nuzzles.github.io/mcpstack/secrets-and-permissions.md) - [Failures and recovery](https://nuzzles.github.io/mcpstack/recovery.md) - [For agents](https://nuzzles.github.io/mcpstack/agents.md) - [Stack format](https://nuzzles.github.io/mcpstack/stack-format.md) --- Source: https://nuzzles.github.io/mcpstack/workflows.md # Everyday workflows Run `mcpstack import` to choose one or both harnesses, then enter a stack file path or HTTP(S) URL. Selecting none reports that nothing was imported and exits without asking for a source. Installed harnesses appear first and are marked `(installed)`; each group is alphabetical. `list`, `show`, `export`, `diff`, and `use` select one harness. Pass `--harness codex` or `--harness claude` to skip the prompt; repeat `--harness` only with `import` to select both. For unattended runs, provide the source or export file and `--non-interactive`. When importing to both harnesses, each is processed in turn; an error can leave the first harness updated. Use the namespaced form for harness-specific options. ## Try it [Download demo.yaml](https://nuzzles.github.io/mcpstack/examples/demo.yaml), then preview against an unused config path: ```sh mcpstack validate demo.yaml mcpstack codex use demo.yaml --config scratch.toml --dry-run --non-interactive ``` Nothing is written or executed. For Claude Code, use `claude` and `scratch.json`. ## Share ```sh mcpstack codex export work.yaml --non-interactive mcpstack claude diff work.yaml mcpstack claude import work.yaml ``` `import` merges servers; those absent from the stack stay configured. ## Switch ```sh mcpstack codex use personal.yaml --dry-run mcpstack codex use personal.yaml ``` **`use` removes servers absent from the stack.** An empty stack clears them all. Unrelated settings are preserved. Repeating an identical import or switch writes nothing. Both harnesses support these commands. See [secrets and permissions](https://nuzzles.github.io/mcpstack/secrets-and-permissions.md) and [recovery](https://nuzzles.github.io/mcpstack/recovery.md) before sharing or applying changes. --- Source: https://nuzzles.github.io/mcpstack/secrets-and-permissions.md # Secrets and permissions ## Secrets Use `--non-interactive` with `show` or `export` to mask recognized credentials. Review shared files: arbitrary embedded secrets may escape detection. `--expose-secrets` includes literals. ```yaml schema_version: 1 servers: example: transport: type: http url: https://mcp.example.com/mcp headers: Authorization: {value_env: EXAMPLE_AUTHORIZATION} ``` Supply the complete header through `EXAMPLE_AUTHORIZATION`. `value_env` resolves at import; `{env: TOKEN, prefix: "Bearer "}` preserves client runtime lookup instead. Claude stdio arguments and environment values also preserve `{env: VARIABLE}` references. Native `config` entries use `{$env: VARIABLE}` for masked literals. Detected credentials inside header-helper commands mask the whole command with `{value_env: VARIABLE}`; supply the complete command when importing. ## Permissions Both harnesses require **`--include-permissions`** to export, compare, or apply policy. Otherwise target policy is preserved. `--all` does not include permissions. Use local tool names: `permissions: {allow: [read], ask: [write], deny: [delete]}`. When included, `{}` clears captured decisions; an omitted policy preserves them. Unsupported conversions fail before writes. See [compatibility](https://nuzzles.github.io/mcpstack/compatibility.md). --- Source: https://nuzzles.github.io/mcpstack/recovery.md # Failures and recovery | Failure | Action | | --- | --- | | Invalid stack or unsupported setting | Validate the stack and check harness compatibility. | | Missing secret | Supply its environment value or run interactively. | | Configuration changed | Read the latest file and preview again. | | Write or recovery failed | Inspect the reported files and backups before retrying. | ## Backups Backups use numbered siblings such as `config.toml.~1~`; existing backups are never replaced. Dry runs and unchanged configurations create none. Codex interactive imports can skip backups; automatic imports, stack switches, and Claude writes back up changed existing files. Keep credential-bearing configs and backups private. To restore, preserve any newer changes, inspect the backup, then copy it to the original path. For Claude, check both MCP config and permission settings. There is no restore command. ## Transactions Changes apply as a whole file/stack. Codex replaces one file atomically. Claude attempts rollback if either file fails, while protecting detected concurrent edits. There is no crash recovery, locking, or atomic multi-file commit. Incomplete recovery is reported; a backup-write failure may leave a partial backup. --- Source: https://nuzzles.github.io/mcpstack/agents.md # For agents [Documentation index](https://nuzzles.github.io/mcpstack/llms.txt) · [All Markdown](https://nuzzles.github.io/mcpstack/llms-full.txt) · [CLI schema](https://nuzzles.github.io/mcpstack/cli-schema.json) ## Install the skill ```sh npx skills add https://nuzzles.github.io/mcpstack ``` Or install from GitHub: `npx skills add nuzzles/mcpstack --skill mcpstack`. Add `-g` for all projects or `-a codex -a claude-code` to select agents. The [skill](https://nuzzles.github.io/mcpstack/.well-known/skills/mcpstack/SKILL.md) teaches agents the CLI workflow; [install mcpstack](https://nuzzles.github.io/mcpstack/getting-started.md) separately. ## Automation Direct commands need an explicit `--harness` when prompts are disabled. Only `import` accepts repeated `--harness` to process both harnesses; every other client command selects one. ```sh mcpstack --schema mcpstack codex import work.yaml --dry-run --non-interactive -y mcpstack codex import work.yaml --non-interactive -y ``` Apply only after authorization. Use the installed binary's schema, explicit `--config` paths when needed, and identical flags for preview/apply. For stack switches, preview with `use --dry-run`; it shows removals that `diff` does not. Schema `requires` lists companion argument IDs needed when an option is supplied. | Output | Format | | --- | --- | | `--schema` | JSON interface and exit codes | | `show` | YAML stack | | Other stdout | Human-readable text | | stderr | Diagnostics and prompts | `--non-interactive` disables prompts; `-y` approves changes. Missing secrets fail; supply them through environment variables. Permissions require `--include-permissions`. Nonzero exits mean failure; zero can also mean cancellation or no change. Inspect results before retrying. There is no JSON result mode for imports or switches. --- Source: https://nuzzles.github.io/mcpstack/stack-format.md # Stack format YAML with `schema_version: 1` and named servers. No source-harness labels. ```yaml schema_version: 1 servers: local: transport: {type: stdio, command: ./bin/server} remote: transport: {type: http, url: "https://mcp.example.com/mcp"} ``` | Field | Purpose | | --- | --- | | `transport` | STDIO command/args/env, or HTTP/SSE/WebSocket URL and headers | | `transport.headers_helper` | Shell command that returns headers as JSON; HTTP in both harnesses, SSE/WebSocket in Claude | | `config` | Native server fields; use instead of `transport` | | `settings` | Enabled/required flags, timeouts, tool filters | | `permissions` | Local tool decisions: allow, ask, deny, auto, writes; optional default_mode | Unsupported target fields fail. Tool filters and permissions require `--include-permissions`. Deny takes precedence over ask, then allow; patterns depend on the harness. See [compatibility](https://nuzzles.github.io/mcpstack/compatibility.md) and [secret references](https://nuzzles.github.io/mcpstack/secrets-and-permissions.md). The harness runs header helpers using its own authentication precedence and refresh rules. mcpstack preserves commands verbatim without running them; use `PATH` or absolute script paths. ## Paths `path_resolution: stack` (default) resolves relative commands and `cwd` from the stack's directory. Bare commands use `PATH`. Exports use `path_resolution: client` to retain original runtime behavior. Arguments and environment strings are not expanded or rebased. `validate`, `diff`, `import`, and `use` also accept HTTP(S) URLs. A remote stack has no local directory, so stack-relative commands and `cwd` fail; use absolute paths or `path_resolution: client`. URL responses must be UTF-8 and at most 4 MiB. Check syntax with `mcpstack validate work.yaml`; preview against the target to check compatibility.