delinea-mcp

DelineaMCP

Server MCP untuk Delinea Secret Server dan API Platform

---

Berita

• 11 Agu 2026 — Protokol MCP v2 (revisi spesifikasi 2026-07-28, HTTP streamable) dan dukungan eksperimental API StrongDM telah hadir — lihat catatan rilis.
• 11 Agu 2026 — Kami adalah penyedia asli dari kasus penggunaan vault "tanpa visibilitas rahasia ke LLM" — waspadalah terhadap peniru ;)

---

Fitur

• Autentikasi otomatis terhadap Secret Server
• Perangkat alat Secret Server yang ekstensif untuk mengelola folder, rahasia, pengguna, grup, dan peran. Termasuk bantuan kotak masuk dan permintaan akses serta utilitas agen pengkodean.
• Alat kompatibilitas ChatGPT (search dan fetch) untuk interaksi AI yang terkontrol.
• Alat manajemen pengguna Platform Delinea opsional
• Alat StrongDM (SDM) opsional eksperimental — pemberian akses, audit hak akses, siklus hidup pengguna/peran, laporan kesehatan dan aktivitas (lihat docs/strongdm.md; instal dengan pip install "delinea-mcp[strongdm]")
• Transport HTTP Streamable (/mcp), Server-Sent Events lama (/mcp/sse), dan STDIO
• OAuth 2.0 dengan registrasi klien dinamis sesuai spesifikasi MCP
• Dukungan TLS untuk koneksi aman
• Image Docker siap-jalan dan titik masuk server pengembangan
• Diuji dengan ChatGPT, Claude Desktop, konektor Claude jarak jauh, VSCode Copilot, dan openwebui

Instalasi

[!NOTE]

Proyek ini menggunakan uv (https://github.com/astral-sh/uv), tetapi jika Anda lebih suka menjalankan perintah tanpa ini, Anda dapat melakukan perintah pip dan venv seperti biasa jika diinginkan.

• Instal Uv
• Inisialisasi proyek: uv pip sync requirements.txt
• Gunakan uv run server.py --config config.json

Konfigurasi

Rahasia seperti kata sandi tetap berasal dari variabel lingkungan. Sediakan DELINEA_PASSWORD di lingkungan shell Anda. Fitur opsional bergantung pada variabel tambahan seperti AZURE_OPENAI_KEY atau PLATFORM_SERVICE_PASSWORD.

Parameter non-rahasia berada di 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": []
}

Untuk Secret Server Cloud cukup gunakan URL cloud tanpa /SecretServer. Tentukan ssl_keyfile dan ssl_certfile untuk mengaktifkan HTTPS. Untuk Let's Encrypt, gunakan file privkey.pem dan fullchain.pem.

File konfigurasi mendukung kunci-kunci berikut:

