mcpstack

Manage, share, and switch MCP server configurations across Codex and Claude Code.

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 · Commands · For agents

Installation

Requires Rust 1.98+.

Install from source or through Crates.io. Keep Cargo’s binary directory on your PATH, then check your version:

mcpstack --version

Next: try a stack.

From source

git clone https://github.com/nuzzles/mcpstack.git
cd mcpstack
cargo install --path . --locked

Crates.io

Install the latest release from Crates.io:

cargo install mcpstack --locked

Run mcpstack update to install newer releases.

Compatibility

✅ Supported · 🚧 In progress · ❌ Not implemented

Claude Code

Supports STDIO, HTTP, SSE, and WebSocket in user configuration.

mcpstack claude list

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 · Commands

Codex

Supports STDIO and HTTP.

mcpstack codex list

Reads $CODEX_HOME/config.toml, otherwise ~/.codex/config.toml. Override with --config <PATH>. 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 · Commands

Commands

Use mcpstack <command> for interactive harness selection or --harness codex or --harness claude for unattended runs. Namespaced mcpstack <harness> <command> forms remain available. Only import accepts multiple harnesses. --config <PATH> selects a configuration for one harness.

--non-interactive disables prompts; -y approves changes. Permissions always require --include-permissions.

Operations

Exit statuses

Zero means success, cancellation, or no change; nonzero means failure.

Full help · CLI schema and error codes · Version 0.2.0

list

List configured servers without running them.

mcpstack list
mcpstack list --harness codex --non-interactive
mcpstack codex list

Select exact names with repeated --server <NAME>. --all includes normally skipped servers but does not widen an explicit selection.

Claude Code options · Codex options · All options

show

Print a portable YAML stack to stdout.

mcpstack show
mcpstack show --harness codex --non-interactive
mcpstack codex show --non-interactive

Masks recognized credentials. Add --include-permissions to include policy. Use export to save a file.

Claude Code options · Codex options · All options

export

Save a portable YAML stack.

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 · Codex options · All options

diff

Preview a redacted import diff without writing files or running servers.

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 to preview removals during a stack switch.

Claude Code options · Codex options · All options

import

Merge server additions and replacements; preserve servers absent from the stack.

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 · Codex options · All options

use

Replace the entire server set. Servers absent from the stack are removed.

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 · Codex options · All options

validate

Check stack syntax without resolving secrets, reading client config, or running servers.

mcpstack validate work.yaml
mcpstack validate https://example.com/work.yaml

A valid stack may contain unsupported target settings. Use diff 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

update

Check for or install the latest stable release from crates.io.

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

help

Show command help.

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.

References

• Everyday workflows
• Secrets and permissions
• Failures and recovery
• For agents
• Stack format

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, then preview against an unused config path:

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

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

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 and recovery before sharing or applying changes.

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.

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.

Failures and recovery

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.

For agents

Documentation index · All Markdown · CLI schema

Install the skill

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 teaches agents the CLI workflow; install mcpstack 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.

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.

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

Stack format

YAML with schema_version: 1 and named servers. No source-harness labels.

schema_version: 1
servers:
  local:
    transport: {type: stdio, command: ./bin/server}
  remote:
    transport: {type: http, url: "https://mcp.example.com/mcp"}

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 and secret references.

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.