delinea-mcp

DelineaMCP

Servidor MCP para las APIs de Delinea Secret Server y Platform

---

Novedades

• 11 Ago 2026 — El protocolo MCP v2 (revisión de especificación 2026-07-28, HTTP transmisible) y el soporte experimental de la API de StrongDM ya están aquí — consulte las notas de la versión.
• 11 Ago 2026 — Somos los proveedores originales del caso de uso de bóveda "sin visibilidad de secretos para el LLM" — cuidado con los imitadores ;)

---

Características

• Autenticación automática contra Secret Server
• Amplio conjunto de herramientas de Secret Server para gestionar carpetas, secretos, usuarios, grupos y roles. Incluye ayudantes de bandeja de entrada y solicitudes de acceso, y utilidades para agentes de codificación.
• Herramientas de compatibilidad con ChatGPT (search y fetch) para interacciones controladas con IA.
• Herramientas opcionales de gestión de usuarios de Delinea Platform
• Herramientas opcionales experimentales de StrongDM (SDM) — concesiones de acceso, auditorías de derechos, ciclo de vida de usuarios/roles, informes de salud y actividad (consulte docs/strongdm.md; instale con pip install "delinea-mcp[strongdm]")
• HTTP transmisible (/mcp), Server-Sent Events heredado (/mcp/sse) y transportes STDIO
• OAuth 2.0 con registro dinámico de clientes según la especificación MCP
• Soporte TLS para conexiones seguras
• Imagen Docker lista para ejecutar y punto de entrada del servidor de desarrollo
• Probado con ChatGPT, Claude Desktop, conector remoto de Claude, VSCode Copilot y openwebui

Instalación

[!NOTE]

