Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/davidpastorvicente/mcpx-cli/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common issues you may encounter when using MCPX and how to resolve each one quickly. If your problem isn’t listed here, check the GitHub Issues page or open a new issue with the output of your failing command.
Run any MCPX command with --verbose to get detailed debug output that can help identify exactly where a failure is occurring:
mcpx sync --verbose
mcpx add my-server --verbose
Cause: You ran mcpx add, mcpx sync, mcpx status, or another command that requires an existing canonical config, but .agents/mcp.json (or ~/.agents/mcp.json for global scope) doesn’t exist yet.Fix: Run the initialization wizard first to create the config file:
mcpx init
If your project is not your current directory, use --dir:
mcpx init --dir /path/to/my-project
Cause: .agents/mcp.json was modified — either manually or by a command — but the corresponding provider config file on disk was not regenerated afterward. The file exists but its contents no longer match what MCPX expects.Fix: Regenerate all provider config files from the current canonical config:
mcpx sync
All providers should show sync when you run mcpx status again.
Cause: The provider config file was deleted, never created, or the provider was added to .agents/mcp.json without running a sync afterward.Fix: Run mcpx sync to create the missing file:
mcpx sync
MCPX will report the file as created once it has been written.
Cause: A server with the name you provided already exists in .agents/mcp.json. MCPX does not silently overwrite existing entries.Fix: Either choose a different name when prompted, or remove the existing server first:
mcpx remove my-server
Then run mcpx add my-server again with your updated configuration.
Cause: MCPX reads .codex/config.toml (or ~/.codex/config.toml) when syncing the OpenAI Codex provider. If the file contains invalid TOML syntax, the parse step fails and MCPX cannot merge the MCP section with the rest of your Codex settings.Fix: Open the file in a text editor and fix the TOML syntax manually before running mcpx sync again. You can use an online TOML validator to identify the offending line.
# After fixing the file:
mcpx sync
Cause: npm installed the binary into the global bin directory for your npm prefix, but that directory is not in your shell’s PATH.Fix: Find your npm prefix and add its bin subdirectory to PATH:
npm config get prefix
# Example output: /usr/local
# Add /usr/local/bin to PATH if it's not already there
For a permanent fix, add the following to your shell profile (.bashrc, .zshrc, etc.):
export PATH="$(npm config get prefix)/bin:$PATH"
Restart your terminal or run source ~/.zshrc (or equivalent) to apply the change.
Cause: MCPX requires Node.js >= 20. Running it on an older version produces errors at startup or during install.Fix: Upgrade to Node.js 20 or later. If you use nvm:
nvm install 20
nvm use 20
Or download the latest LTS release from nodejs.org.Verify your version after upgrading:
node --version
# Should print v20.x.x or higher
Cause: VS Code (.vscode/mcp.json) and IntelliJ IDEA (.idea/mcp.json) are project-only providers — they do not have a global config path. When you run mcpx init with global scope, these two providers are excluded automatically and will not appear in the provider selection list.Fix: Run mcpx init from your project directory and choose project scope:
cd my-project
mcpx init
# Choose "Project" when prompted for scope
VS Code and IntelliJ will then appear as selectable providers.
Cause: MCPX copies env values from .agents/mcp.json verbatim into every generated provider config file. If you stored a real API key or token as a string value, it will appear in every file MCPX writes — including .mcp.json, .vscode/mcp.json, and others.Tip: Use shell environment variable references in your terminal session rather than storing the literal value in the config. Alternatively, manage secrets with a dedicated secrets tool (e.g. direnv, AWS Secrets Manager, 1Password CLI) and inject them at runtime rather than at config generation time.At minimum, add the generated provider files to .gitignore so they are not committed:
# Provider configs generated by MCPX
.mcp.json
.copilot/mcp-config.json
.gemini/config/mcp_config.json
.kimi-code/mcp.json
.codex/config.toml
opencode.json
.vscode/mcp.json
.idea/mcp.json
Cause: MCPX scanned the current directory (and home directory for global scope) for known provider config files but found none. This typically means you’re running the command from the wrong directory.Fix: Make sure you’re in the project root that contains the provider config files you want to import:
cd /path/to/my-project
mcpx import
Or use --dir to specify the directory explicitly:
mcpx import --dir /path/to/my-project
If you encounter a bug or a scenario not covered here, please open an issue at github.com/davidpastorvicente/mcpx-cli/issues. Include the MCPX version (mcpx --version), your Node.js version, operating system, and the full output of the failing command with --verbose.

Build docs developers (and LLMs) love

Get started for freeTalk to us