• delinea_username - Nama pengguna Secret Server. Harus berupa pengguna programatik dengan izin untuk melakukan tugas yang Anda inginkan.
• delinea_base_url - URL dasar instance Secret Server Anda.
• platform_hostname - Nama host tenant Platform (mengaktifkan alat Platform).
• platform_service_account - Akun layanan yang digunakan dengan API Platform.
• platform_tenant_id - ID Tenant untuk permintaan API Platform.
• strongdm_api_host - Bidang kendali StrongDM (default app.strongdm.com:443; varian UK/EU tersedia). Kredensial berasal dari variabel env SDM_API_ACCESS_KEY / SDM_API_SECRET_KEY; lihat docs/strongdm.md.
• azure_openai_endpoint - Titik akhir Azure OpenAI. Hanya jika Anda menginginkan pembuatan laporan otomatis (sebagian besar agen dapat membuat SQL laporan mereka sendiri jadi jangan aktifkan kecuali Anda membutuhkannya).
• azure_openai_deployment - Nama deployment untuk Azure OpenAI.
• auth_mode - Mode autentikasi (none atau oauth). OAuth jelas tidak berfungsi dengan transport stdio.
• transport_mode - stdio untuk baris perintah atau sse untuk HTTP. Dalam mode sse server mengekspos titik akhir HTTP streamable di /mcp (transport MCP saat ini, melayani revisi protokol 2024-11-05 hingga 2026-07-28) dan titik akhir HTTP+SSE lama di /mcp/sse + /messages/.
• streamable_http_stateless - default true; jalankan /mcp tanpa sesi sisi-server (disarankan untuk konektor jarak jauh). Setel false untuk mengaktifkan operasi berbasis sesi dengan stream GET mandiri.
• streamable_http_json_response - default true; tanggapi dengan JSON polos alih-alih respons berbingkai SSE pada /mcp.
• chatgpt_disable_scope_checks - Lewati validasi cakupan pada permintaan ChatGPT. Aktifkan hanya jika Anda mengalami masalah saat menghubungkan ke ChatGPT.
• port - Port untuk server HTTP dalam mode sse.
• debug - Aktifkan pencatatan verbose.
• external_hostname - Nama host yang digunakan saat menyusun audiens token OAuth. Jangan tambahkan awalan HTTP(S) atau port.
• ssl_keyfile - Jalur ke kunci SSL untuk HTTPS. (mis. privkey.pem)
• ssl_certfile - Jalur ke sertifikat SSL untuk HTTPS. (mis. fullchain.pem)
• registration_psk - Kunci pra-berbagi yang diperlukan untuk mendaftarkan klien OAuth. Anda perlu mengetikkan rahasia ini di browser Anda untuk menyetujui koneksi OAuth.
• jwt_key_path - Lokasi pasangan kunci RSA yang digunakan untuk token OAuth. Default ke .cache/jwt.json. dibuat otomatis jika tidak ada.
• oauth_db_path - Jalur ke file database OAuth. Default ke .cache/oauth.db. dibuat otomatis jika tidak ada.
• enabled_tools - Daftar nama alat yang akan didaftarkan. Daftar kosong mengaktifkan semua alat. Sangat disarankan untuk mengaktifkan alat secara selektif per kasus penggunaan atau tugas. Lihat folder docs/ untuk beberapa contoh.
• search_objects - Jenis objek yang diizinkan untuk alat search. Default ke ["secret"] tetapi dapat mencakup user, folder, group, dan role.
• fetch_objects - Jenis objek yang diizinkan untuk alat fetch. Default ke ["secret"] tetapi dapat mencakup nilai yang sama dengan search_objects.

Menjalankan Server

Mulai server secara lokal dalam mode pengembangan:

python server.py

Saat startup, server meminta token bearer dan menyimpannya untuk permintaan API berikutnya. Proyek ini akan diperluas untuk berintegrasi lebih lanjut dengan API Secret Server.

Alat MCP

Server mengekspos alat MCP untuk Secret Server, direktori identitas Platform Delinea, dan (opsional) StrongDM. Setiap alat memublikasikan anotasi perilaku (petunjuk hanya-baca/merusak) melalui tools/list.

Kompatibilitas ChatGPT / deep-research

• search(query) - pencarian terpadu yang mengembalikan hasil {id, title, url}; jenis objek dibatasi oleh kunci konfigurasi search_objects (default: hanya rahasia).
• fetch(id) - ambil satu objek yang dimunculkan oleh search; dibatasi oleh fetch_objects.

Secret Server

