If you work with more than one AI CLI tool, you already know the pain: Claude Code expectsDocumentation 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.
.mcp.json, VS Code wants .vscode/mcp.json, OpenAI Codex uses a TOML file, and every other provider has its own format, field names, and quirks. Keeping 8 different config files in sync — for every project — is tedious, error-prone, and completely unnecessary. MCPX solves this by maintaining a single canonical config file (.agents/mcp.json for a project, ~/.agents/mcp.json globally) and automatically generating the correct file for every AI provider you use. Change one file, and all providers stay in sync.
Installation
Install MCPX globally in seconds using npm or directly from GitHub.
Quickstart
Run the interactive wizard and generate all provider configs in minutes.
Canonical Format
Learn the structure of
.agents/mcp.json and every supported field.Providers
Explore provider-specific config paths, formats, and quirks.
Supported Providers
MCPX generates config files for all eight major AI CLI providers. Most support both project-scoped and global configurations; VS Code and IntelliJ IDEA are project-only.| Provider | Project config path | Global config path | Project scope | Global scope |
|---|---|---|---|---|
| Claude Code | .mcp.json | ~/.claude.json | ✅ | ✅ |
| Antigravity CLI | .gemini/config/mcp_config.json | ~/.gemini/config/mcp_config.json | ✅ | ✅ |
| Kimi CLI | .kimi-code/mcp.json | ~/.kimi-code/mcp.json | ✅ | ✅ |
| OpenAI Codex | .codex/config.toml | ~/.codex/config.toml | ✅ | ✅ |
| OpenCode | opencode.json | ~/.config/opencode/opencode.jsonc | ✅ | ✅ |
| GitHub Copilot CLI | .copilot/mcp-config.json | ~/.copilot/mcp-config.json | ✅ | ✅ |
| VS Code | .vscode/mcp.json | — | ✅ | ❌ |
| IntelliJ IDEA | .idea/mcp.json | — | ✅ | ❌ |
OpenAI Codex is the only provider that uses TOML instead of JSON. MCPX handles
this automatically and performs a smart merge so your existing
model and
approval_mode settings are never overwritten.How MCPX works
MCPX operates in three stages every time you runmcpx sync (or complete the mcpx init wizard):
- Canonical config — MCPX reads
.agents/mcp.json(or~/.agents/mcp.jsonfor global scope). This is the single source of truth for all your MCP servers. - Provider generation — For each provider listed in the
providersarray, MCPX translates the canonical server definitions into the exact format that provider expects — including field renames, TOML serialisation, type annotations, and format-specific quirks. - Smart merge — For providers that share their config file with non-MCP settings (such as OpenAI Codex and OpenCode), MCPX replaces only the MCP section and leaves all other top-level keys untouched. When a provider is removed from the list, its generated config file is deleted.