Servidor MCP de Dashboard Builder

Permite que un cliente de IA descubra tus conjuntos de datos y cree paneles en Dashboard Builder.

Se comunica con la aplicación Next.js por HTTP como un cliente API ordinario, por lo que cada guardia de permisos, política de dependencias y regla de validación de la aplicación sigue aplicándose. Nada cambia en la aplicación principal.

Se puede ejecutar de dos maneras:

El modo alojado es el despliegue normal y es lo que cubre este documento. El modo local es para desarrollar el propio servidor, o para identidad por usuario, y se encuentra en DEVELOPMENT.md.

Para usuarios: conectarse a un servidor alojado

Necesitas dos cosas de quien lo haya desplegado: la URL y tu clave de acceso. Nada que clonar, sin archivos que apuntar, sin .env.

Añade esto a claude_desktop_config.json (Claude Desktop) o .mcp.json (Claude Code):

{
  "mcpServers": {
    "dashboard-builder": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.yourcompany.com/mcp",
        "--header", "Authorization: Bearer YOUR_KEY_HERE",
        "--header", "X-Dashboard-Username: you",
        "--header", "X-Dashboard-Password: your-dashboard-password"
      ]
    }
  }
}

mcpServers es una clave de nivel superior, hermana de preferences — no anidada dentro de ella. Sal de Claude Desktop desde la bandeja del sistema y vuelve a abrirlo; cerrar la ventana no es suficiente.

Con las dos cabeceras X-Dashboard-* presentes, el servidor inicia sesión como tú automáticamente en el primer uso y de nuevo cada vez que la sesión expire — no hay nada más que hacer, y cada llamada actúa como tú: tus permisos, tu rastro de auditoría. La contrapartida es que tu contraseña de panel se encuentra en este archivo de configuración y viaja (por HTTPS) con cada solicitud. Si la contraseña contiene caracteres fuera de ASCII, usa el enlace curl de abajo — las cabeceras HTTP no los transportan de forma fiable.

Alternativa: vincular una vez con curl, mantener la contraseña fuera de la configuración

Omite las dos cabeceras X-Dashboard-* y en su lugar vincula tu clave una vez — la contraseña se usa para ese único inicio de sesión y nunca se almacena en ningún sitio; el servidor conserva solo los tokens de sesión resultantes, exactamente como un navegador guarda las cookies:

curl -X POST https://mcp.yourcompany.com/auth/bind \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
  -H "content-type: application/json" \
  -d '{"username":"you","password":"your-dashboard-password"}'

La diferencia con la ruta de cabeceras: cuando la cadena de sesión finalmente expire, vuelves a ejecutar este comando, mientras que las cabeceras se re-vinculan automáticamente. DELETE /auth/bind con la misma cabecera Authorization cierra la sesión de la clave en cualquier caso.

Alice's Claude ──[gate key]──> MCP server ──[Alice's session cookies]──> Dashboard API
                     ^                                ^
              client config              bound via credential headers or
                                         POST /auth/bind; refreshed
                                         automatically after that

Si una clave nunca se vincula, las llamadas a herramientas fallan con un error que explica el paso de vinculación — o, cuando el servidor está configurado con una cuenta de servicio heredada, caen en esa identidad compartida.

mcp-remote es un pequeño puente que se ejecuta localmente y reenvía al servidor, por lo que Node debe estar instalado en la máquina del usuario. Para evitar incluso eso, Configuración → Conectores → Añadir conector personalizado de Claude Desktop acepta una URL directamente sin nada local — esa ruta espera OAuth en lugar de una clave estática, y la disponibilidad varía según la versión de Desktop.

Desplegando el servidor

server.js es el archivo de inicio. Escucha en PORT como un server.js de Next.js, y pone una barrera de clave API delante de cada solicitud MCP para que los llamadores no autenticados sean rechazados antes de que algo llegue al sistema de paneles.

Endpoints: POST /mcp (protegido), POST /auth/bind y DELETE /auth/bind (protegidos — vinculan o desvinculan la identidad de panel de la clave que llama), y GET /health (abierto, para la comprobación de salud de la plataforma). Todo lo demás devuelve 404.

Variables de entorno

Requeridas — el servidor no arrancará sin ellas

Genera claves con openssl rand -hex 24. La etiqueta antes de los dos puntos aparece en los registros y en los cubos de límite de velocidad; el secreto en sí nunca se registra. Revoca a una persona eliminando su entrada y reiniciando — y elimina su archivo de sesión en ~/.dashboard-mcp/sessions/ para eliminar también la identidad vinculada.

Cada clave se vincula luego a una cuenta de panel por su titular mediante POST /auth/bind — ver la sección de usuarios arriba. Ninguna credencial de panel vive en el entorno del servidor.

Respaldo heredado opcional — una cuenta de servicio compartida

Cuando se establece, las claves que no se han vinculado actúan como esta cuenta compartida en lugar de fallar — al igual que una clave cuya vinculación ha expirado, hasta que se vuelva a vincular. Útil durante la migración; omítelo para nuevos despliegues para que cada llamador tenga su propia identidad.

Muy recomendado

Deja DASHBOARD_MCP_PERSIST_SESSION en su valor predeterminado (true): las vinculaciones se almacenan un archivo por clave y sobreviven a los reinicios. Ponerlo en false mantiene las vinculaciones solo en memoria, por lo que cada reinicio — y cada worker en un host multi-worker — necesita su propio re-vinculado.

MCP_ALLOWED_HOSTS y MCP_ALLOWED_ORIGINS son opcionales — el servidor se ejecuta sin ellos y la barrera de clave API sigue aplicándose. Establecer cualquiera de ellos activa la protección contra rebinding de DNS del transporte. Deja ambos sin establecer y el registro de inicio lo dice explícitamente.