• run_report(sql_query, report_name=None) - buat dan jalankan laporan sementara.
• ai_generate_and_run_report(description) - buat SQL menggunakan Azure OpenAI dan jalankan. Memerlukan variabel Azure OpenAI.
• list_example_reports() - daftar contoh kueri dan informasi tabel.
• get_secret(id, summary=False) - ambil rahasia atau detail ringkasan.
• get_folder(id) - ambil metadata folder dan anak-anaknya.
• search_secrets(query, lookup=False) - cari atau telusuri rahasia.
• search_folders(query, lookup=False) - cari atau telusuri folder.
• get_secret_environment_variable(secret_id, environment) - keluarkan skrip untuk mengambil kredensial rahasia di shell yang ditentukan.
• check_secret_template(template_id) - ambil detail template rahasia.
• check_secret_template_field(template_id, field_id) - periksa apakah template berisi sebuah bidang.
• get_secret_template_field(field_id) - ambil detail tentang bidang template rahasia tertentu berdasarkan ID.
• handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - setujui atau tolak permintaan akses.
• get_pending_access_requests() - daftar permintaan akses yang tertunda.
• get_inbox_messages(read_status_filter=None, take=20, skip=0) - ambil pesan kotak masuk.
• mark_inbox_messages_read(message_ids, read=True) - tandai pesan sebagai dibaca atau belum dibaca.
• create_secret_with_generated_password(name, secret_template_id, password_field_id, items, folder_id=None, site_id=None, comment=None) - buat rahasia yang kata sandinya dibuat di sisi server; hanya metadata yang telah dibersihkan yang dikembalikan, nilainya tidak pernah mencapai model.
• update_secret_generated_password(secret_id, field_slug, password_field_id, comment=None) - rotasi kata sandi rahasia di sisi server tanpa menampilkan nilainya.
• update_secret_fields(secret_id, field_updates, comment=None, allow_password_fields=False) - alur baca-template → ubah bidang non-kata sandi → verifikasi; menolak bidang yang ditandai kata sandi kecuali diizinkan secara eksplisit.
• set_secret_field_environment_variable(secret_id, field_slug, environment, source="stdin", comment=None) - keluarkan skrip shell (bash/powershell/cmd) yang membaca nilai secara lokal dan mendorongnya ke bidang rahasia, sehingga nilainya melewati model sepenuhnya.
• bulk_user_response(user_ids, scenario, comment, confirm=False) - kombinator insiden beropini di atas API operasi pengguna massal. Skenario: compromise, offboard, unlock, reenable, force_logout; memerlukan confirm=True plus komentar audit yang tidak kosong, dan memberikan pratinjau saat belum dikonfirmasi.
• role_management(action, role_id=None, data=None, params=None) - kelola peran. action dapat berupa list, get, create, atau update. Berikan parameter kueri opsional dengan params saat mendaftar peran. Contoh: role_management("update", role_id=3, data={"name": "New Role"}).
• user_role_management(action, user_id, role_ids=None) - tetapkan atau hapus peran dari pengguna. action adalah get, add, atau remove dan role_ids adalah daftar pengidentifikasi peran untuk operasi tambah/hapus.
• group_management(action, group_id=None, data=None, params=None) - tangani grup. action dapat berupa get, list, create, atau delete. Berikan group_id untuk get/delete dan data saat membuat grup.
• folder_management(action, folder_id=None, data=None, params=None) - kelola folder. action dapat berupa get, list, create, update, atau delete. Berikan folder_id untuk get, update, atau delete dan sediakan data saat membuat atau memperbarui folder.
• user_group_management(action, user_id, group_ids=None) - kelola keanggotaan grup untuk pengguna. action adalah get, add, atau remove. Sediakan daftar group_ids saat menambah atau menghapus keanggotaan.
• group_role_management(action, group_id, role_ids=None) - kontrol peran pada grup. Gunakan aksi list, add, atau remove. Berikan role_ids saat menambah atau menghapus.
• health_check() - kueri titik akhir pemeriksaan kesehatan Secret Server dan kembalikan status layanan saat ini.

Pengguna dan peran Platform Delinea

Sejak v1.0.0 alat pengguna kanonik menargetkan direktori identitas Platform Delinea (memerlukan kredensial platform_hostname + PLATFORM_SERVICE_*; tanpa keduanya, alat mengembalikan panduan alih-alih gagal):

