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 gives you a single canonical config file — .agents/mcp.json — and automatically generates the correct config format for every AI tool you use. This guide takes you from a fresh installation to a fully-configured project with working provider files for Claude Code, GitHub Copilot, VS Code, and more.
Prerequisites
  • Node.js >= 20 (check with node --version)
  • A project directory you want to configure
  • At least one supported AI tool installed: Claude Code, GitHub Copilot CLI, VS Code, Kimi CLI, Antigravity CLI, OpenAI Codex, OpenCode, or IntelliJ IDEA
1
Install MCPX
2
Install the CLI globally from GitHub:
3
npm install -g github:davidpastorvicente/mcpx-cli
4
Verify the installation:
5
mcpx --version
7
Move into the directory you want to configure:
8
cd my-project
9
Run the interactive wizard
10
Launch the wizard by running mcpx with no arguments:
11
mcpx
12
MCPX immediately prompts you to choose a scope:
13
  • Project — stores config in .agents/mcp.json inside your project folder (recommended for per-project servers)
  • Global — stores config in ~/.agents/mcp.json for your user account (if you run mcpx from your home directory, MCPX selects global scope automatically)
    • 14
    If MCPX finds existing provider config files in the directory (e.g. an existing .mcp.json from Claude Code), it shows you what it detected and asks whether to import those servers — select Yes to bring them in automatically.
    15
    If no existing configs are detected, the wizard enters server setup mode. For each server you add, you’ll be asked:
    16
  • Server name — a short identifier like github, jira, or my-server (letters, numbers, hyphens, dots, and underscores)
  • Transport type — stdio for a local command, or http for a remote server URL
  • Command / URL — the executable to run (stdio) or the server URL (http)
  • Arguments — comma-separated args passed to the command (stdio only; leave blank for none)
  • Environment variables — key/value pairs added to the server’s env map (stdio); or Headers — key/value pairs sent with every request (http)
    • 17
    After configuring at least one server, the wizard asks you to select providers — the AI tools you want MCPX to generate config files for. Use the spacebar to toggle each one, then press Enter.
    18
    Finally, confirm the summary and MCPX writes .agents/mcp.json and all selected provider files.
    19
    Inspect the result
    20
    Open .agents/mcp.json to see your canonical config:
    21
    {
  "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"
      }
    }
  }
}
    22
    MCPX also created a provider config file for each selected provider. For the example above you would see:
    23
    ProviderGenerated fileClaude Code.mcp.jsonGitHub Copilot CLI.copilot/mcp-config.jsonVS Code.vscode/mcp.json
    24
    Each file uses the correct format, field names, and structure required by that tool — you don’t need to touch them.
    25
    Verify all providers are in sync
    26
    mcpx status
    27
    This compares each provider file against what MCPX would generate from .agents/mcp.json and reports one of three states per provider:
    28
  • sync — the file matches exactly
  • desync — the file exists but differs (e.g. you edited it manually)
  • missing — the file has not been created yet
    • 29
    All providers should show sync immediately after the wizard completes. If anything shows desync or missing, run mcpx sync to regenerate all provider files.

    ​
    Example: adding a stdio server (npx-based GitHub server)

    Here is what the wizard looks like when adding an npx-based GitHub MCP server: 
    ✔ MCP server name › github
✔ Transport type › stdio  (local command)
✔ Command › npx
✔ Arguments › -y, @anthropic-ai/mcp-github-server
✔ Add environment variables? › Yes
✔ Variable name › GITHUB_PERSONAL_ACCESS_TOKEN
✔ Value for GITHUB_PERSONAL_ACCESS_TOKEN › ghp_xxx
✔ Add another variable? › No
    The resulting entry written to .agents/mcp.json: 
    "github": {
  "enabled": true,
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@anthropic-ai/mcp-github-server"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
  }
}

    ​
    Example: adding an http server with an authorization header

    For a remote MCP server that requires a bearer token, choose http transport: 
    ✔ MCP server name › my-remote-server
✔ Transport type › http  (remote server)
✔ Server URL › https://mcp.example.com/api
✔ Add headers? › Yes
✔ Header name › Authorization
✔ Value for Authorization › Bearer my-secret-token
✔ Add another header? › No
    The resulting entry in .agents/mcp.json: 
    "my-remote-server": {
  "enabled": true,
  "transport": "http",
  "url": "https://mcp.example.com/api",
  "headers": {
    "Authorization": "Bearer my-secret-token"
  }
}
    Commit .agents/mcp.json to version control so your team shares the same server roster. If any env values or header values contain real secrets, add the generated provider files (e.g. .mcp.json, .vscode/mcp.json) to .gitignore — MCPX can regenerate them at any time with mcpx sync.
    You don’t need to cd into a project first. Use --dir (or -d) to point MCPX at any directory:
    mcpx --dir /path/to/my-project

    Build docs developers (and LLMs) love

    Get started for freeTalk to us