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.

mcpx sync reads .agents/mcp.json (or ~/.agents/mcp.json for global scope) and writes or updates every provider config file listed in the providers array. For providers whose config files contain non-MCP settings alongside the MCP section — such as OpenAI Codex’s .codex/config.toml — MCPX performs a smart merge that replaces only the MCP section and leaves all other settings intact. 
mcpx sync [--dir <path>] [--verbose]
If no .agents/mcp.json exists in the target directory, MCPX prints a warning and directs you to run mcpx init first. If the config exists but has no providers configured, MCPX warns that there is nothing to sync.

​
Sync results

After processing all providers, MCPX prints a line for each file and a summary. Each file is tagged with one of the following statuses:
StatusMeaning
createdThe provider config file did not exist; MCPX created it (and any parent directories).
updatedThe file already existed but its content differed from the expected output; MCPX overwrote it.
unchangedThe file already matched the expected output exactly; MCPX skipped writing it.
errorMCPX could not write the file; the error message is printed alongside the path.

​
Example output

.mcp.json (created)
.gemini/config/mcp_config.json (updated)
.vscode/mcp.json (unchanged)
3 providers processed (1 created, 1 updated, 1 unchanged)

​
When to run sync

  • After manually editing .agents/mcp.json to add, remove, or change server definitions.
  • After adding or removing providers through mcpx init (the wizard syncs automatically, but a manual sync is safe to run afterwards).
  • After pulling changes from version control that modified .agents/mcp.json.
  • Whenever mcpx status reports one or more providers as desync or missing.
Smart merge for OpenAI Codex: .codex/config.toml may contain Codex-specific settings such as model, approval_mode, and other top-level keys that are unrelated to MCP. When syncing, MCPX replaces only the [mcp_servers] section in that file and preserves all other settings, so your Codex configuration is never overwritten by a sync.
Run mcpx status first to preview which provider files will be created or updated before committing to the sync. This is especially useful in CI or before code review to verify that all generated files are current.

Build docs developers (and LLMs) love

Get started for freeTalk to us