• user_management(action, user_id=None, data=None, username=None) - CRUD pengguna Platform. action menerima get, create, update, delete, atau search.
• search_users(query) - cari direktori pengguna Platform.
• platform_role_management(action, role_id=None, data=None, page_size=100, query="%") - CRUD peran Platform (list, get, create, update, delete); mutasi peran digerakkan oleh penemuan dan mengembalikan panduan pada tenant yang cakupan API-nya tidak mengeksposnya.
• platform_user_role_management(action, role_id, user_principals=None) - list, add, atau remove pengguna pada peran Platform.
• platform_user_management(...) - alias usang dari user_management.

Pengguna lokal Secret Server (lama)

Untuk deployment khusus SS tanpa Platform yang dikonfigurasi:

• secretserver_local_user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - operasi pengguna Secret Server pra-v1.0.0: get, create, update, delete, list_sessions, reset_2fa, reset_password, lock_out. Contoh: secretserver_local_user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
• search_secretserver_local_users(query) - cari penyimpanan pengguna lokal Secret Server.

Alat StrongDM (opsional, eksperimental)

Eksperimental: backend StrongDM belum diverifikasi terhadap organisasi SDM langsung (hanya diuji unit terhadap permukaan SDK). Harapkan kekasaran dan laporkan masalah. Diinstal melalui ekstra strongdm; lihat docs/strongdm.md untuk panduan lengkap. sdm_search, sdm_audit_access, sdm_grant_access (pemberian just-in-time terbatas waktu atau berdiri), sdm_revoke_access, sdm_user_management (alur onboard/offboard), sdm_role_management, sdm_resource_health, sdm_access_requests, sdm_activity_report, sdm_network_status. Aksi merusak dikonfirmasi-gate dengan komentar audit; kecocokan nama yang ambigu mengembalikan kandidat tanpa mutasi.

Gunakan variabel konfigurasi server yang dijelaskan di atas untuk mengautentikasi. Alat AI secara otomatis dinonaktifkan jika variabel Azure OpenAI tidak ada. Hanya nama alat yang tercantum di config.json yang akan didaftarkan. Daftar kosong mengaktifkan setiap alat.

Kasus Penggunaan

Dokumentasi mencakup beberapa alur kerja untuk menghubungkan alat ke server:

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

Mulai Cepat Docker

Sebuah Dockerfile disediakan untuk menjalankan server MCP tanpa menginstal dependensi Python secara lokal.

1. Bangun image:

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

2. Jalankan server (teruskan kredensial Anda melalui variabel lingkungan):

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

Isi config.json dengan nama pengguna dan URL Anda seperti yang ditunjukkan di atas.

Kontainer menyimpan oauth.db dan jwt.json di /app/data. Pasang volume (ditampilkan sebagai mcp-data di atas) agar file-file ini dan sertifikat HTTPS apa pun tetap tersimpan di antara sesi eksekusi.

Ganti <https://your-secret-server/SecretServer> dengan URL dasar instance Secret Server Anda untuk menghindari kesalahan koneksi.

Server akan dimulai pada port 8000 secara default menggunakan python server.py. Atur opsi port di config.json untuk mengganti nilai default. Aktifkan debug: true untuk mencatat semua permintaan HTTP yang masuk.

Contoh Skrip

Skrip manual_secret_request.py menunjukkan cara mengambil token OAuth untuk ID rahasia tertentu:

python scripts/manual_secret_request.py <Secret_ID>

Atur variabel lingkungan SECRET_USERNAME_<id> dan SECRET_PASSWORD_<id> untuk rahasia tersebut sebelum menjalankan skrip. Secara opsional, atur DELINEA_BASE_URL untuk mengganti https://localhost/SecretServer default.

Menjalankan Pengujian

Jalankan pengujian unit dengan cakupan (CI menerapkan minimum 70%):

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

Pengujian Langsung

Beberapa pengujian integrasi memerlukan kredensial yang valid. Atur variabel lingkungan berikut dan LIVE_SECRET_ID opsional sebelum menjalankan rangkaian pengujian:

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>

Ketika variabel-variabel ini tersedia, pengujian langsung akan melakukan permintaan API nyata.

