mcp-core ⚡️

Gateway MCP — un único punto de entrada para todos tus servidores

mcp-core pone una sola entrada en cada cliente de IA (Cursor, Claude Desktop, VS Code…) y desde ahí expone todos los servidores MCP que tengas instalados. En lugar de que cada cliente gestione sus propias conexiones, hay un daemon central que mantiene una instancia por servidor — compartida entre todos los clientes.

El cliente ve herramientas prefijadas por servidor: context7__get_library_docs, playwright__browser_navigate, mcp_core__install_server, etc. Al instalar un servidor nuevo, aparece en todos los clientes automáticamente sin tocar ningún archivo de configuración.

⚡ Quick Start

# 1) Instala el paquete
npm install -g @agarpac/mcp-core

# 2) Inyecta el gateway en todos los clientes detectados. Pregunta, por cada
#    servidor MCP que ya tuvieras, si migrarlo al registro central o dejarlo
#    conectado directo al cliente. Deja un `.backup` de cada config.
mcp-core init -i

Sin -i no pregunta: migra todos. Si es una instalación limpia, sin servidores previos, ambos hacen lo mismo.

Con eso ya funciona. El daemon arranca solo cuando el primer cliente conecta y queda vivo en segundo plano; no hace falta reiniciar el cliente si soporta tools/list_changed.

Opcionales:

mcp-core install @modelcontextprotocol/server-memory  # añadir un servidor MCP
mcp-core migrate --dry-run                            # mover servidores a ~/.mcp-core/servers/
mcp-core ui                                           # dashboard web

Con mise (o asdf / nvm)

Cambian dos cosas: el paquete necesita una exención para instalarse, y los clientes deben apuntar al shim en vez de al PATH.

1) Declara el paquete en ~/.config/mise/config.toml. Requiere mise 2026.7.14+:

[tools]
"npm:@agarpac/mcp-core" = { version = "latest", allow_low_downloads = true }

allow_low_downloads es obligatorio: aube rechaza los paquetes por debajo de 1000 descargas semanales. Afecta solo a este paquete.

2) Instala y apunta los clientes al shim:

mise install
mcp-core init -i --self-binary ~/.local/share/mise/shims/mcp-core-mcp

El flag se pasa una sola vez: la ruta queda en init.selfBinary y los init siguientes la reutilizan.

Con asdf o nvm, sustituye el shim por la ruta absoluta equivalente. No uses la del PATH (.../installs/node/<versión>/bin): cambia al actualizar node y las apps GUI no la ven.

Si acabas de publicar una versión y mise install sigue trayendo la anterior, es la cuarentena minimum_release_age. Pide la exacta: mise install npm:@agarpac/mcp-core@<versión>.

🏗️ Arquitectura

 Cursor           Claude Desktop       VS Code
   │ stdio             │ stdio            │ stdio
   ▼                   ▼                  ▼
mcp-core-mcp       mcp-core-mcp       mcp-core-mcp   ← gateway shim (1 por cliente)
   │                   │                  │
   │         UNIX socket                  │
   ▼                   ▼                  ▼
┌────────────────────────────────────────────────┐
│              mcp-daemon (1 proceso)            │
│  ┌─────────────┐  ┌────────────────┐           │
│  │server-memory│  │server-filesyst.│  …        │
│  └─────────────┘  └────────────────┘           │
└────────────────────────────────────────────────┘

Gateway shim (mcp-core-mcp): binario MCP ligero. Se conecta al daemon, suscribe a cambios de backends y reexpone todas las tools/resources/prompts con prefijo (<backend>__<name>). Si el daemon no está corriendo, lo arranca automáticamente.
Daemon: supervisa y multiplexa backends MCP. Cuando el gateway conecta, arranca todos los backends configurados para descubrir sus capabilities. Si un backend lleva ~5 minutos sin recibir llamadas, el daemon mata su proceso automáticamente para ahorrar RAM (las capabilities quedan en caché para relanzarlo al instante). Notifica a todos los shims cuando se instala o desinstala un servidor — los clientes que soportan list_changed reciben las nuevas tools sin reiniciar.
CLI (mcp-core): instalar, desinstalar, migrar, inicializar y lanzar el dashboard.

