ControlDB MCP — servidor de metadata

Servidor MCP local que expone la metadata de gobierno de una organización de ControlDB como herramientas y recursos de solo lectura. No accede a datos ni a credenciales: todo pasa por la API REST /api/mcp/* del servidor ControlDB, autenticada con la llave de la organización.

Requisitos

• Una llave MCP de la organización. Se crea desde el producto (sección de gobierno de datos), la genera quien tenga el permiso metadata.manage, y se muestra una sola vez (empieza por cdbm_).

Uso

El comando detecta el contexto solo:

• En tu terminal (npx controldb-mcp) abre el explorador interactivo para revisar la metadata a mano.
• Lanzado por un cliente de IA (con la E/S por tuberías) arranca como servidor MCP por stdio.

Sin instalar nada:

npx controldb-mcp

O instálalo una vez y ejecútalo como comando en cualquier terminal (Windows, macOS, Linux):

npm install -g controldb-mcp
controldb-mcp

Para el modo servidor (lo habitual es que lo lance el cliente de IA) se configura por entorno:

| Variable | Descripción | | --- | --- | | CONTROLDB_MCP_URL | URL del panel de ControlDB (la misma con la que entras en el navegador). | | CONTROLDB_MCP_KEY | Llave de la organización (cdbm_...). |

Explorador interactivo (para una persona)

npx controldb-mcp en una terminal abre una interfaz a pantalla completa: verifica la conexión, muestra el alcance de la llave y ofrece un menú de herramientas con selección por flechas. La llave se teclea oculta y por defecto NO se guarda; solo se persiste en ~/.controldb-mcp.json si aceptas "recordar en este equipo" (--reset la olvida). Si la llave fue revocada o regenerada, la validación lo detecta y te la vuelve a pedir. El propio explorador entrega el comando y el JSON de configuración listos para pegar en tu cliente de IA.

Ejemplo de configuración en un cliente MCP

{
  "mcpServers": {
    "controldb": {
      "command": "npx",
      "args": ["-y", "controldb-mcp"],
      "env": {
        "CONTROLDB_MCP_URL": "https://controldb.tu-empresa.com",
        "CONTROLDB_MCP_KEY": "cdbm_..."
      }
    }
  }
}

Herramientas

| Herramienta | Qué hace | | --- | --- | | listar_conexiones | Conexiones (bases) monitoreadas de la organización. | | listar_tablas | Tablas de una conexión con tamaño y estado de catalogación/gobierno. | | describir_tabla | Columnas, tipos, claves y comentarios + metadata de negocio de una tabla. | | buscar_metadata | Busca tablas/columnas por nombre técnico, de negocio o descripción. | | evaluar_gobierno | Resumen de gobierno y lista de vacíos (sin documentar, PII sin clasificar, desfases). | | sugerir_clasificacion | Sugiere clasificación de PII de columnas aún sin clasificar. | | confirmar_datalake | Perfil de una conexión (nº de tablas, volumen, tablas más grandes). | | proyectar_plan_gobierno | Plan priorizado de mejora del gobierno con proyección de score. |

Recursos

• controldb://inventario — inventario de conexiones (JSON).
• controldb://gobierno — resumen de gobierno de datos (JSON).

Seguridad

• La llave solo habilita lectura de metadata de una organización; nunca datos ni credenciales.
• Cada llamada queda auditada en la organización y está sujeta a límite de peticiones por llave.
• Revoca una llave desde el producto en cualquier momento; deja de funcionar al instante.