MCP Hub

Un servidor administrador para servidores MCP que gestiona procesos y enruta herramientas.

Documentación

MCP Hub

MCP Hub actúa como coordinador central para servidores y clientes MCP, proporcionando dos interfaces clave:

Interfaz de Gestión (/api/*): Gestiona múltiples servidores MCP mediante una API REST unificada y una interfaz web
Interfaz de Servidor MCP (/mcp): Conecta CUALQUIER cliente MCP para acceder a TODAS las capacidades de los servidores a través de un único endpoint

Este enfoque de doble interfaz significa que puedes gestionar servidores a través de la interfaz del Hub mientras que los clientes MCP (Claude Desktop, Cline, etc.) solo necesitan conectarse a un endpoint (localhost:37373/mcp) para acceder a todas las capacidades. Implementa la especificación MCP 2025-03-26.

Soporte de Funciones

Categoría	Función	Soporte	Notas
Transporte
	streamable-http	✅	Protocolo de transporte principal para servidores remotos
	SSE	✅	Transporte de respaldo para servidores remotos
	STDIO	✅	Para ejecutar servidores locales
Autenticación
	OAuth 2.0	✅	Con flujo PKCE
	Cabeceras	✅	Para claves API/tokens
Capacidades
	Herramientas	✅	Listar herramientas
	🔔 Lista de Herramientas Cambiada	✅	Actualizaciones en tiempo real
	Recursos	✅	Soporte completo
	🔔 Lista de Recursos Cambiada	✅	Actualizaciones en tiempo real
	Plantillas de Recursos	✅	Plantillas URI
	Prompts	✅	Soporte completo
	🔔 Lista de Prompts Cambiada	✅	Actualizaciones en tiempo real
	Roots	❌	No soportado
	Sampling	❌	No soportado
	Completion	❌	No soportado
Marketplace
	Descubrimiento de Servidores	✅	Explorar servidores disponibles
	Instalación	✅	Configuración automática
Tiempo Real
	Actualizaciones de Estado	✅	Estado del servidor y de la conexión
	Actualizaciones de Capacidades	✅	Refresco automático
	Transmisión de Eventos a clientes	✅	Basado en SSE
	Reconexión Automática	✅	Con retroceso
Desarrollo
	Recarga en Caliente	✅	Reinicio automático de un servidor MCP al cambiar archivos con modo `dev`
Configuración
	Sintaxis `${}`	✅	Variables de entorno y ejecución de comandos en todos los campos
	Compatibilidad con VS Code	✅	Soporte para la clave `servers`, `${env:}`, `${input:}`, variables predefinidas
	Soporte JSON5	✅	Comentarios y comas finales en archivos de configuración

Configuración Simplificada del Cliente

Configura todos los clientes MCP con solo un endpoint:

{
    "mcpServers" : {
        "Hub": {
            "url" : "http://localhost:37373/mcp"  
        }
    }
}

El Hub automáticamente:

Espacia las capacidades por nombres para prevenir conflictos (ej., filesystem__search vs database__search)
Enruta las solicitudes al servidor apropiado
Actualiza las capacidades en tiempo real cuando se añaden/eliminan servidores
Maneja la autenticación y la gestión de conexiones

Funciones Clave

Endpoint Unificado de Servidor MCP (/mcp):
- Endpoint único para que TODOS los clientes MCP se conecten
- Accede a las capacidades de todos los servidores gestionados a través de una conexión
- El espaciado automático por nombres previene conflictos entre servidores
- Actualizaciones de capacidades en tiempo real cuando cambian los servidores
- Configuración simplificada del cliente: solo un endpoint en lugar de muchos
Gestión Dinámica de Servidores:
- Iniciar, detener, habilitar/deshabilitar servidores bajo demanda
- Actualizaciones de configuración en tiempo real con reconexión automática del servidor
- Soporte para servidores MCP locales (STDIO) y remotos (streamable-http/SSE)
- Monitoreo de salud y recuperación automática
- Autenticación OAuth con flujo PKCE
- Autenticación de token basada en cabeceras
API REST Unificada:
- Ejecuta herramientas desde cualquier servidor conectado
- Accede a recursos y plantillas de recursos
- Actualizaciones de estado en tiempo real mediante Server-Sent Events (SSE)
- Operaciones CRUD completas para la gestión de servidores
Eventos en Tiempo Real y Monitoreo:
- Estado del servidor en vivo y actualizaciones de capacidades
- Seguimiento de conexiones de clientes
- Notificaciones de cambios en listas de herramientas y recursos
- Registro JSON estructurado con salida a archivo
Gestión de Conexiones de Clientes:
- Conexiones simples de clientes basadas en SSE mediante /api/events
- Limpieza automática de conexiones al desconectarse
- Apagado automático opcional cuando no hay clientes conectados
- Monitoreo del estado de conexión en tiempo real
Gestión del Ciclo de Vida de Procesos:
- Manejo elegante de inicio y apagado
- Limpieza adecuada de conexiones de servidores
- Recuperación de errores y reconexión
Gestión del Espacio de Trabajo:
- Seguimiento de instancias activas de MCP Hub en diferentes directorios de trabajo
- Caché global del espacio de trabajo en directorio de estado compatible con XDG
- Actualizaciones del espacio de trabajo en tiempo real mediante eventos SSE
- Endpoints API para listar y monitorear espacios de trabajo activos

Componentes

Servidor Hub

El servidor de gestión principal que:

Mantiene conexiones con múltiples servidores MCP
Proporciona acceso API unificado a las capacidades de los servidores
Maneja el ciclo de vida del servidor y el monitoreo de salud
Gestiona conexiones y eventos SSE de clientes
Procesa actualizaciones de configuración y reconexión de servidores

Servidores MCP

Servicios conectados que:

Proporcionan herramientas, recursos, plantillas y prompts
Soportan dos modos de conectividad:
- Servidores STDIO basados en scripts para operaciones locales
- Servidores remotos (streamable-http/SSE) con soporte OAuth
Implementan actualizaciones de capacidades en tiempo real
Soportan recuperación automática de estado
Mantienen una interfaz consistente entre tipos de transporte

Instalación

npm install -g mcp-hub

Uso Básico

Inicia el servidor hub:

mcp-hub --port 3000 --config path/to/config.json

# Or with multiple config files (merged in order)
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

Opciones CLI

Options:
  --port            Port to run the server on (required)
  --config          Path to config file(s). Can be specified multiple times. Merged in order. (required)
  --watch           Watch config file for changes, only updates affected servers (default: false)
  --auto-shutdown   Whether to automatically shutdown when no clients are connected (default: false)
  --shutdown-delay  Delay in milliseconds before shutting down when auto-shutdown is enabled (default: 0)
  -h, --help       Show help information

Configuración

MCP Hub utiliza archivos de configuración JSON para definir servidores gestionados con sintaxis universal de marcador de posición ${} para variables de entorno y ejecución de comandos.

Compatibilidad con la Configuración de VS Code

MCP Hub proporciona compatibilidad perfecta con el formato de configuración .vscode/mcp.json de VS Code, permitiéndote usar los mismos archivos de configuración tanto en VS Code como en MCP Hub.

Funciones Soportadas

Claves de Configuración del Servidor

Se soportan tanto las claves mcpServers como servers:

{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "perplexity": {
      "command": "npx", 
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "API_KEY": "${env:PERPLEXITY_API_KEY}"
      }
    }
  }
}

Sustitución de Variables

MCP Hub soporta la sustitución de variables estilo VS Code:

Variables de Entorno: ${env:VARIABLE_NAME} o ${VARIABLE_NAME}
Variables del Espacio de Trabajo: ${workspaceFolder}, ${userHome}, ${pathSeparator}
Ejecución de Comandos: ${cmd: command args}

Variables Predefinidas Soportadas:

${workspaceFolder} - Directorio donde se ejecuta mcp-hub
${userHome} - Directorio de inicio del usuario
${pathSeparator} - Separador de rutas del sistema operativo (/ o )
${workspaceFolderBasename} - Solo el nombre de la carpeta
${cwd} - Alias para workspaceFolder
${/} - Abreviatura de VS Code para pathSeparator

Variables de Entrada de VS Code

Para variables ${input:} utilizadas en configuraciones de VS Code, usa la variable de entorno MCP_HUB_ENV:

# Set input variables globally
export MCP_HUB_ENV='{"input:api-key":"your-secret-key","input:database-url":"postgresql://..."}'

# Then use in config
{
  "servers": {
    "myserver": {
      "env": {
        "API_KEY": "${input:api-key}"
      }
    }
  }
}

Migración desde VS Code

Los archivos .vscode/mcp.json existentes funcionan directamente con MCP Hub. Simplemente apunta MCP Hub a tu configuración de VS Code:

mcp-hub --config .vscode/mcp.json --port 3000

Múltiples Archivos de Configuración

MCP Hub soporta la carga de múltiples archivos de configuración que se fusionan en orden. Esto permite una gestión flexible de la configuración:

Configuración Global: Ajustes a nivel de sistema (ej., ~/.config/mcphub/global.json)
Configuración del Proyecto: Ajustes específicos del proyecto (ej., ./.mcphub/project.json)
Configuración del Entorno: Anulaciones específicas del entorno

Cuando se especifican múltiples archivos de configuración, se fusionan con los archivos posteriores anulando a los anteriores:

# Global config is loaded first, then project config overrides
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

Comportamiento de Fusión:

Las secciones mcpServers se fusionan (las definiciones de servidores de archivos posteriores anulan a las anteriores)
Otras propiedades de nivel superior son completamente reemplazadas por archivos posteriores
Los archivos de configuración faltantes se omiten silenciosamente

Sintaxis Universal de Marcador de Posición

${ENV_VAR} o ${env:ENV_VAR} - Resuelve variables de entorno
${cmd: command args} - Ejecuta comandos y usa la salida
${workspaceFolder} - Directorio donde se ejecuta mcp-hub
${userHome} - Directorio de inicio del usuario
${pathSeparator} - Separador de rutas del sistema operativo
${input:variable-id} - Se resuelve desde MCP_HUB_ENV (compatibilidad con VS Code)
null o "" - Retrocede a process.env

Ejemplos de Configuración

Servidor STDIO Local

{
  "mcpServers": {
    "local-server": {
      "command": "${MCP_BINARY_PATH}/server",
      "args": [
        "--token", "${API_TOKEN}",
        "--database", "${DB_URL}",
        "--secret", "${cmd: op read op://vault/secret}"
      ],
      "env": {
        "API_TOKEN": "${cmd: aws ssm get-parameter --name /app/token --query Parameter.Value --output text}",
        "DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
        "DB_PASSWORD": "${cmd: op read op://vault/db/password}",
        "FALLBACK_VAR": null
      },
      "dev": {
        "enabled": true,
        "watch": ["src/**/*.js", "**/*.json"],
        "cwd": "/absolute/path/to/server/directory"
      }
    }
  }
}

Servidor Remoto

{
  "mcpServers": {
    "remote-server": {
      "url": "https://${PRIVATE_DOMAIN}/mcp",
      "headers": {
        "Authorization": "Bearer ${cmd: op read op://vault/api/token}",
        "X-Custom-Header": "${CUSTOM_VALUE}"
      }
    }
  }
}

Opciones de Configuración

MCP Hub soporta tanto servidores STDIO como servidores remotos (streamable-http/SSE). El tipo de servidor se detecta automáticamente desde la configuración. Todos los campos soportan la sintaxis universal de marcador de posición ${}.

Opciones de Servidor STDIO

Para ejecutar servidores MCP basados en scripts localmente:

command: Comando para iniciar el ejecutable del servidor MCP (soporta ${VARIABLE} y ${cmd: command})
args: Matriz de argumentos de línea de comandos (soporta marcadores de posición ${VARIABLE} y ${cmd: command})
env: Variables de entorno con resolución de marcadores de posición y respaldo del sistema
cwd: El directorio de trabajo para el proceso que inicia el servidor MCP
dev: Configuración del modo de desarrollo (opcional)
- enabled: Habilita/deshabilita el modo de desarrollo (predeterminado: true)
- watch: Matriz de patrones glob para vigilar cambios (predeterminado: ["/*.js", "/.ts", "**/.json"])
- cwd: Requerido ruta absoluta al directorio de trabajo del servidor para la vigilancia de archivos

Variables de Entorno Globales (`MCP_HUB_ENV`)

MCP Hub buscará la variable de entorno MCP_HUB_ENV (una cadena JSON) en su propio entorno de proceso. Si está configurada, todos los pares clave-valor de esta variable se inyectarán en el entorno de cada servidor MCP gestionado (tanto stdio como remoto). Esto es útil para pasar secretos, tokens u otra configuración compartida a todos los servidores sin repetirlos en cada configuración de servidor.

Los campos env específicos del servidor siempre anulan los valores de MCP_HUB_ENV.

Ejemplo de uso:

MCP_HUB_ENV='{"DBUS_SESSION_BUS_ADDRESS":"/run/user/1000/bus","MY_TOKEN":"abc"}' mcp-hub --port 3000 --config path/to/config.json

Opciones de Servidor Remoto

Para conectarse a servidores MCP remotos:

url: URL del endpoint del servidor (soporta marcadores de posición ${VARIABLE} y ${cmd: command})
headers: Cabeceras de autenticación (soporta marcadores de posición ${VARIABLE} y ${cmd: command})

Detección del Tipo de Servidor

El tipo de servidor se determina por:

Servidor STDIO → Tiene campo command
Servidor remoto → Tiene campo url

Nota: Una configuración de servidor no puede mezclar campos de servidor STDIO y remoto.

Orden de Resolución de Marcadores de Posición

Comandos Primero: ${cmd: command args} se ejecutan primero
Variables de Entorno: ${VAR} se resuelven desde el objeto env, luego process.env
Respaldo: Los valores null o "" retroceden a process.env
Múltiples Pasadas: Las dependencias entre variables se resuelven automáticamente

Nix

Instalación con Nixpkgs

próximamente...

Instalación con Flake

Solo añádelo a tu flake.nix de NixOS o home-manager:

inputs = {
  mcp-hub.url = "github:ravitemer/mcp-hub";
  ...
}

Para integrar mcp-hub en tu configuración de NixOS/Home Manager, añade lo siguiente a tu environment.systemPackages o home.packages respectivamente:

inputs.mcp-hub.packages."${system}".default

Uso sin instalación

Si quieres usar mcphub.nvim sin tener el servidor mcp-hub en tu PATH, puedes enlazar el servidor internamente añadiendo la ruta del store de nix de mcp-hub al comando cmd en la configuración del plugin como

Ejemplo de Nixvim:

{ mcphub-nvim, mcp-hub, ... }:
{
  extraPlugins = [mcphub-nvim];
  extraConfigLua = ''
    require("mcphub").setup({
        port = 3000,
        config = vim.fn.expand("~/mcp-hub/mcp-servers.json"),
        cmd = "${mcp-hub}/bin/mcp-hub"
    })
  '';
}

# where
{
  # For nixpkgs (not available yet)
  mcp-hub = pkgs.mcp-hub;

  # For flakes
  mcp-hub = inputs.mcp-hub.packages."${system}".default;
}

Ejemplos de Integración

Integración con Neovim

El plugin ravitemer/mcphub.nvim proporciona una integración perfecta con Neovim, permitiendo la interacción directa con MCP Hub desde tu editor:

Ejecuta herramientas MCP directamente desde Neovim
Accede a recursos MCP dentro de tu flujo de trabajo de edición
Actualizaciones de estado en tiempo real en Neovim
Instalación automática de servidores MCP con adición al marketplace

API REST

Salud y Estado

Verificación de Salud

GET /api/health

El endpoint de salud proporciona información completa de estado que incluye:

Estado actual del hub (iniciando, listo, reiniciando, reiniciado, deteniendo, detenido, error)
Estados y capacidades de los servidores conectados
Detalles de conexiones SSE activas
Métricas detalladas de conexión
Detalles del estado de error si corresponde

Respuesta:

{
  "status": "ok",
  "state": "ready",
  "server_id": "mcp-hub",
  "version": "4.1.1",
  "activeClients": 2,
  "timestamp": "2024-02-20T05:55:00.000Z",
  "servers": [],
  "connections": {
    "totalConnections": 2,
    "connections": [
      {
        "id": "client-uuid",
        "state": "connected",
        "connectedAt": "2024-02-20T05:50:00.000Z",
        "lastEventAt": "2024-02-20T05:55:00.000Z"
      }
    ]
  },
  "workspaces": {
    "current": "40123",
    "allActive": {
      "40123": {
        "cwd": "/path/to/project-a",
        "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
        "pid": 12345,
        "port": 40123,
        "startTime": "2025-01-17T10:00:00.000Z",
        "state": "active",
        "activeConnections": 2,
        "shutdownStartedAt": null,
        "shutdownDelay": null
      }
    }
  }
}

Listar Servidores MCP

GET /api/servers

Obtener Información del Servidor

POST /api/servers/info
Content-Type: application/json

{
  "server_name": "example-server"
}

Actualizar capacidades del servidor

POST /api/servers/refresh
Content-Type: application/json

{
  "server_name": "example-server"
}

Respuesta:

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "capabilities": {
      "tools": ["tool1", "tool2"],
      "resources": ["resource1", "resource2"],
      "resourceTemplates": []
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Actualizar todos los servidores

POST /api/refresh

Respuesta:

{
  "status": "ok",
  "servers": [
    {
      "name": "example-server",
      "capabilities": {
        "tools": ["tool1", "tool2"],
        "resources": ["resource1", "resource2"],
        "resourceTemplates": []
      }
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Iniciar servidor

POST /api/servers/start
Content-Type: application/json

{
  "server_name": "example-server"
}

Respuesta:

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "connected",
    "uptime": 123
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Detener servidor

POST /api/servers/stop?disable=true|false
Content-Type: application/json

{
  "server_name": "example-server"
}

El parámetro de consulta opcional disable puede establecerse en true para deshabilitar el servidor en la configuración.

Respuesta:

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "disconnected",
    "uptime": 0
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Gestión de espacios de trabajo

Listar espacios de trabajo activos

GET /api/workspaces

Respuesta:

{
  "workspaces": {
    "40123": {
      "cwd": "/path/to/project-a",
      "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
      "pid": 12345,
      "port": 40123,
      "startTime": "2025-01-17T10:00:00.000Z",
      "state": "active",
      "activeConnections": 2,
      "shutdownStartedAt": null,
      "shutdownDelay": null
    },
    "40567": {
      "cwd": "/path/to/project-b",
      "config_files": ["/home/user/.config/mcphub/global.json"],
      "pid": 54321,
      "port": 40567,
      "startTime": "2025-01-17T10:05:00.000Z",
      "state": "shutting_down",
      "activeConnections": 0,
      "shutdownStartedAt": "2025-01-17T10:15:00.000Z",
      "shutdownDelay": 600000
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Integración con el mercado

Listar servidores disponibles

GET /api/marketplace

Parámetros de consulta:

search: Filtrar por nombre, descripción o etiquetas
category: Filtrar por categoría
tags: Filtrar por etiquetas separadas por comas
sort: Ordenar por "newest", "stars" o "name"

Respuesta:

{
  "servers": [
    {
      "id": "example-server",
      "name": "Example Server",
      "description": "Description here",
      "author": "example-author",
      "url": "https://github.com/user/repo",
      "category": "search",
      "tags": ["search", "ai"],
      "stars": 100,
      "featured": true,
      "verified": true,
      "lastCommit": 1751257963,
      "updatedAt": 1751265038
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Obtener detalles del servidor

POST /api/marketplace/details
Content-Type: application/json

{
  "mcpId": "example-server"
}

Respuesta:

{
  "server": {
    "id": "example-server",
    "name": "Example Server",
    "description": "Description here",
    "author": "example-author",
    "url": "https://github.com/user/repo",
    "category": "search",
    "tags": ["search", "ai"],
    "installations": [],
    "stars": 100,
    "featured": true,
    "verified": true,
    "lastCommit": 1751257963,
    "updatedAt": 1751265038
  },
  "readmeContent": "# Server Documentation...",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Operaciones del servidor MCP

Ejecutar herramienta

POST /api/servers/tools
Content-Type: application/json

{
  "server_name": "example-server",
  "tool": "tool_name",
  "arguments": {},
  "request_options" : {}
}

Acceder a recurso

POST /api/servers/resources
Content-Type: application/json

{
  "server_name": "example-server",
  "uri": "resource://uri",
  "request_options" : {}
}

Obtener prompt

POST /api/servers/prompts
Content-Type: application/json

{
  "server_name": "example-server",
  "prompt": "prompt_name",
  "arguments": {},
  "request_options" : {}
}

Respuesta:

{
  "result": {
    "messages": [
      {
        "role": "assistant",
        "content": {
          "type": "text",
          "text": "Text response example"
        }
      },
      {
        "role": "assistant",
        "content": {
          "type": "image",
          "data": "base64_encoded_image_data",
          "mimeType": "image/png"
        }
      }
    ]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Reiniciar el Hub

POST /api/restart

Recarga el archivo de configuración y reinicia todos los servidores MCP.

Respuesta:

{
  "status": "ok",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Sistema de eventos en tiempo real

MCP Hub implementa un sistema integral de eventos en tiempo real utilizando Server-Sent Events (SSE) en /api/events. Este endpoint proporciona actualizaciones en vivo sobre el estado de los servidores, cambios de configuración, actualizaciones de capacidades y más.

Estados del Hub

El servidor del Hub transita por varios estados durante su ciclo de vida:

Estado	Descripción
`starting`	Inicio inicial, cargando configuración
`ready`	El servidor está en ejecución y listo para manejar solicitudes
`restarting`	Recargando configuración/reconectando servidores
`restarted`	Recarga de configuración completada
`stopping`	Apagado gradual en curso
`stopped`	El servidor se ha detenido por completo
`error`	Estado de error (incluye detalles del error)

Puede monitorear estos estados a través del endpoint /health o mediante eventos SSE.

Tipos de eventos

MCP Hub emite varios tipos de eventos:

Eventos principales

heartbeat - Verificación periódica de salud de la conexión

{
  "connections": 2,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

hub_state - Cambios en el estado del servidor del Hub

{
  "state": "ready",
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "pid": 12345,
  "port": 3000,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

log - Mensajes de registro del servidor

{
  "type": "info",
  "message": "Server started",
  "data": {},
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Eventos de suscripción

config_changed - Cambios detectados en el archivo de configuración

{
  "type": "config_changed",
  "newConfig": {},
  "isSignificant": true,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

servers_updating - Actualizaciones de servidores en curso

{
  "type": "servers_updating",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

servers_updated - Actualizaciones de servidores completadas

{
  "type": "servers_updated",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

tool_list_changed - Lista de herramientas del servidor actualizada

{
  "type": "tool_list_changed",
  "server": "example-server",
  "tools": ["tool1", "tool2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

resource_list_changed - Recursos/plantillas del servidor actualizados

{
  "type": "resource_list_changed",
  "server": "example-server",
  "resources": ["resource1", "resource2"],
  "resourceTemplates": [],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

prompt_list_changed - Lista de prompts del servidor actualizada

{
  "type": "prompt_list_changed",
  "server": "example-server",
  "prompts": ["prompt1", "prompt2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

workspaces_updated - Espacios de trabajo activos cambiados

{
  "type": "workspaces_updated",
  "workspaces": {
    "40123": {
      "cwd": "/path/to/project-a",
      "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
      "pid": 12345,
      "port": 40123,
      "startTime": "2025-01-17T10:00:00.000Z",
      "state": "active",
      "activeConnections": 2,
      "shutdownStartedAt": null,
      "shutdownDelay": null
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Gestión de conexiones

Cada conexión SSE recibe un ID único
Las conexiones se limpian automáticamente al desconectarse el cliente
Estadísticas de conexión disponibles a través del endpoint /health
Apagado automático opcional cuando no hay clientes conectados

Registro de eventos

MCP Hub utiliza registro JSON estructurado para todos los eventos. Los registros se escriben tanto en consola como en archivo siguiendo la Especificación de Directorio Base XDG:

Cumplimiento XDG: $XDG_STATE_HOME/mcp-hub/logs/mcp-hub.log (típicamente ~/.local/state/mcp-hub/logs/mcp-hub.log)
Respaldo heredado: ~/.mcp-hub/logs/mcp-hub.log (para compatibilidad hacia atrás)

Ejemplo de entrada de registro:

{
  "type": "error",
  "code": "TOOL_ERROR",
  "message": "Failed to execute tool",
  "data": {
    "server": "example-server",
    "tool": "example-tool",
    "error": "Invalid parameters"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Los niveles de registro incluyen:

info: Mensajes operativos normales
warn: Condiciones de advertencia
debug: Información de depuración detallada (incluye cambios de configuración)
error: Condiciones de error (incluye código de error y traza de pila)

Los registros se rotan diariamente y se conservan durante 30 días por defecto.

Caché de espacios de trabajo

MCP Hub mantiene una caché global de espacios de trabajo para rastrear instancias activas en diferentes directorios de trabajo con gestión de ciclo de vida en tiempo real:

Ubicación de la caché: $XDG_STATE_HOME/mcp-hub/workspaces.json (típicamente ~/.local/state/mcp-hub/workspaces.json)
Propósito: Previene conflictos de puertos, permite el descubrimiento de espacios de trabajo y proporciona seguimiento del ciclo de vida en tiempo real
Contenido: Mapea números de puerto (como claves) a información del proceso del Hub con estado detallado del ciclo de vida
Limpieza: Elimina automáticamente entradas obsoletas cuando los procesos ya no están en ejecución

Estructura de la caché

{
  "40123": {
    "cwd": "/path/to/project-a",
    "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
    "pid": 12345,
    "port": 40123,
    "startTime": "2025-01-17T10:00:00.000Z",
    "state": "active",
    "activeConnections": 2,
    "shutdownStartedAt": null,
    "shutdownDelay": null
  },
  "40567": {
    "cwd": "/path/to/project-b", 
    "config_files": ["/home/user/.config/mcphub/global.json"],
    "pid": 54321,
    "port": 40567,
    "startTime": "2025-01-17T10:05:00.000Z",
    "state": "shutting_down",
    "activeConnections": 0,
    "shutdownStartedAt": "2025-01-17T10:15:00.000Z",
    "shutdownDelay": 600000
  }
}

Manejo de errores

MCP Hub implementa un sistema integral de manejo de errores con clases de error personalizadas para diferentes tipos de errores:

Clases de error

ConfigError: Errores relacionados con la configuración (configuración inválida, campos faltantes)
ConnectionError: Problemas de conexión del servidor (conexiones fallidas, errores de transporte)
ServerError: Problemas de inicio/inicialización del servidor
ToolError: Fallos en la ejecución de herramientas
ResourceError: Problemas de acceso a recursos
ValidationError: Errores de validación de solicitudes

Cada error incluye:

Código de error para identificación fácil
Mensaje de error detallado
Contexto adicional en el objeto de detalles
Traza de pila para depuración

Ejemplo de estructura de error:

{
  "code": "CONNECTION_ERROR",
  "message": "Failed to communicate with server",
  "details": {
    "server": "example-server",
    "error": "connection timeout"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Arquitectura

Ciclo de vida del servidor del Hub

sequenceDiagram
    participant C as Client
    participant H as Hub Server
    participant M1 as MCP Server 1
    participant M2 as MCP Server 2

    Note over H: Server Start (state: starting)
    activate H
    
    Note over H: Config Loading
    H->>H: Load & Validate Config
    H->>H: Watch Config File
    H->>H: Initialize SSE Manager
    
    Note over H: Server Connections (state: ready)
    H->>+M1: Connect
    M1-->>-H: Connected + Capabilities
    H->>+M2: Connect
    M2-->>-H: Connected + Capabilities
    H-->>C: hub_state (ready)

    Note over C,H: Client Setup
    C->>H: Connect to /api/events (SSE)
    H-->>C: connection_opened
    
    Note over C,H: Client Operations
    C->>H: Execute Tool (HTTP)
    H->>M1: Execute Tool
    M1-->>H: Tool Result
    H-->>C: HTTP Response
    
    Note over H,C: Real-time Updates
    H->>H: Detect Config Change
    H-->>C: servers_updating (SSE)
    H->>M1: Reconnect with New Config
    M1-->>H: Updated Capabilities
    H-->>C: servers_updated (SSE)

    Note over H,C: Server Events
    M2->>H: Tool List Changed
    H-->>C: tool_list_changed (SSE)
    
    Note over H: Shutdown Process
    Note over C,H: Client Disconnects
    H-->>C: hub_state (stopping) (SSE)
    H->>M1: Disconnect
    H->>M2: Disconnect
    H-->>C: hub_state (stopped) (SSE)
    deactivate H

El servidor del Hub coordina la comunicación entre clientes y servidores MCP:

Inicia y se conecta a los servidores MCP configurados
Maneja conexiones SSE de clientes y eventos
Enruta solicitudes de herramientas y recursos a los servidores apropiados
Monitorea la salud del servidor y mantiene las capacidades
Gestiona procesos de inicio/apagado gradual

Gestión de servidores MCP

flowchart TB
    A[Hub Server Start] --> B{Config Available?}
    B -->|Yes| C[Load Server Configs]
    B -->|No| D[Use Default Settings]
    
    C --> E[Initialize Connections]
    D --> E
    
    E --> F{For Each MCP Server}
    F -->|Enabled| G[Attempt Connection]
    F -->|Disabled| H[Skip Server]
    
    G --> I{Connection Status}
    I -->|Success| J[Fetch Capabilities]
    I -->|Failure| K[Log Error]
    
    J --> L[Store Server Info]
    K --> M[Mark Server Unavailable]
    
    L --> N[Monitor Health]
    M --> N
    
    N --> O{Health Check}
    O -->|Healthy| P[Update Capabilities]
    O -->|Unhealthy| Q[Attempt Reconnect]
    
    Q -->|Success| P
    Q -->|Failure| R[Update Status]
    
    P --> N
    R --> N

El servidor del Hub gestiona activamente los servidores MCP mediante:

Inicialización de servidores basada en configuración
Descubrimiento de conexiones y capacidades
Monitoreo de salud y seguimiento de estado
Intentos automáticos de reconexión
Gestión del estado del servidor

Manejo de solicitudes

sequenceDiagram
    participant C as Client
    participant H as Hub Server
    participant M as MCP Server
    
    Note over C,H: Tool Execution
    C->>H: POST /api/servers/tools (HTTP)
    H->>H: Validate Request & Server
    
    alt Server Not Connected
        H-->>C: 503 Server Unavailable (HTTP)
    else Server Connected
        H->>M: Execute Tool
        
        alt Success
            M-->>H: Tool Result
            H-->>C: Result Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Resource Access
    C->>H: POST /api/servers/resources (HTTP)
    H->>H: Validate URI & Template
    
    alt Invalid Resource
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Request Resource
        
        alt Success
            M-->>H: Resource Data
            H-->>C: Resource Content (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Prompt Execution
    C->>H: POST /api/servers/prompts (HTTP)
    H->>H: Validate Prompt & Args
    
    alt Invalid Prompt
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Execute Prompt
        
        alt Success
            M-->>H: Messages Array
            H-->>C: Messages Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end

Todas las solicitudes de clientes siguen un flujo estandarizado:

Validación de la solicitud
Verificación del estado del servidor
Enrutamiento de la solicitud al servidor MCP apropiado
Manejo de respuestas y gestión de errores

Requisitos

Node.js >= 18.0.0

Registro MCP

MCP Hub ahora utiliza el sistema de Registro MCP para la funcionalidad de mercado. Esto proporciona:

Descubrimiento descentralizado de servidores: Registro alojado en GitHub Pages para mayor confiabilidad
Integración directa con GitHub: Documentación README obtenida directamente de los repositorios
Metadatos mejorados: Información completa del servidor incluyendo estrellas, categorías e instrucciones de instalación
Mejor caché: Sistema de caché mejorado con TTL de 1 hora para actualizaciones frecuentes
Soporte de respaldo: Respaldo automático a curl cuando fetch falla (útil para entornos proxy/VPN)

El registro se actualiza regularmente con nuevos servidores y mejoras a las entradas existentes.

Pendientes

Implementar mercado personalizado en lugar de depender de mcp-marketplace
TUI como mcphub.nvim
Interfaz web para gestionar servidores

Agradecimientos

ravitemer/mcp-registry - Por proporcionar los endpoints del mercado de servidores MCP que impulsan la integración de mercado de MCP Hub

MCP Hub

Documentación

MCP Hub

Soporte de Funciones

Configuración Simplificada del Cliente

Funciones Clave

Componentes

Servidor Hub

Servidores MCP

Instalación

Uso Básico

Opciones CLI

Configuración

Compatibilidad con la Configuración de VS Code

Funciones Soportadas

Claves de Configuración del Servidor

Sustitución de Variables

Variables de Entrada de VS Code

Migración desde VS Code

Múltiples Archivos de Configuración

Sintaxis Universal de Marcador de Posición

Ejemplos de Configuración

Servidor STDIO Local

Servidor Remoto

Opciones de Configuración

Opciones de Servidor STDIO

Variables de Entorno Globales (MCP_HUB_ENV)

Opciones de Servidor Remoto

Detección del Tipo de Servidor

Orden de Resolución de Marcadores de Posición

Nix

Instalación con Nixpkgs

Instalación con Flake

Uso sin instalación

Ejemplos de Integración

Integración con Neovim

API REST

Salud y Estado

Verificación de Salud

Listar Servidores MCP

Obtener Información del Servidor

Actualizar capacidades del servidor

Actualizar todos los servidores

Iniciar servidor

Detener servidor

Gestión de espacios de trabajo

Listar espacios de trabajo activos

Integración con el mercado

Listar servidores disponibles

Obtener detalles del servidor

Operaciones del servidor MCP

Ejecutar herramienta

Acceder a recurso

Obtener prompt

Reiniciar el Hub

Sistema de eventos en tiempo real

Estados del Hub

Tipos de eventos

Eventos principales

Eventos de suscripción

Gestión de conexiones

Registro de eventos

Caché de espacios de trabajo

Estructura de la caché

Manejo de errores

Clases de error

Arquitectura

Ciclo de vida del servidor del Hub

Gestión de servidores MCP

Manejo de solicitudes

Requisitos

Registro MCP

Pendientes

Agradecimientos

Variables de Entorno Globales (`MCP_HUB_ENV`)