Prefijado de capabilities

Capability	Prefijo	Ejemplo
Tools	`<backend>__<name>`	`memory__store`, `mcp_core__list_servers`
Resources	URI `mcp-core://<backend>/<uri>`	`mcp-core://filesystem/file:///foo`
Prompts	`<backend>__<name>`	`github__create_issue`

Las 5 tools de control del gateway viven bajo el prefijo mcp_core__: install_server, uninstall_server, list_servers, toggle_client, get_daemon_status.

💻 Clientes soportados

mcp-core init detecta e inyecta la entrada del gateway automáticamente en:

Cliente	Path (macOS)	Path (Linux)	Clave raíz
Cursor	`~/.cursor/mcp.json`	`~/.cursor/mcp.json`	`mcpServers`
VS Code / Copilot	`~/Library/Application Support/Code/User/mcp.json`	`~/.config/Code/User/mcp.json`	`servers`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`	—	`mcpServers`
Claude Code	`~/.claude.json`	`~/.claude.json`	`mcpServers`
OpenCode (cli)	`~/.config/opencode/opencode.json`	`~/.config/opencode/opencode.json`	`mcp`
Codex / ChatGPT Desktop	`~/.codex/config.toml`	`~/.codex/config.toml`	`mcp_servers`

Codex: el archivo ~/.codex/config.toml (formato TOML) lo comparten la CLI de Codex y la pestaña Codex de la app ChatGPT Desktop; una sola entrada cubre ambos. El chat normal de ChatGPT queda fuera de alcance: es remoto y no se automatiza mediante un archivo local.

Windows: fuera del alcance actual.

🛠️ Comandos (CLI)

# Bootstrap del gateway: inyecta mcp-core en todos los clientes y migra entradas legacy
mcp-core init [--clients cursor,claudeCode] [-i|--interactive] [--self-binary <path>]

# Instalar un servidor MCP
mcp-core install <npm-pkg | git-url | uvx-pkg> [opciones]
  --name <alias>              alias del servidor
  --env KEY=value             variable de entorno (repetible)
  --method auto|npm|uvx|git   método de instalación (por defecto: auto)
  --no-validate               saltarse el handshake MCP de verificación

# Desinstalar un servidor
mcp-core uninstall <server-name>

# Migrar servidores legacy al directorio gestionado por mcp-core
mcp-core migrate [--dry-run]

# Estado: daemon, servidores registrados y su estado en vivo, runtimes
mcp-core status

# Comandos del daemon
mcp-core daemon stop
mcp-core daemon restart
mcp-core daemon logs [server-name] [-f] [-n <N>]

# Dashboard web local
mcp-core ui

Instalación de paquetes npm

Para paquetes npm, mcp-core install descarga e instala el paquete en ~/.mcp-core/servers/node_modules/ (un node_modules compartido entre todos los servidores). El binario se resuelve automáticamente desde el package.json del paquete:

✅ Installed server-memory
   Validated: 9 tools (154ms)

El comando almacenado apunta al path local: node ~/.mcp-core/servers/node_modules/@modelcontextprotocol/server-memory/dist/index.js. No depende de npm ni de red tras la instalación. Al desinstalar, se ejecuta npm uninstall para limpiar el node_modules compartido.

Environment variables

mcp-core install @modelcontextprotocol/server-github \
  --env GITHUB_TOKEN=ghp_xxx

Soporte uvx (Python)

--method uvx fuerza el runner; auto lo detecta para paquetes con prefijo mcp-server-:

mcp-core install mcp-server-postgres --env DATABASE_URL=postgres://localhost/mydb

init interactivo (`-i` / `--interactive`)

Por defecto, mcp-core init es autónomo: migra todos los servidores MCP no-gateway de cada cliente al registro central sin preguntar. Con -i (o --interactive) el comando pregunta, una vez por cada MCP encontrado, si quieres Migrar a mcp-core (opción por defecto) o Dejar directo (lo sigue gestionando el cliente, fuera de mcp-core).

mcp-core init -i

Los servidores que marques como «Dejar directo» se guardan en init.preserveDirect del config global (~/.mcp-core/config.json); el resto del flujo autónomo se ejecuta igual y los deja intactos en la configuración del cliente. Cada nombre se pregunta una sola vez aunque aparezca en varios clientes, y los nombres que ya estén en init.preserveDirect no se vuelven a preguntar. Si cancelas (Ctrl-C / ESC) no se realiza ningún cambio. El modo interactivo requiere un terminal (TTY); si la salida está redirigida (CI, pipes) el comando falla con error en lugar de migrarlo todo sin preguntar, que sería justo lo contrario de lo que pediste con -i.

`--self-binary`

Escribe una ruta absoluta en la configuración de los clientes en lugar del nombre mcp-core-mcp resuelto por PATH. Necesario cuando el binario no está en un directorio visible para todo el sistema — ver Con mise.

mcp-core init --self-binary /ruta/absoluta/a/mcp-core-mcp

La ruta debe ser absoluta, existir y ser ejecutable; si no, el comando falla sin tocar ninguna configuración.
Se guarda en init.selfBinary (~/.mcp-core/config.json) y los init siguientes la reutilizan. Para cambiarla, vuelve a pasar el flag; para desactivarla, borra esa clave.
Solo con init.selfBinary definido reescribe init una entrada de gateway existente. Sin él respeta la que haya, así que una configuración editada a mano no se pierde.

init.preserveDirect

Por defecto, mcp-core init migra todos los servidores MCP no-gateway de cada cliente al registro central. init.preserveDirect es una lista global de nombres de servidor que deben quedar conectados directamente al cliente en lugar de migrarse. Los servidores cuya clave de configuración coincida con una entrada de esta lista nunca se importan al registro y permanecen intactos en la configuración del cliente, junto a la entrada del gateway mcp-core inyectada.

Configúralo en ~/.mcp-core/config.json:

{ "init": { "preserveDirect": ["codegraph"] } }

Los nombres se comparan con la clave del servidor tal como aparece en la configuración del cliente. La semántica es solo-proteger: preserveDirect únicamente evita migraciones futuras. No elimina ni revierte un servidor que ya fue migrado al registro en una ejecución anterior de init; para revertir esos, usa manualmente mcp-core uninstall <server-name>.

El comando mcp-core migrate también obvia los servidores listados en preserveDirect: aunque estuvieran en el registro, no se reinstalan en ~/.mcp-core/servers/, respetando la intención de mantenerlos conectados directamente al cliente.

mcp-core migrate

Si tenías servidores MCP configurados directamente en los clientes (Cursor, VS Code, etc.) antes de instalar mcp-core, el comando init los importa al registro central conservando su comando original, que puede seguir apuntando a un node_modules externo.

mcp-core migrate detecta estos servidores y los reinstala correctamente en ~/.mcp-core/servers/, haciéndolos independientes de esos clientes:

# Ejecutar la migración
mcp-core migrate

Antes de migrar, usa --dry-run para ver exactamente qué se haría sin tocar nada. Es útil para revisar qué paquetes se instalarán y qué servidores se omitirán, sin riesgo:

mcp-core migrate --dry-run

Ejemplo de salida:

Servers to migrate to ~/.mcp-core/servers/:

  context7            npm install @upstash/context7-mcp
  playwright          npm install @playwright/mcp

Skipped:

  engram              (not an npm package (system binary or local path))

🎉 Migration complete. 2 migrated, 0 failed.

Los servidores de tipo sistema (Homebrew, binarios del PATH) se omiten automáticamente — mcp-core no toca lo que no instaló.

🎨 Web Dashboard

mcp-core ui levanta un Express en loopback con token aleatorio. Ábrelo en el navegador con la URL que imprime en consola y ciérralo con Ctrl+C cuando no lo necesites.

Secciones

System Panel — OS, Node, estado del daemon y grid de runtimes detectados.
Advanced Installer — instalar con stream SSE de progreso en tiempo real.
Active MCP Servers — lista de backends registrados con:
- Estado en vivo (polling cada 5s): ● running proceso activo, ● cached proceso parado pero capabilities en memoria (se relanza automáticamente al recibir la primera llamada), ● idle sin proceso y sin capabilities (solo ocurre antes del primer arranque del daemon en una sesión).
- Running from — comando exacto que usa el daemon para arrancar el servidor.
- Health — handshake MCP bajo demanda: muestra número de tools y, al hacer click, la lista de nombres.
- Logs — últimas 100 líneas del stderr del servidor en un modal.
- Re-validate / Uninstall — validación manual y desinstalación con confirmación.
AI Clients — detecta automáticamente los clientes de IA instalados (Cursor, VS Code, Claude Code, Codex…) y muestra si el gateway está inyectado en cada uno.

La UI está endurecida contra DNS rebinding: bind a 127.0.0.1, validación de Host:, CORS whitelist, token Bearer obligatorio.

Endpoints de la API

Método	Ruta	Descripción
GET	`/api/system`	Estado del sistema, runtimes y ruta del config
GET	`/api/servers`	Servidores registrados
GET	`/api/clients`	Clientes de IA detectados con estado del gateway
GET	`/api/daemon/status`	Ping al daemon + PID + uptime
GET	`/api/daemon/active-servers`	Procesos activos y backends en caché en el daemon
GET	`/api/logs/:name?lines=N`	Últimas N líneas del log de stderr de un servidor
GET	`/api/events`	SSE stream de progreso
POST	`/api/install`	`{ source, name?, env?, method?, validate? }`
POST	`/api/uninstall`	`{ name }`
POST	`/api/validate`	`{ name }` → `{ success, tools, toolNames, latencyMs }`

📂 Directorios

~/.mcp-core/
├── config.json          # Registro central de servidores MCP
├── daemon.sock          # UNIX socket gateway ↔ daemon
├── daemon.pid           # PID lock
├── logs/                # Stderr de cada backend (un .log por servidor)
└── servers/             # Paquetes npm instalados localmente
    ├── package.json     # Dependencias npm compartidas
    └── node_modules/    # node_modules compartido entre todos los servidores

🧪 Desarrollo

git clone <repo> && cd mcp-core
npm run setup       # install + build + npm link
npx vitest run      # Suite completa (258 tests)

npm run setup deja los dos binarios (mcp-core, mcp-core-mcp) disponibles en el PATH.

Licencia

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
dashboard		dashboard
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
ui-preview2.png		ui-preview2.png
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

mcp-core ⚡️

⚡ Quick Start

Con mise (o asdf / nvm)

🏗️ Arquitectura

Prefijado de capabilities

💻 Clientes soportados

🛠️ Comandos (CLI)

Instalación de paquetes npm

Environment variables

Soporte uvx (Python)

init interactivo (`-i` / `--interactive`)

`--self-binary`

init.preserveDirect

mcp-core migrate

🎨 Web Dashboard

Secciones

Endpoints de la API

📂 Directorios

🧪 Desarrollo

Licencia

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

mcp-core ⚡️

⚡ Quick Start

Con mise (o asdf / nvm)

🏗️ Arquitectura

Prefijado de capabilities

💻 Clientes soportados

🛠️ Comandos (CLI)

Instalación de paquetes npm

Environment variables

Soporte uvx (Python)

init interactivo (-i / --interactive)

--self-binary

init.preserveDirect

mcp-core migrate

🎨 Web Dashboard

Secciones

Endpoints de la API

📂 Directorios

🧪 Desarrollo

Licencia

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

init interactivo (`-i` / `--interactive`)

`--self-binary`