Este proyecto utiliza uv (https://github.com/astral-sh/uv), pero si prefiere ejecutar comandos sin esto, puede hacer los comandos pip y venv como de costumbre si lo desea.

• Instalar Uv
• Inicializar el proyecto: uv pip sync requirements.txt
• Usar uv run server.py --config config.json

Configuración

Los secretos como contraseñas continúan proveniendo de variables de entorno. Proporcione DELINEA_PASSWORD en su entorno de shell. Las características opcionales dependen de variables adicionales como AZURE_OPENAI_KEY o PLATFORM_SERVICE_PASSWORD.

Los parámetros no secretos pertenecen a config.json:

{
  "delinea_username": "<username>",
  "delinea_base_url": "https://your-secret-server/SecretServer",
  "platform_hostname": "<tenant>.secureplatform.io",
  "platform_service_account": "<service_account>",
  "platform_tenant_id": "<tenant_id>",
  "azure_openai_endpoint": "https://example.openai.azure.com/",
  "azure_openai_deployment": "<deployment_name>",
  "auth_mode": "none",
  "transport_mode": "stdio",
  "chatgpt_disable_scope_checks": false,
  "port": 8000,
  "debug": false,
  "external_hostname": null,
  "ssl_keyfile": null,
  "ssl_certfile": null,
  "registration_psk": null,
  "jwt_key_path": ".cache/jwt.json",
  "oauth_db_path": ".cache/oauth.db",
  "enabled_tools": []
}

Para Secret Server Cloud simplemente use la URL de la nube sin /SecretServer. Especifique ssl_keyfile y ssl_certfile para habilitar HTTPS. Para Let's Encrypt, use los archivos privkey.pem y fullchain.pem.

El archivo de configuración admite las siguientes claves:

• delinea_username - Nombre de usuario de Secret Server. Debe ser un usuario programático con permiso para realizar las tareas que desee.
• delinea_base_url - URL base de su instancia de Secret Server.
• platform_hostname - Nombre de host del tenant de Platform (habilita las herramientas de Platform).
• platform_service_account - Cuenta de servicio utilizada con la API de Platform.
• platform_tenant_id - ID de tenant para solicitudes a la API de Platform.
• strongdm_api_host - Plano de control de StrongDM (predeterminado app.strongdm.com:443; variantes UK/EU disponibles). Las credenciales provienen de las variables de entorno SDM_API_ACCESS_KEY / SDM_API_SECRET_KEY; consulte docs/strongdm.md.
• azure_openai_endpoint - Punto de conexión de Azure OpenAI. Solo si desea la generación automática de informes (la mayoría de los agentes pueden generar su propio SQL de informes, así que no lo habilite a menos que lo necesite).
• azure_openai_deployment - Nombre de implementación para Azure OpenAI.
• auth_mode - Modo de autenticación (none o oauth). OAuth obviamente no funciona con el transporte stdio.
• transport_mode - stdio para línea de comandos o sse para HTTP. En modo sse el servidor expone tanto el punto de conexión HTTP transmisible en /mcp (transporte MCP actual, sirve revisiones de protocolo 2024-11-05 hasta 2026-07-28) como los puntos de conexión HTTP+SSE heredados en /mcp/sse + /messages/.
• streamable_http_stateless - predeterminado true; ejecute /mcp sin sesiones del lado del servidor (recomendado para conectores remotos). Establezca false para habilitar la operación basada en sesiones con el flujo GET independiente.
• streamable_http_json_response - predeterminado true; responda con JSON simple en lugar de respuestas con marco SSE en /mcp.
• chatgpt_disable_scope_checks - Omita la validación de alcance en solicitudes de ChatGPT. Habilite solo si encuentra problemas al conectarse a ChatGPT.
• port - Puerto para el servidor HTTP en modo sse.
• debug - Habilite el registro detallado.
• external_hostname - Nombre de host utilizado al construir audiencias de tokens OAuth. No agregue prefijo HTTP(S) ni puerto.
• ssl_keyfile - Ruta a la clave SSL para HTTPS. (ej. privkey.pem)
• ssl_certfile - Ruta al certificado SSL para HTTPS. (ej. fullchain.pem)
• registration_psk - Clave precompartida requerida para registrar clientes OAuth. Deberá escribir este secreto en su navegador para aprobar conexiones OAuth.
• jwt_key_path - Ubicación del par de claves RSA utilizado para tokens OAuth. Predeterminado a .cache/jwt.json. autogenerado si no existe.
• oauth_db_path - Ruta al archivo de base de datos OAuth. Predeterminado a .cache/oauth.db. autogenerado si no existe.
• enabled_tools - Lista de nombres de herramientas a registrar. Una lista vacía habilita todas las herramientas. Se recomienda encarecidamente habilitar herramientas selectivamente según el caso de uso o la tarea. Consulte la carpeta docs/ para algunos ejemplos.
• search_objects - Tipos de objetos permitidos para la herramienta search. Predeterminado a ["secret"] pero puede incluir user, folder, group y role.
• fetch_objects - Tipos de objetos permitidos para la herramienta fetch. Predeterminado a ["secret"] pero puede incluir los mismos valores que search_objects.

Ejecutar el Servidor

Inicie el servidor localmente en modo de desarrollo:

python server.py

Al iniciar, el servidor solicita un token de portador y lo almacena para solicitudes posteriores a la API. Este proyecto se ampliará para integrarse aún más con la API de Secret Server.

Herramientas MCP

El servidor expone herramientas MCP para Secret Server, el directorio de identidad de Delinea Platform y (opcionalmente) StrongDM. Cada herramienta publica anotaciones de comportamiento (pistas de solo lectura/destructivas) a través de tools/list.

Compatibilidad con ChatGPT / deep-research

• search(query) - búsqueda unificada que devuelve {id, title, url} resultados; los tipos de objetos están limitados por la clave de configuración search_objects (predeterminado: solo secretos).
• fetch(id) - recuperar un solo objeto expuesto por search; limitado por fetch_objects.

Secret Server

• run_report(sql_query, report_name=None) - crear y ejecutar un informe temporal.
• ai_generate_and_run_report(description) - generar SQL usando Azure OpenAI y ejecutarlo. Requiere las variables de Azure OpenAI.
• list_example_reports() - listar consultas de muestra e información de tablas.
• get_secret(id, summary=False) - recuperar un secreto o detalles resumidos.
• get_folder(id) - obtener metadatos de carpeta y elementos secundarios.
• search_secrets(query, lookup=False) - buscar o consultar secretos.
• search_folders(query, lookup=False) - buscar o consultar carpetas.
• get_secret_environment_variable(secret_id, environment) - generar un script para obtener credenciales de secretos en el shell especificado.
• check_secret_template(template_id) - obtener detalles de plantilla de secreto.
• check_secret_template_field(template_id, field_id) - verificar si una plantilla contiene un campo.
• get_secret_template_field(field_id) - recuperar detalles sobre un campo específico de plantilla de secreto por ID.
• handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - aprobar o denegar una solicitud de acceso.
• get_pending_access_requests() - listar solicitudes de acceso pendientes.
• get_inbox_messages(read_status_filter=None, take=20, skip=0) - recuperar mensajes de la bandeja de entrada.
• mark_inbox_messages_read(message_ids, read=True) - marcar mensajes como leídos o no leídos.
• create_secret_with_generated_password(name, secret_template_id, password_field_id, items, folder_id=None, site_id=None, comment=None) - crear un secreto cuya contraseña se genera en el lado del servidor; solo se devuelve metadatos sanitizados, el valor nunca llega al modelo.
• update_secret_generated_password(secret_id, field_slug, password_field_id, comment=None) - rotar la contraseña de un secreto en el lado del servidor sin exponer el valor.
• update_secret_fields(secret_id, field_updates, comment=None, allow_password_fields=False) - flujo de leer plantilla → mutar campos no relacionados con contraseñas → verificar; rechaza campos marcados como contraseña a menos que se permita explícitamente.
• set_secret_field_environment_variable(secret_id, field_slug, environment, source="stdin", comment=None) - emitir un script de shell (bash/powershell/cmd) que lea un valor localmente y lo inserte en el campo del secreto, de modo que el valor evite el modelo por completo.
• bulk_user_response(user_ids, scenario, comment, confirm=False) - combinador de incidentes con opinión sobre la API de operaciones masivas de usuarios. Escenarios: compromise, offboard, unlock, reenable, force_logout; requiere confirm=True más un comentario de auditoría no vacío, y previsualiza cuando no está confirmado.
• role_management(action, role_id=None, data=None, params=None) - gestionar roles. action puede ser list, get, create o update. Pase parámetros de consulta opcionales con params al listar roles. Ejemplo: role_management("update", role_id=3, data={"name": "New Role"}).
• user_role_management(action, user_id, role_ids=None) - asignar o eliminar roles de un usuario. action es get, add o remove y role_ids es una lista de identificadores de roles para operaciones de agregar/eliminar.
• group_management(action, group_id=None, data=None, params=None) - manejar grupos. action puede ser get, list, create o delete. Proporcione group_id para obtener/eliminar y data al crear un grupo.
• folder_management(action, folder_id=None, data=None, params=None) - gestionar carpetas. action puede ser get, list, create, update o delete. Proporcione folder_id para obtener, actualizar o eliminar y suministre data al crear o actualizar una carpeta.
• user_group_management(action, user_id, group_ids=None) - gestionar membresía de grupo para un usuario. action es get, add o remove. Suministre una lista de group_ids al agregar o eliminar membresía.
• group_role_management(action, group_id, role_ids=None) - controlar roles en un grupo. Use acciones list, add o remove. Proporcione role_ids al agregar o eliminar.
• health_check() - consultar el punto de conexión de verificación de salud de Secret Server y devolver el estado actual del servicio.

Usuarios y roles de Delinea Platform

Desde v1.0.0 las herramientas canónicas de usuario apuntan al directorio de identidad de Delinea Platform (requiere credenciales platform_hostname + PLATFORM_SERVICE_*; sin ellas, las herramientas devuelven orientación en lugar de fallar):

• user_management(action, user_id=None, data=None, username=None) - CRUD de usuarios de Platform. action acepta get, create, update, delete o search.
• search_users(query) - buscar en el directorio de usuarios de Platform.
• platform_role_management(action, role_id=None, data=None, page_size=100, query="%") - CRUD de roles de Platform (list, get, create, update, delete); las mutaciones de roles están impulsadas por descubrimiento y devuelven orientación en tenants cuyo alcance de API no las expone.
• platform_user_role_management(action, role_id, user_principals=None) - list, add o remove usuarios en un rol de Platform.
• platform_user_management(...) - alias obsoleto de user_management.

Usuarios locales de Secret Server (heredado)

Para implementaciones solo SS sin Platform configurada:

• secretserver_local_user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - las operaciones de usuario de Secret Server anteriores a v1.0.0: get, create, update, delete, list_sessions, reset_2fa, reset_password, lock_out. Ejemplo: secretserver_local_user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
• search_secretserver_local_users(query) - buscar en el almacén de usuarios local de Secret Server.

Herramientas de StrongDM (opcional, experimental)

Experimental: el backend de StrongDM aún no se ha verificado contra una organización SDM en vivo (solo probado unitariamente contra la superficie del SDK). Espere bordes ásperos y reporte problemas. Instalado a través del extra strongdm; consulte docs/strongdm.md para la guía completa. sdm_search, sdm_audit_access, sdm_grant_access (concesiones just-in-time limitadas en tiempo o permanentes), sdm_revoke_access, sdm_user_management (flujos de incorporación/desincorporación), sdm_role_management, sdm_resource_health, sdm_access_requests, sdm_activity_report, sdm_network_status. Las acciones destructivas están sujetas a confirmación con comentarios de auditoría; las coincidencias de nombres ambiguas devuelven candidatos sin mutar.

Use las variables de configuración del servidor descritas anteriormente para autenticarse. La herramienta de IA se desactiva automáticamente si faltan las variables de Azure OpenAI. Solo se registrarán los nombres de herramientas listados en config.json. Una lista vacía habilita todas las herramientas.

Casos de Uso

La documentación cubre varios flujos de trabajo para conectar herramientas al servidor:

• ChatGPT Custom Connector
• Claude Desktop
• Remote Claude Connector
• openwebui for Administration
• VSCode Copilot

Inicio rápido con Docker

Se proporciona un Dockerfile para ejecutar el servidor MCP sin instalar dependencias de Python localmente.

1. Construir la imagen:

docker build -t dev.local/delinea-mcp:latest .

2. Ejecutar el servidor (pasa tus credenciales mediante variables de entorno):

docker run --rm -p 8000:8000 \
  -e DELINEA_PASSWORD=<password> \
  -e PLATFORM_SERVICE_PASSWORD=<password> \
  -e DELINEA_DEBUG=1 \
  -e AZURE_OPENAI_KEY=<your-key-or-appropriate-token> \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v mcp-data:/app/data \
  dev.local/delinea-mcp:latest

Rellena config.json con tus nombres de usuario y URLs como se muestra arriba.

El contenedor almacena oauth.db y jwt.json en /app/data. Monta un volumen (mostrado como mcp-data arriba) para que estos archivos y cualquier certificado HTTPS persistan entre ejecuciones.

Reemplaza <https://your-secret-server/SecretServer> con la URL base de tu instancia de Secret Server para evitar errores de conexión.

El servidor se iniciará en el puerto 8000 por defecto usando python server.py. Establece la opción port en config.json para sobrescribir el valor predeterminado. Habilita debug: true para registrar todas las solicitudes HTTP entrantes.

Scripts de ejemplo

El script manual_secret_request.py muestra cómo recuperar un token OAuth para un ID de secreto específico:

python scripts/manual_secret_request.py <Secret_ID>

Establece las variables de entorno SECRET_USERNAME_<id> y SECRET_PASSWORD_<id> para el secreto antes de ejecutar el script. Opcionalmente, establece DELINEA_BASE_URL para sobrescribir el https://localhost/SecretServer predeterminado.

Ejecución de pruebas

Ejecuta las pruebas unitarias con cobertura (CI exige un mínimo del 70%):

pip install -r requirements.txt
coverage run -m pytest -q
coverage report --omit "tests/*"

Pruebas en vivo

Algunas pruebas de integración requieren credenciales válidas. Establece las siguientes variables de entorno y el LIVE_SECRET_ID opcional antes de ejecutar la suite:

export DELINEA_PASSWORD=<password>
# Optional secret used by tests/test_live.py
export LIVE_SECRET_ID=<id>
export SECRET_USERNAME_<id>=<secret_username>
export SECRET_PASSWORD_<id>=<secret_password>

Cuando estas variables están presentes, las pruebas en vivo realizan solicitudes reales a la API.

Despliegue en producción

Las dependencias están fijadas en requirements.txt y los lanzamientos se etiquetan usando Versionado Semántico. Construye la imagen Docker desde un commit etiquetado y despliégala en tu entorno de producción, pasando las variables de entorno requeridas (DELINEA_USERNAME, DELINEA_PASSWORD, opcionalmente DELINEA_BASE_URL). Las características opcionales dependen de variables adicionales:

• PLATFORM_SERVICE_PASSWORD junto con PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT y PLATFORM_TENANT_ID habilita las herramientas de gestión de usuarios.
• AZURE_OPENAI_KEY junto con AZURE_OPENAI_ENDPOINT y AZURE_OPENAI_DEPLOYMENT habilita el asistente de generación de informes de IA.
• SDM_API_ACCESS_KEY y SDM_API_SECRET_KEY habilitan las herramientas experimentales de StrongDM (requiere el extra strongdm; ver docs/strongdm.md).

Cuando se ejecuta con transporte OAuth o SSE, es posible que necesites proporcionar registration_psk y configurar un external_hostname o archivos de certificado HTTPS.

Estructura del repositorio

• delinea_mcp/ - paquete que contiene las herramientas MCP: tools.py (Secret Server), user_platform_tools.py (Delinea Platform), secretserver_users.py (usuarios locales de SS), strongdm_tools.py (StrongDM, opcional), además de transports/ (SSE + HTTP transmisible) y auth/ (el servidor de autorización OAuth integrado).
• server.py - punto de entrada ligero que registra todo con el servidor MCP.
• docs/ - documentación del proyecto y el delinea-secret-server-openapi-spec.json generado.
• scripts/ - ejemplos auxiliares, incluyendo manual_secret_request.py.

Consideraciones de seguridad

El servidor de autorización OAuth integrado es una conveniencia para desarrollo, pruebas y despliegues pequeños; los despliegues más grandes deberían poner el servidor detrás del proveedor de identidad de su organización. Salvaguardas actuales:

• El registro de clientes (/oauth/register) y el formulario de autorización ambos requieren el secreto compartido registration_psk (comparado en tiempo constante).
• Los valores de redirect_uri se validan contra las URIs registradas para el cliente tanto en el formulario de autorización como en la redirección de código.
• Los tokens de acceso son JWTs RS256 vinculados a la audiencia; el descubrimiento de recursos sigue RFC 9728 (/.well-known/oauth-protected-resource más cabeceras WWW-Authenticate en respuestas 401/403).
• Despliega siempre con TLS (ssl_keyfile/ssl_certfile o un proxy de terminación) — los tokens de portador y los secretos transitan en cada solicitud.
• Limita la exposición de herramientas según el caso de uso con enabled_tools; los valores de los secretos se mantienen fuera del contexto del modelo por diseño (generación de contraseñas en el servidor, indirección de scripts con variables de entorno, protecciones en campos de contraseña).

Notas de la versión

Consulta CHANGELOG.md para un resumen de las últimas características y elementos de la hoja de ruta.

Hoja de ruta

1. Autenticación de paso
2. Soporte de clientes para Documentos de Metadatos de ID de Cliente OAuth (CIMD) (el Registro Dinámico de Clientes está obsoleto a partir de la revisión 2026-07-28 del protocolo MCP; el flujo /oauth/register controlado por PSK sigue funcionando para los conectores actuales)
3. Ampliar la cobertura de herramientas en la Delinea Platform y añadir otros productos de Delinea

Contribuciones

¡Las contribuciones son bienvenidas! Abre issues o pull requests para cualquier mejora. Todo código nuevo debe incluir pruebas unitarias y pasar la suite de pruebas existente.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.