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.

By the end of this page you will have a working .agents/mcp.json file in your project, and MCPX will have generated the correct config file for every AI provider you selected. The whole process takes under five minutes and requires no manual JSON editing — the interactive wizard handles everything.
1

Install MCPX

Install the CLI globally using npm. Node.js 20 or later is required.
npm install -g github:davidpastorvicente/mcpx-cli
Verify the installation:
mcpx --version
# 2.0.1
2

Navigate to your project

Change into the directory you want to configure. MCPX will create .agents/mcp.json here along with all provider-specific config files.
cd my-project
Run from your home directory (cd ~) instead of a project folder to create a global configuration at ~/.agents/mcp.json. MCPX detects the home directory automatically and skips the scope prompt.
3

Run the interactive wizard

Start the wizard by running mcpx (or the equivalent mcpx init):
mcpx
The wizard walks you through five phases:
  1. Detection — MCPX scans your project for existing MCP config files from any supported provider.
  2. Import offer — If existing configs are found, MCPX offers to import their server definitions into the new canonical file so you don’t lose your current setup.
  3. Add servers — If no servers were imported in the previous step, an interactive prompt lets you define new MCP servers one by one, specifying the transport (stdio or http), command or URL, arguments, environment variables, and headers.
  4. Select providers — Choose which AI CLI tools you use. MCPX will generate a config file for each selected provider.
  5. Generate — MCPX writes .agents/mcp.json (or ~/.agents/mcp.json) and creates all provider config files in the correct locations.
4

Verify with mcpx status

After the wizard completes, check that every provider config was written successfully:
mcpx status
You will see output similar to:
✔ Claude Code      .mcp.json                          sync
✔ Copilot CLI      .copilot/mcp-config.json           sync
✔ VS Code          .vscode/mcp.json                   sync
5

Add more servers later

To add another MCP server at any time without re-running the full wizard, use the add command:
mcpx add
You can also pass the server name directly:
mcpx add my-api
MCPX will prompt for the remaining fields, update .agents/mcp.json, and regenerate all provider configs automatically.

​
Example canonical config

After completing the wizard your .agents/mcp.json will look similar to this. The file uses the schema defined by McpConfigFileSchema — version, providers, and servers are the three top-level keys. 
{
  "version": 1,
  "providers": ["claude-code", "copilot-cli", "vscode"],
  "servers": {
    "github": {
      "enabled": true,
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-github-server"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    },
    "my-api": {
      "enabled": true,
      "transport": "http",
      "url": "https://mcp.example.com",
      "headers": { "Authorization": "Bearer sk-xxx" }
    }
  }
}
Every server entry requires enabled and transport. For stdio transport the command field is required; for http transport the url field is required. All other fields (args, env, headers) are optional.
If you edit .agents/mcp.json directly — to change an environment variable, toggle a server, or add a new provider — run mcpx sync afterwards to regenerate all provider config files from the updated canonical source.

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us