🔌 MCPX

Uma config para dominar todas. Configure seus servidores MCP uma vez e distribua para todas as CLIs de IA automaticamente.

😩 O Problema

Cada CLI de IA usa um formato de arquivo diferente para configurar servidores MCP (Model Context Protocol):

CLI de IA	Arquivo de Config	Formato
Claude Code	`.mcp.json`	JSON
Gemini CLI	`.gemini/settings.json`	JSON
Kimi CLI	`~/.kimi/mcp.json`	JSON
OpenAI Codex	`.codex/config.toml`	TOML
OpenCode	`opencode.json`	JSON
GitHub Copilot CLI	`.copilot/mcp-config.json`	JSON
VS Code	`.vscode/mcp.json`	JSON
IntelliJ IDEA	`.idea/mcp.json`	JSON

Se voce usa multiplas ferramentas de IA (e provavelmente usa), precisa manter manualmente 8 arquivos de config diferentes com estruturas, nomes de campos e particularidades distintas. Para cada projeto.

✨ A Solucao

O MCPX mantem um unico arquivo canonico (.mcpx.json) por projeto e gera automaticamente o arquivo de config correto para cada provider de IA que voce usa.

.mcpx.json  ──────►  .mcp.json                     (Claude Code)
    │       ──────►  .gemini/settings.json          (Gemini CLI)
    │       ──────►  ~/.kimi/mcp.json               (Kimi CLI)
    │       ──────►  .codex/config.toml             (OpenAI Codex)
    │       ──────►  opencode.json                  (OpenCode)
    │       ──────►  .copilot/mcp-config.json       (Copilot CLI)
    │       ──────►  .vscode/mcp.json               (VS Code)
    └─────  ──────►  .idea/mcp.json                 (IntelliJ IDEA)

🚀 Inicio Rapido

📦 Instalacao

npm install -g mcpx-cli

⚡ Primeira Configuracao

Navegue ate o diretorio do seu projeto e execute:

mcpx

O wizard interativo vai te guiar por:

🔍 Deteccao — Detecta automaticamente configs MCP existentes no seu projeto
📥 Importacao — Oferece importar servidores das configs detectadas
➕ Adicionar servidores — Wizard interativo para configurar novos servidores MCP
🎯 Selecionar providers — Escolha para quais CLIs de IA gerar configs
⚙️ Gerar — Cria o .mcpx.json e todos os arquivos dos providers

📋 Comandos

Comando	Descricao
`mcpx` ou `mcpx init`	🧙 Wizard interativo de configuracao
`mcpx add [nome]`	➕ Adicionar um novo servidor MCP
`mcpx remove [nome]`	➖ Remover um servidor MCP
`mcpx list`	📄 Listar servidores MCP configurados
`mcpx sync`	🔄 Regenerar todos os arquivos de config dos providers
`mcpx import [provider]`	📥 Importar config de um provider existente
`mcpx status`	📊 Mostrar estado de sincronizacao dos providers

🏳️ Flags Globais

Flag	Descricao
`--dir, -d <caminho>`	📁 Diretorio do projeto (padrao: diretorio atual)
`--verbose`	🔊 Exibir logs detalhados
`--version, -V`	🏷️ Exibir versao
`--help, -h`	❓ Exibir ajuda

📐 Formato Canonico

O MCPX usa um unico arquivo .mcpx.json como fonte da verdade:

{
  "version": 1,
  "providers": ["claude-code", "gemini-cli", "openai-codex", "copilot-cli"],
  "servers": {
    "jira": {
      "description": "Jira Atlassian",
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://minhaorg.atlassian.net",
        "JIRA_USERNAME": "usuario@exemplo.com",
        "JIRA_API_TOKEN": "seu-token"
      }
    },
    "github": {
      "description": "GitHub MCP Server",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-github-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

📝 Campos do Servidor

Campo	Tipo	Obrigatorio	Descricao
`transport`	`"stdio"` \| `"http"`	✅ Sim	Protocolo de transporte
`command`	`string`	stdio	Comando executavel
`args`	`string[]`	—	Argumentos do comando
`env`	`Record<string, string>`	—	Variaveis de ambiente
`cwd`	`string`	—	Diretorio de trabalho
`url`	`string`	http	URL do servidor
`headers`	`Record<string, string>`	—	Headers HTTP
`description`	`string`	—	Descricao legivel
`enabled`	`boolean`	—	Ativar/desativar (padrao: `true`)

🤖 Providers Suportados

📁 Providers com Escopo de Projeto

Estes providers geram arquivos de config dentro do diretorio do projeto. Cada projeto tem sua propria config independente.

🟣 Claude Code

Aspecto	Detalhe
Arquivo	`.mcp.json`
Formato	JSON
Chave raiz	`mcpServers`
Exige `type`	Sim `"stdio"`

🔵 Gemini CLI

Aspecto	Detalhe
Arquivo	`.gemini/settings.json`
Formato	JSON
Chave raiz	`mcpServers`
Exige `type`	Nao

🟢 OpenAI Codex

Aspecto	Detalhe
Arquivo	`.codex/config.toml`
Formato	TOML
Chave raiz	`mcp_servers`
Merge inteligente	Sim — Preserva configuracoes existentes do Codex (`model`, `approval_mode`, etc.)

🟠 OpenCode

Aspecto	Detalhe
Arquivo	`opencode.json`
Formato	JSON
Chave raiz	`mcp`
Particularidades	`command` e um array (comando + args juntos), usa `environment` em vez de `env`, `type: "local"`

⚫ GitHub Copilot CLI

Aspecto	Detalhe
Arquivo	`.copilot/mcp-config.json`
Formato	JSON
Chave raiz	`mcpServers`
Particularidades	Exige campo `tools: ["*"]`, precisa de alias no shell para config por projeto

📌 Nota: O Copilot CLI nao detecta automaticamente configs MCP a nivel de projeto. O MCPX configura automaticamente um alias no shell (copilot='copilot --additional-mcp-config @.copilot/mcp-config.json') no seu .zshrc, .bashrc ou config.fish para que a config do projeto seja carregada ao executar copilot.

🔷 VS Code

Aspecto	Detalhe
Arquivo	`.vscode/mcp.json`
Formato	JSON
Chave raiz	`servers`
Particularidades	Campo `type` obrigatorio (`"stdio"` ou `"sse"`), HTTP mapeado como `"sse"`

🟧 IntelliJ IDEA

Aspecto	Detalhe
Arquivo	`.idea/mcp.json`
Formato	JSON
Chave raiz	`mcpServers`
Particularidades	Sem campo `type`, infere pelo `command` vs `url`

🌍 Providers Globais

Estes providers usam um unico arquivo global compartilhado entre todos os projetos. Executar mcpx sync sobrescreve o arquivo global com os servidores do projeto atual.

🔴 Kimi CLI

Aspecto	Detalhe
Arquivo	`~/.kimi/mcp.json`
Formato	JSON
Chave raiz	`mcpServers`
Escopo	Global — afeta todos os projetos

🔄 Sincronizacao e Gerenciamento de Providers

🔁 Sincronizando

Apos modificar o .mcpx.json (manualmente ou via comandos), regenere todas as configs dos providers:

mcpx sync

🔀 Alterando Providers

Use o wizard interativo para adicionar ou remover providers:

mcpx init
# Selecione "Alterar providers"

Quando um provider e removido, o MCPX exclui o arquivo de config correspondente. Para providers globais, arquivos legados a nivel de projeto tambem sao limpos.

📥 Importando de Configs Existentes

Ja tem servidores MCP configurados em uma das suas ferramentas de IA? Importe-os:

mcpx import

O MCPX detecta configs existentes a nivel de projeto (.mcp.json, .gemini/settings.json, etc.) e permite selecionar quais servidores importar para o .mcpx.json.

🏗️ Arquitetura

src/
├── cli.ts                    # Setup Commander e roteamento
├── types/
│   ├── canonical.ts          # McpConfigFile, McpServerConfig (schemas Zod)
│   ├── providers.ts          # Interface Provider
│   └── common.ts             # CommandContext, SyncResult
├── commands/
│   ├── init.ts               # Wizard interativo
│   ├── add.ts / remove.ts    # Gerenciamento de servidores
│   ├── list.ts / status.ts   # Exibicao de informacoes
│   ├── sync.ts               # Regenerar configs
│   └── import.ts             # Importar de providers
├── providers/
│   ├── base.ts               # Interface Provider
│   ├── registry.ts           # Registry de providers (factory)
│   ├── claude-code.ts        # .mcp.json
│   ├── gemini-cli.ts         # .gemini/settings.json
│   ├── kimi-cli.ts           # ~/.kimi/mcp.json
│   ├── openai-codex.ts       # .codex/config.toml
│   ├── opencode.ts           # opencode.json
│   ├── copilot-cli.ts        # .copilot/mcp-config.json
│   ├── vscode.ts             # .vscode/mcp.json
│   └── intellij.ts           # .idea/mcp.json
├── core/
│   ├── config-store.ts       # Leitura/escrita do .mcpx.json
│   ├── detector.ts           # Deteccao de configs existentes
│   └── merger.ts             # Sync inteligente com suporte a merge
├── wizard/
│   ├── main-wizard.ts        # Fluxo interativo principal
│   ├── server-wizard.ts      # Wizard de criacao de servidor
│   ├── provider-wizard.ts    # Selecao de providers
│   └── step-runner.ts        # Navegacao entre etapas (suporte a voltar)
└── utils/
    ├── fs.ts                 # Helpers de filesystem
    ├── logger.ts             # Logger com cores
    └── validation.ts         # Validacao Zod

🧪 Testes

# Rodar todos os testes
npm test

# Rodar uma vez (CI)
npm run test:run

# Checagem de tipos
npm run typecheck

🛠️ Stack Tecnica

Categoria	Biblioteca
💻 Linguagem	TypeScript 5.x (ESM)
📦 Build	tsup (esbuild)
⌨️ CLI Framework	commander
💬 Prompts Interativos	@clack/prompts
🎨 Cores	picocolors
📄 TOML	smol-toml
✅ Validacao	zod
🧪 Testes	vitest
🟢 Node minimo	>= 20

📄 Licenca

MIT

🇺🇸 Read in English (en-US)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🔌 MCPX

😩 O Problema

✨ A Solucao

🚀 Inicio Rapido

📦 Instalacao

⚡ Primeira Configuracao

📋 Comandos

🏳️ Flags Globais

📐 Formato Canonico

📝 Campos do Servidor

🤖 Providers Suportados

📁 Providers com Escopo de Projeto

🟣 Claude Code

🔵 Gemini CLI

🟢 OpenAI Codex

🟠 OpenCode

⚫ GitHub Copilot CLI

🔷 VS Code

🟧 IntelliJ IDEA

🌍 Providers Globais

🔴 Kimi CLI

🔄 Sincronizacao e Gerenciamento de Providers

🔁 Sincronizando

🔀 Alterando Providers

📥 Importando de Configs Existentes

🏗️ Arquitetura

🧪 Testes

🛠️ Stack Tecnica

📄 Licenca

FilesExpand file tree

README.pt-BR.md

Latest commit

History

README.pt-BR.md

File metadata and controls

🔌 MCPX

😩 O Problema

✨ A Solucao

🚀 Inicio Rapido

📦 Instalacao

⚡ Primeira Configuracao

📋 Comandos

🏳️ Flags Globais

📐 Formato Canonico

📝 Campos do Servidor

🤖 Providers Suportados

📁 Providers com Escopo de Projeto

🟣 Claude Code

🔵 Gemini CLI

🟢 OpenAI Codex

🟠 OpenCode

⚫ GitHub Copilot CLI

🔷 VS Code

🟧 IntelliJ IDEA

🌍 Providers Globais

🔴 Kimi CLI

🔄 Sincronizacao e Gerenciamento de Providers

🔁 Sincronizando

🔀 Alterando Providers

📥 Importando de Configs Existentes

🏗️ Arquitetura

🧪 Testes

🛠️ Stack Tecnica

📄 Licenca