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 uses a single JSON file as the source of truth for all your MCP server configuration. For project scope this file lives at .agents/mcp.json inside your project root; for global scope it lives at ~/.agents/mcp.json in your home directory. Every provider-specific config file — Claude Code’s .mcp.json, OpenAI Codex’s .codex/config.toml, VS Code’s .vscode/mcp.json, and the rest — is generated from this one canonical file each time you run mcpx sync or save changes through the interactive wizard.

​
Full example

The following example shows a canonical config file with two stdio servers and one HTTP server, targeting four providers. 
{
  "version": 1,
  "providers": [
    "antigravity-cli",
    "claude-code",
    "copilot-cli",
    "openai-codex"
  ],
  "servers": {
    "github": {
      "enabled": true,
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-github-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    },
    "jira": {
      "enabled": true,
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_API_TOKEN": "your-token",
        "JIRA_URL": "https://myorg.atlassian.net",
        "JIRA_USERNAME": "user@example.com"
      }
    },
    "remote-api": {
      "enabled": true,
      "transport": "http",
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer sk-xxx"
      }
    }
  }
}

​
Top-level fields

​
version
number
required
Schema version. Must be 1. MCPX uses this to validate the file and will reject any file that does not carry a recognized version number.
​
providers
string[]
required
Array of provider IDs that MCPX should generate config files for. Valid values are antigravity-cli, claude-code, copilot-cli, intellij, kimi-cli, openai-codex, opencode, and vscode. MCPX sorts this array alphabetically each time it saves the file.
​
servers
object
required
Map of server names to server configuration objects. Keys are the unique server names you assign (for example "github" or "jira"). Each value must conform to the server schema described below.

​
Server fields

Each entry in servers is an object with the following fields.
​
enabled
boolean
required
Whether the server is active. When set to false the server is kept in the canonical file but omitted from generated provider configs (with the exception of Antigravity CLI, which records it with disabled: true instead of removing it).
​
transport
"stdio" | "http"
required
Transport mechanism used to connect to this server. Use "stdio" for a locally executed process and "http" for a remote endpoint.
​
url
string
The URL of the remote MCP server. Required when transport is "http". Not used for "stdio" servers.
​
headers
object
Map of HTTP header names to values. Only applicable when transport is "http". Use this to pass authorization tokens or other request headers to the remote server.
​
command
string
The executable to run. Required when transport is "stdio". Common values are npx, uvx, node, or a direct binary name.
​
args
string[]
Arguments passed to command. Optional for "stdio" transport, ignored for "http" transport.
​
env
object
Map of environment variable names to values injected into the server process. Only applicable for "stdio" transport. Use this to supply API tokens and other secrets without hard-coding them in command.

​
Transport types

Use "stdio" for any MCP server that runs as a local child process. MCPX launches the process and communicates over standard input/output.
{
  "enabled": true,
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@anthropic-ai/mcp-github-server"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
  }
}
command is required. args and env are optional but commonly used to pass configuration and secrets to the server process.

​
Field ordering

MCPX normalizes the canonical file every time it writes it to disk. This means you should not rely on manual formatting being preserved. The normalization rules are:
  • providers is sorted alphabetically.
  • servers keys are sorted alphabetically by server name.
  • Each server’s fields are written in canonical order: enabled, transport, url, headers, command, args, env. Optional fields that are not set are omitted entirely rather than written as null.
This deterministic output makes version-control diffs clean and predictable.
Server names must be unique within a single config file. If you attempt to add a server with a name that already exists, MCPX will overwrite the existing entry.

Build docs developers (and LLMs) love

Get started for freeTalk to us