MCPX supports two configuration scopes — project and global. Project scope configures MCP servers for a single repository or working directory, keeping server definitions close to the code that needs them. Global scope applies across your entire user account and is ideal for servers you rely on in every project, such as a personal GitHub integration or a productivity tool. Both scopes share the same canonical format; only the file location and the set of supported providers differ.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.
Project scope
ConfigScope = 'project'
Project scope stores the canonical config at .agents/mcp.json relative to your project root and generates each provider’s config file inside that same directory tree.
| Aspect | Detail |
|---|---|
| Canonical file | .agents/mcp.json |
| Example path | /my-project/.agents/mcp.json |
| Providers supported | All 8 |
- Your MCP servers are specific to one project (for example, a Jira integration pointing at a single workspace).
- You want to commit the canonical config and the generated provider configs to version control so teammates get the same setup automatically.
- Different projects need different sets of servers or different credentials.
Global scope
ConfigScope = 'global'
Global scope stores the canonical config at ~/.agents/mcp.json in your home directory and generates provider configs in each tool’s global config location.
| Aspect | Detail |
|---|---|
| Canonical file | ~/.agents/mcp.json |
| Example path | ~/.agents/mcp.json |
| Providers supported | antigravity-cli, claude-code, copilot-cli, kimi-cli, openai-codex, opencode |
- You want a server available in every project without repeating configuration.
- You use personal API tokens that should not be checked into any repository.
VS Code and IntelliJ IDEA are project-only providers. They do not support
global scope and will not appear as options when initializing a global config.
Scope detection
When you run any MCPX command without explicitly specifying a scope, MCPX determines the active scope automatically by examining the resolvedprojectRoot directory. The detection logic follows these steps in order:
Home directory check
If the resolved
projectRoot equals your home directory, MCPX uses
global scope. Running mcpx from ~ will always resolve to global
without prompting.Project config exists
If
.agents/mcp.json exists inside projectRoot, MCPX uses project
scope for that directory.Global config exists
If
~/.agents/mcp.json exists (even if you are not in the home directory),
MCPX uses global scope.Choosing a scope interactively
- Project scope
- Global scope
Navigate to your project directory and run Select Project to create
mcpx init. The wizard will
detect that you are not in the home directory and ask which scope you want
to initialize..agents/mcp.json in the current directory.
MCPX will then let you add servers and choose providers, and will generate
all provider config files inside the project.Provider scope support
| Provider | Supports Project | Supports Global |
|---|---|---|
claude-code | ✅ | ✅ |
antigravity-cli | ✅ | ✅ |
kimi-cli | ✅ | ✅ |
openai-codex | ✅ | ✅ |
opencode | ✅ | ✅ |
copilot-cli | ✅ | ✅ |
vscode | ✅ | ❌ |
intellij | ✅ | ❌ |
Running
mcpx from the home directory (~) automatically uses global scope
without prompting. This is a shortcut for quickly managing your global MCP
servers without needing to navigate elsewhere.