Penerapan Produksi

Dependensi dikunci di requirements.txt dan rilis diberi tag menggunakan Versioning Semantik. Bangun image Docker dari commit yang diberi tag dan terapkan ke lingkungan produksi Anda, dengan meneruskan variabel lingkungan yang diperlukan (DELINEA_USERNAME, DELINEA_PASSWORD, secara opsional DELINEA_BASE_URL). Fitur opsional bergantung pada variabel tambahan:

• PLATFORM_SERVICE_PASSWORD bersama dengan PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT, dan PLATFORM_TENANT_ID mengaktifkan alat manajemen pengguna.
• AZURE_OPENAI_KEY bersama dengan AZURE_OPENAI_ENDPOINT dan AZURE_OPENAI_DEPLOYMENT mengaktifkan pembantu pembuatan laporan AI.
• SDM_API_ACCESS_KEY dan SDM_API_SECRET_KEY mengaktifkan alat StrongDM eksperimental (memerlukan ekstra strongdm; lihat docs/strongdm.md).

Saat berjalan dengan transport OAuth atau SSE, Anda mungkin perlu menyediakan registration_psk dan mengonfigurasi external_hostname atau file sertifikat HTTPS.

Struktur Repositori

• delinea_mcp/ - paket yang berisi alat MCP: tools.py (Secret Server), user_platform_tools.py (Platform Delinea), secretserver_users.py (pengguna SS-lokal), strongdm_tools.py (StrongDM, opsional), plus transports/ (SSE + HTTP yang dapat dialirkan) dan auth/ (server otorisasi OAuth tertanam).
• server.py - titik masuk tipis yang mendaftarkan semuanya ke server MCP.
• docs/ - dokumentasi proyek dan delinea-secret-server-openapi-spec.json yang dihasilkan.
• scripts/ - contoh pembantu termasuk manual_secret_request.py.

Pertimbangan Keamanan

Server otorisasi OAuth tertanam adalah kemudahan untuk pengembangan, pengujian, dan penerapan skala kecil; penerapan yang lebih besar sebaiknya menempatkan server di belakang penyedia identitas organisasi mereka. Pengamanan saat ini:

• Pendaftaran klien (/oauth/register) dan formulir otorisasi sama-sama memerlukan rahasia bersama registration_psk (dibandingkan dengan waktu konstan).
• Nilai redirect_uri divalidasi terhadap URI yang terdaftar untuk klien pada formulir otorisasi dan pengalihan kode.
• Token akses adalah JWT RS256 yang terikat audiens; penemuan sumber daya mengikuti RFC 9728 (header /.well-known/oauth-protected-resource plus WWW-Authenticate pada respons 401/403).
• Selalu terapkan dengan TLS (ssl_keyfile/ssl_certfile atau proxy pemutus) — token pembawa dan rahasia transit di setiap permintaan.
• Batasi paparan alat per kasus penggunaan dengan enabled_tools; nilai rahasia dijauhkan dari konteks model secara desain (generasi kata sandi sisi server, pengalihan skrip variabel lingkungan, penjaga bidang kata sandi).

Catatan Rilis

Lihat CHANGELOG.md untuk ringkasan fitur terbaru dan item peta jalan.

Peta Jalan

1. Autentikasi penerusan
2. Dukungan klien Dokumen Metadata ID Klien OAuth (CIMD) (Pendaftaran Klien Dinamis tidak digunakan lagi sejak revisi protokol MCP 2026-07-28; alur /oauth/register yang dibatasi PSK tetap berfungsi untuk konektor saat ini)
3. Perluas cakupan alat di Platform Delinea dan tambahkan produk Delinea lainnya

Berkontribusi

Kontribusi sangat diterima! Silakan buka issue atau pull request untuk perbaikan apa pun. Semua kode baru harus menyertakan pengujian unit dan lulus rangkaian pengujian yang ada.

Lisensi

Proyek ini dilisensikan di bawah Lisensi MIT.