Opcionales

Variables de ajuste adicionales — ruta del archivo de sesión, tiempo de espera de solicitud, límites de respuesta y la anulación del id de tipo de panel — están documentadas en línea en .env.example, que está organizado por modo y lista cada variable que el servidor lee.

Nota sobre múltiples workers

Las vinculaciones son un archivo por clave, y un worker cuyo token en memoria ha sido rotado por otro worker se recupera releyendo ese archivo, que el worker ganador ya ha actualizado. La ventana de fallo es que dos workers refresquen el mismo token al mismo instante; el perdedor se recupera en su siguiente intento, y en el peor caso la clave debe volver a vincularse. El transporte MCP en sí es sin estado, por lo que las solicitudes pueden aterrizar en cualquier worker.

Configuración de Plesk

Añade a las directivas nginx adicionales del dominio:

proxy_buffering off;
proxy_read_timeout 300s;

MCP responde como Server-Sent Events y nginx almacena en búfer las respuestas proxy por defecto. Sin proxy_buffering off las solicitudes parecen colgarse en lugar de fallar, lo cual es una forma confusa de perder una tarde.

Mantén el puerto de Node fuera del firewall público. El nginx de Plesk hace proxy hacia él y establece X-Forwarded-For, que es lo que hace que las IPs de cliente registradas sean fiables.

Acceso versus identidad

La clave de acceso controla el acceso; la identidad proviene de la vinculación. La clave permite al llamador pasar la barrera, y la sesión vinculada a esa clave decide quién ve el panel — sus permisos, su rastro de auditoría. Los dos están deliberadamente separados: rotar el secreto de una clave elimina su vinculación (la sesión se archiva bajo el digest de la clave), y revocar una clave elimina el acceso sin tocar la cuenta.

La vinculación funciona como un inicio de sesión de navegador. POST /auth/bind ejecuta el /api/auth/login real de la aplicación una vez, la contraseña se descarta después del intercambio, y solo se conserva la sesión de token de refresco rotatorio — un archivo por clave, modo 0600. Debido a que la aplicación rota el token de refresco en cada uso, un archivo de sesión filtrado muere rápidamente; porque la contraseña nunca se almacena, no hay nada de larga duración que filtrar. La contrapartida: cuando una cadena de refresco expira o se rompe, esa clave se re-vincula con un curl.

Una credencial estable por solicitud (ApiKey en el sistema principal, o OAuth) eliminaría incluso ese re-vinculado, pero requiere cambios en la aplicación principal. Este diseño deliberadamente no necesita ninguno.

Desarrollar o ejecutarlo localmente

Ejecutar el servidor en tu propia máquina — para desarrollo, o para identidad por usuario sin alojamiento — está documentado por separado en DEVELOPMENT.md.

Herramientas

Notas de diseño

Disciplina de contexto. Toda la superficie de las herramientas ocupa unos 3,6 KB — 13 descripciones más las instrucciones del servidor —, por lo que resulta económico mantenerla cargada. Las respuestas son texto compacto en lugar de JSON en bruto, y cada lista se cierra con una nota explícita sobre lo que se ha omitido. get_dashboard omite deliberadamente las configuraciones de los widgets; pides un widget concreto por su id cuando necesitas su configuración.

Revelación progresiva. Una configuración de gráfico tiene unos 59 campos. Incluir eso en una descripción de herramienta dominaría el contexto del cliente en cada solicitud, así que describe_widget_kind sirve el contrato bajo demanda: nombres de campos, tipos, notas, un ejemplo mínimo funcional y — la parte útil — una configuración real extraída de un widget existente de ese tipo en tu propio espacio de trabajo. Copiar una forma que ya se renderiza es mejor que inventar una a partir de los nombres de los campos.

El servidor se encarga de la geometría. Los modelos no son fiables en el empaquetado 2D. add_widget acepta una sugerencia de size (small, medium, large, full) y encuentra por sí mismo la primera celda libre sin solapamientos en la cuadrícula de 12 columnas. arrange_dashboard en modo auto reempaqueta un panel completo.

Fallar antes de la API, no después. La aplicación almacena las configuraciones de los widgets como JSON opaco, así que una clave mal escrita produce un widget en blanco en lugar de un error. add_widget valida primero la configuración contra el contrato del tipo — claves obligatorias, nombres de agregación válidos, field presente cuando la agregación necesita uno — y devuelve una lista específica de lo que falta.

Los widgets coinciden con lo que crearía la UI. La paleta de la aplicación inicializa cada widget nuevo con el defaultConfig del tipo procedente del registro (config === undefined ? def.defaultConfig : config). add_widget replica ese comportamiento: los valores predeterminados del tipo se apilan por debajo de lo que proporcione el llamante, de modo que un gráfico creado por MCP incorpora la misma línea base de paginationMode y maxPoints que uno construido a mano, en lugar de una configuración dispersa a la que el renderizador tenga que recurrir. El objeto fusionado es lo que se valida.

Fusionar en lugar de reenviar. PATCH /widgets/:id reemplaza el objeto de configuración por completo. update_widget fusiona por defecto tus claves con la configuración existente, así que cambiar un ajuste no implica reenviarla por completo.

Fallar en modo cerrado al arrancar. El servidor HTTP se niega a arrancar sin al menos una entrada en MCP_API_KEYS y rechaza las claves de menos de 24 caracteres. Un endpoint MCP sin autenticar nunca debería ser posible por accidente. Las claves se comparan como resúmenes SHA-256 con timingSafeEqual, y solo se registran las etiquetas.

Limitaciones conocidas

• **El catá