conduit-mcp

Servidor MCP remoto que sirve de fachada para múltiples integraciones SaaS tras tres meta-herramientas. En lugar de exponer más de cien herramientas a cada cliente, el servidor expone list_integrations, find_tools e invoke_tool: los clientes buscan en el catálogo por descripción de la tarea, reciben los esquemas de herramientas que coinciden e invocan por nombre exacto. Un portal de administración gestiona los plugins, las claves de API, los roles y el uso.

Integraciones incluidas: HaloPSA, Hudu, CIPP, NinjaRMM, QuickBooks Online.

estructura

Related MCP server: production-grade-mcp-agentic-system

cómo ejecutar

Requiere node >= 22 y pnpm mediante corepack (versión fijada en packageManager de package.json).

corepack enable
scripts/setup.ps1    # or setup.sh: frozen-lockfile install + full workspace build
pnpm dev

pnpm dev lo ejecuta todo en una sola terminal con concurrently, con prefijo de salida por proceso: azurite (almacenamiento de tablas en memoria), los watchers de tsc del sdk y del servidor, el servidor de API y next dev. Ctrl+C lo detiene todo. pnpm serve se salta los watchers y sirve únicamente la API precompilada y la exportación web estática.

• portal: http://localhost:3000 (next dev, hace de proxy de las apis Llamadas hacia :4000)

• api + mcp: http://localhost:4000 (/healthz, /mcp)

Sin configuración, el servidor arranca sin configurar y el portal muestra el asistente de configuración inicial, que guía por el registro de la app de entra. Para omitirlo, copia .dev.env.example a .dev.env y presiembra ENTRA_TENANT_ID / ENTRA_CLIENT_ID / BOOTSTRAP_ADMIN_OID; pnpm dev lo carga en el arranque.

Comprobaciones en todo el repositorio: pnpm lint, pnpm typecheck, pnpm test, pnpm build.

cómo funciona

superficie mcp. /mcp habla HTTP streamable. Las solicitudes autentican con un token de portador de entra o con una clave de API de conduit. Para los clientes que solo hablan OAuth, el servidor hace de proxy de autorizaciones a entra (metadatos del servidor de autorización + registro dinámico de clientes). Las sesiones y los flujos de eventos persisten en el almacenamiento de tablas, así que los flujos sobreviven las reconexiones.

catálogo y meta-herramientas. Cada herramienta de plugin se indexa en un catálogo buscable (minisearch). find_tools devuelve los esquemas de las herramientas coincidentes, invoke_tool ejecuta por nombre exacto y registra el uso. Los permisos filtran tanto los resultados de búsqueda como las invocaciones; por lo tanto, una entidad de seguridad solo ve las herramientas que sus concesiones permiten.

plugins Un plugin es un directorio de origen con el manifiesto conduit.plugin.json (identificar, entrada, nombres de secretos, configuración de ui del portal, rutas públicas públicas). El cargador empaqueta la entrada con esbuild en tiempo de carga contra el SDK del host, registra sus herramientas en el catálogo y monta las rutas del portal bajo /api/plugins/:pluginId. Los paquetes en packages/plugins se siembran automáticamente; pueden instalar más de los git desde el portal. docs/writing-plugins.md cubre la creación de un plugin contra el SDK y la instalación de uno personalizado.

modelo de acceso. Las entidades o princentidades son usuarios de entra o claves de API. Los roles tienen permisos por integración (solo lectura o total, hasta herramientas individuales) y se resuelven en cada solicitud; el acceso al portal es otro plano separado; los roles del portal nunca amplían el acceso a las herramientas mcp. BOOTSTRAP_ADMIN_OID siembra el primer admin.

almacenamiento y secretos. El almacenamiento de tablas de azure mantiene todo el estado (configuración, registro de plugins, roles, claves de API, uso, sesiones mcp); azurite hace de soporte localmente. Los secretos van al key vault de AZURE_KEYVAULT_URL, en caso contrario, variables de entorno simples.

portal. el portal siguiente.js se exporta como sitio estático y lo sirve el propio servidor de API en producción (apps/web/out); en modo watch local ejecuta next dev en su lugar.

despliegue

El Dockerfile crea una imagen de servidor autocontenida con la exportación web incorporada. La CI (.github/workflows/deploy.yml) ejecuta los tests y luego compila y publica la imagen ghcr.io/<owner>/<repo>:<sha> en cada push a main. Solo en la primera publicación: el paquete viene como privado por defecto, así que cambia a visible Público en Ajustes del repositorio > Paquetes para que el app service pueda descargarlo sin credenciales del registro.

infra/main.bicep (ámbito de suscripción) aprovisiona el grupo de recursos, el app service, el storage y el key vault. La inscripción de la app de la wray se hace de dos maneras:

Asistente de configuración, una sola ejecución de bicep. Despliega en blanco los parámetros de entra y abre el portal: el asistente de bootstrap te identifica con el código de dispositivo, crea el registro de la app through graph y escribe los ids de tenant/id de cliente en el servicio de configuración. /api/setup/* no se autentica hasta que se completa la configuración y el primer que se identifica se convierte en admin (confianza en el primer uso); la puerta de configuración responde con 404 a esos endpoints después.

Mediante scripts, dos ejecuciones de bicep. No sin open window setup, el servidor arranca ya configurado. El script de entra necesita las salidas de la ejecución 1 (url de la webapp para los uri de redirección, nombre de key vault para el secreto de cliente), y bicep no puede crear registros de app por sí mismo; por eso se hace una segunda ejecución para dejar las ids como app settings configura.

# 1. infra, entra params blank. operatorObjectId grants the KV write step 2 needs
az deployment sub create -l eastus2 -f infra/main.bicep \
  -p image=ghcr.io/<owner>/conduit-mcp:<sha> bootstrapAdminOid=<your-oid> operatorObjectId=<your-oid>

# 2. app registration + client secret into key vault
#    PS7, az login as a user with Application.ReadWrite.OwnedBy, -DryRun to preview
./infra/scripts/setup-entra-app.ps1 -DisplayName "conduit-mcp" \
  -ProdUrl <webAppUrl output> -KeyVaultName <keyVaultName output>

# 3. same deployment plus the ids the script printed
az deployment sub create -l eastus2 -f infra/main.bicep \
  -p image=ghcr.io/<owner>/conduit-mcp:<sha> bootstrapAdminOid=<your-oid> operatorObjectId=<your-oid> \
     entraTenantId=<tenant-id> entraClientId=<client-id>

El cambio de app settings reinicia el contenedor; el arranque siembra los ids en el almacén de configuración (solo rellena los campos vacíos; el put de configuración sigue siendo la fuente de autoridad).

Despliegue continuo opcional. crea una federación oidc para el workflow, y se ponen los secretos AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_SUBSCRIPTION_ID y lasvariables AZURE_WEBAPP_NAME / AZURE_RESOURCE_GROUP, además pon la variable de repo AZURE_DEPLOY=true. A partir de cada push a main, la webapp se apunta a la imagen recién subida.

Actualizaciones dentro del portal. Los ajustes muestran si la imagen del registro difiere de la compilación en ejecución (la CI hornea el sha de git en la imagen) y pueden reiniciar la app para descargarla; el reinicio usa un rol personalizado de solo reinicio concedido a la identidad administrada por el bicep, así que los despliegues con anterioridad a la existencia de ese rol necesitan volver a ejecutar bicep para que el botón funcione.