delinea-mcp

DelineaMCP

MCP server cho Secret Server và Platform APIs của Delinea

---

Tin tức

• 11 Thg 8 2026 — Giao thức MCP v2 (spec revision 2026-07-28, streamable HTTP) và hỗ trợ StrongDM API thử nghiệm đã có mặt — xem ghi chú phát hành.
• 11 Thg 8 2026 — Chúng tôi là nhà cung cấp ban đầu của trường hợp sử dụng vault "không hiển thị bí mật cho LLM" — hãy cẩn thận với những kẻ bắt chước ;)

---

Tính năng

• Xác thực tự động với Secret Server
• Bộ công cụ Secret Server phong phú để quản lý thư mục, bí mật, người dùng, nhóm và vai trò. Bao gồm các tiện ích hỗ trợ hộp thư đến và yêu cầu truy cập cũng như tiện ích cho coding agent.
• Công cụ tương thích ChatGPT (search và fetch) cho các tương tác AI có kiểm soát.
• Công cụ quản lý người dùng Delinea Platform tùy chọn
• Công cụ StrongDM (SDM) thử nghiệm tùy chọn — cấp quyền truy cập, kiểm toán entitlement, vòng đời người dùng/vai trò, báo cáo sức khỏe và hoạt động (xem docs/strongdm.md; cài đặt bằng pip install "delinea-mcp[strongdm]")
• Streamable HTTP (/mcp), Server-Sent Events kế thừa (/mcp/sse) và transport STDIO
• OAuth 2.0 với đăng ký client động theo spec MCP
• Hỗ trợ TLS cho kết nối an toàn
• Docker image sẵn sàng chạy và entry point máy chủ phát triển
• Đã kiểm thử với ChatGPT, Claude Desktop, remote Claude connector, VSCode Copilot và openwebui

Cài đặt

[!NOTE]

Dự án này sử dụng uv (https://github.com/astral-sh/uv), nhưng nếu bạn muốn chạy lệnh mà không cần công cụ này, bạn có thể thực hiện pip và venv như bình thường nếu muốn.

• Cài đặt Uv
• Khởi tạo dự án: uv pip sync requirements.txt
• Sử dụng uv run server.py --config config.json

Cấu hình

Các bí mật như mật khẩu tiếp tục được lấy từ biến môi trường. Cung cấp DELINEA_PASSWORD trong môi trường shell của bạn. Các tính năng tùy chọn phụ thuộc vào các biến bổ sung như AZURE_OPENAI_KEY hoặc PLATFORM_SERVICE_PASSWORD.

Các tham số không phải bí mật nằm trong 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": []
}

Đối với Secret Server Cloud chỉ cần sử dụng URL đám mây mà không có /SecretServer. Chỉ định ssl_keyfile và ssl_certfile để bật HTTPS. Đối với Let's Encrypt, hãy sử dụng các tệp privkey.pem và fullchain.pem.

Tệp cấu hình hỗ trợ các khóa sau:

• delinea_username - Tên người dùng Secret Server. Phải là người dùng lập trình (programmatic user) có quyền thực hiện các tác vụ bạn muốn.
• delinea_base_url - URL gốc của phiên bản Secret Server của bạn.
• platform_hostname - Tên máy chủ tenant Platform (kích hoạt công cụ Platform).
• platform_service_account - Tài khoản dịch vụ được sử dụng với Platform API.
• platform_tenant_id - Mã tenant cho các yêu cầu Platform API.
• strongdm_api_host - StrongDM control plane (mặc định app.strongdm.com:443; có các biến thể UK/EU). Thông tin xác thực đến từ các biến môi trường SDM_API_ACCESS_KEY / SDM_API_SECRET_KEY; xem docs/strongdm.md.
• azure_openai_endpoint - Endpoint Azure OpenAI. Chỉ khi bạn muốn tạo báo cáo tự động (hầu hết các agent có thể tự tạo SQL báo cáo nên đừng bật trừ khi bạn cần).
• azure_openai_deployment - Tên deployment cho Azure OpenAI.
• auth_mode - Chế độ xác thực (none hoặc oauth). OAuth rõ ràng không hoạt động với transport stdio.
• transport_mode - stdio cho dòng lệnh hoặc sse cho HTTP. Trong chế độ sse máy chủ hiển thị cả endpoint streamable HTTP tại /mcp (transport MCP hiện tại, phục vụ các bản sửa đổi giao thức 2024-11-05 đến 2026-07-28) và các endpoint HTTP+SSE kế thừa tại /mcp/sse + /messages/.
• streamable_http_stateless - mặc định true; chạy /mcp mà không có phiên phía máy chủ (khuyến nghị cho remote connector). Đặt false để bật hoạt động dựa trên phiên với GET stream độc lập.
• streamable_http_json_response - mặc định true; phản hồi bằng JSON thuần thay vì phản hồi khung SSE trên /mcp.
• chatgpt_disable_scope_checks - Bỏ qua kiểm tra phạm vi trên các yêu cầu ChatGPT. Chỉ bật nếu bạn gặp sự cố khi kết nối với ChatGPT.
• port - Cổng cho máy chủ HTTP ở chế độ sse.
• debug - Bật ghi log chi tiết.
• external_hostname - Tên máy chủ được sử dụng khi xây dựng đối tượng audience cho token OAuth. Không thêm tiền tố HTTP(S) hoặc cổng.
• ssl_keyfile - Đường dẫn đến khóa SSL cho HTTPS. (ví dụ privkey.pem)
• ssl_certfile - Đường dẫn đến chứng chỉ SSL cho HTTPS. (ví dụ fullchain.pem)
• registration_psk - Khóa chia sẻ trước (pre-shared key) bắt buộc để đăng ký client OAuth. Bạn sẽ cần nhập bí mật này trong trình duyệt để phê duyệt kết nối OAuth.
• jwt_key_path - Vị trí của cặp khóa RSA dùng cho token OAuth. Mặc định là .cache/jwt.json. tự động tạo nếu chưa tồn tại.
• oauth_db_path - Đường dẫn đến tệp cơ sở dữ liệu OAuth. Mặc định là .cache/oauth.db. tự động tạo nếu chưa tồn tại.
• enabled_tools - Danh sách tên công cụ để đăng ký. Danh sách rỗng kích hoạt tất cả các công cụ. Rất khuyến nghị bật các công cụ một cách chọn lọc theo từng trường hợp sử dụng hoặc tác vụ. Xem thư mục docs/ để biết một số ví dụ.
• search_objects - Các loại đối tượng được phép cho công cụ search. Mặc định là ["secret"] nhưng có thể bao gồm user, folder, group và role.
• fetch_objects - Các loại đối tượng được phép cho công cụ fetch. Mặc định là ["secret"] nhưng có thể bao gồm các giá trị tương tự như search_objects.

Chạy Máy Chủ

Khởi động máy chủ cục bộ ở chế độ phát triển:

python server.py

Khi khởi động, máy chủ yêu cầu bearer token và lưu trữ token đó cho các yêu cầu API tiếp theo. Dự án này sẽ được mở rộng để tích hợp sâu hơn với Secret Server API.

Công cụ MCP

Máy chủ hiển thị các công cụ MCP cho Secret Server, thư mục danh tính Delinea Platform và (tùy chọn) StrongDM. Mọi công cụ đều công bố chú thích hành vi (gợi ý chỉ đọc/phá hủy) thông qua tools/list.

Tương thích ChatGPT / deep-research

• search(query) - tìm kiếm thống nhất trả về {id, title, url} kết quả; các loại đối tượng bị giới hạn bởi khóa cấu hình search_objects (mặc định: chỉ bí mật).
• fetch(id) - truy xuất một đối tượng duy nhất được hiển thị bởi search; bị giới hạn bởi fetch_objects.

Secret Server

• run_report(sql_query, report_name=None) - tạo và thực thi một báo cáo tạm thời.
• ai_generate_and_run_report(description) - tạo SQL bằng Azure OpenAI và chạy nó. Yêu cầu các biến Azure OpenAI.
• list_example_reports() - liệt kê các truy vấn mẫu và thông tin bảng.
• get_secret(id, summary=False) - truy xuất một bí mật hoặc chi tiết tóm tắt.
• get_folder(id) - lấy siêu dữ liệu thư mục và các mục con.
• search_secrets(query, lookup=False) - tìm kiếm hoặc tra cứu bí mật.
• search_folders(query, lookup=False) - tìm kiếm hoặc tra cứu thư mục.
• get_secret_environment_variable(secret_id, environment) - xuất ra một tập lệnh để lấy thông tin xác thực bí mật trong shell được chỉ định.
• check_secret_template(template_id) - lấy chi tiết mẫu bí mật.
• check_secret_template_field(template_id, field_id) - kiểm tra xem một mẫu có chứa một trường hay không.
• get_secret_template_field(field_id) - truy xuất chi tiết về một trường mẫu bí mật cụ thể theo ID.
• handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - phê duyệt hoặc từ chối một yêu cầu truy cập.
• get_pending_access_requests() - liệt kê các yêu cầu truy cập đang chờ xử lý.
• get_inbox_messages(read_status_filter=None, take=20, skip=0) - truy xuất tin nhắn hộp thư đến.
• mark_inbox_messages_read(message_ids, read=True) - đánh dấu tin nhắn là đã đọc hoặc chưa đọc.
• create_secret_with_generated_password(name, secret_template_id, password_field_id, items, folder_id=None, site_id=None, comment=None) - tạo một bí mật có mật khẩu được tạo phía máy chủ; chỉ trả về siêu dữ liệu đã được làm sạch, giá trị không bao giờ đến được mô hình.
• update_secret_generated_password(secret_id, field_slug, password_field_id, comment=None) - xoay vòng mật khẩu bí mật phía máy chủ mà không hiển thị giá trị.
• update_secret_fields(secret_id, field_updates, comment=None, allow_password_fields=False) - quy trình đọc-mẫu → sửa đổi các trường không phải mật khẩu → xác minh; từ chối các trường được đánh dấu mật khẩu trừ khi được phép một cách tường minh.
• set_secret_field_environment_variable(secret_id, field_slug, environment, source="stdin", comment=None) - phát ra một tập lệnh shell (bash/powershell/cmd) đọc giá trị cục bộ và đẩy giá trị đó vào trường bí mật, để giá trị hoàn toàn đi vòng qua mô hình.
• bulk_user_response(user_ids, scenario, comment, confirm=False) - bộ tổ hợp sự cố theo quan điểm (opinionated) dựa trên API thao tác hàng loạt người dùng. Các kịch bản: compromise, offboard, unlock, reenable, force_logout; yêu cầu confirm=True cùng với nhận xét kiểm toán không rỗng và xem trước khi chưa xác nhận.
• role_management(action, role_id=None, data=None, params=None) - quản lý vai trò. action có thể là list, get, create hoặc update. Truyền các tham số truy vấn tùy chọn bằng params khi liệt kê vai trò. Ví dụ: role_management("update", role_id=3, data={"name": "New Role"}).
• user_role_management(action, user_id, role_ids=None) - gán hoặc gỡ vai trò khỏi người dùng. action là get, add hoặc remove và role_ids là danh sách mã định danh vai trò cho các thao tác thêm/gỡ.
• group_management(action, group_id=None, data=None, params=None) - xử lý nhóm. action có thể là get, list, create hoặc delete. Cung cấp group_id cho get/delete và data khi tạo nhóm.
• folder_management(action, folder_id=None, data=None, params=None) - quản lý thư mục. action có thể là get, list, create, update hoặc delete. Cung cấp folder_id cho get, update hoặc delete và cung cấp data khi tạo hoặc cập nhật thư mục.
• user_group_management(action, user_id, group_ids=None) - quản lý tư cách thành viên nhóm cho người dùng. action là get, add hoặc remove. Cung cấp danh sách group_ids khi thêm hoặc gỡ tư cách thành viên.
• group_role_management(action, group_id, role_ids=None) - kiểm soát vai trò trên một nhóm. Sử dụng các hành động list, add hoặc remove. Cung cấp role_ids khi thêm hoặc gỡ.
• health_check() - truy vấn endpoint kiểm tra sức khỏe Secret Server và trả về trạng thái dịch vụ hiện tại.

Người dùng và vai trò Delinea Platform

Kể từ v1.0.0, các công cụ người dùng chuẩn nhắm đến thư mục danh tính Delinea Platform (yêu cầu thông tin xác thực platform_hostname + PLATFORM_SERVICE_*; nếu không có chúng, các công cụ sẽ trả về hướng dẫn thay vì lỗi):

• user_management(action, user_id=None, data=None, username=None) - thao tác CRUD người dùng Platform. action chấp nhận get, create, update, delete hoặc search.
• search_users(query) - tìm kiếm thư mục người dùng Platform.
• platform_role_management(action, role_id=None, data=None, page_size=100, query="%") - CRUD vai trò Platform (list, get, create, update, delete); các thay đổi vai trò được điều khiển bằng khám phá (discovery-driven) và trả về hướng dẫn trên các tenant có phạm vi API không hiển thị chúng.
• platform_user_role_management(action, role_id, user_principals=None) - list, add hoặc remove người dùng trên một vai trò Platform.
• platform_user_management(...) - bí danh không được dùng nữa của user_management.

Người dùng cục bộ Secret Server (kế thừa)

Dành cho các triển khai chỉ dùng SS mà không cấu hình Platform:

• secretserver_local_user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - các thao tác người dùng Secret Server trước v1.0.0: get, create, update, delete, list_sessions, reset_2fa, reset_password, lock_out. Ví dụ: secretserver_local_user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
• search_secretserver_local_users(query) - tìm kiếm kho lưu trữ người dùng cục bộ của Secret Server.

Công cụ StrongDM (tùy chọn, thử nghiệm)

Thử nghiệm: backend StrongDM chưa được xác minh với một tổ chức SDM trực tiếp (chỉ được kiểm thử đơn vị dựa trên bề mặt SDK). Hãy mong đợi các cạnh chưa hoàn thiện và báo cáo sự cố. Được cài đặt thông qua gói bổ sung strongdm; xem docs/strongdm.md để biết hướng dẫn đầy đủ. sdm_search, sdm_audit_access, sdm_grant_access (cấp quyền just-in-time giới hạn thời gian hoặc cấp quyền thường trực), sdm_revoke_access, sdm_user_management (quy trình onboard/offboard), sdm_role_management, sdm_resource_health, sdm_access_requests, sdm_activity_report, sdm_network_status. Các hành động phá hủy được chặn xác nhận kèm nhận xét kiểm toán; các kết quả khớp tên không rõ ràng trả về các ứng viên mà không thay đổi.

Sử dụng các biến cấu hình máy chủ được mô tả ở trên để xác thực. Công cụ AI tự động bị vô hiệu hóa nếu thiếu các biến Azure OpenAI. Chỉ các tên công cụ được liệt kê trong config.json mới được đăng ký. Danh sách rỗng kích hoạt mọi công cụ.

Trường hợp sử dụng

Tài liệu bao gồm một số quy trình công việc để kết nối các công cụ với máy chủ:

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

Khởi động nhanh với Docker

Một Dockerfile được cung cấp để chạy MCP server mà không cần cài đặt các phụ thuộc Python cục bộ.

1. Xây dựng image:

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

2. Chạy server (truyền thông tin xác thực của bạn qua các biến môi trường):

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

Điền config.json với tên người dùng và URL của bạn như minh họa ở trên.

Container lưu trữ oauth.db và jwt.json trong /app/data. Gắn một volume (được hiển thị là mcp-data ở trên) để các tệp này và mọi chứng chỉ HTTPS được duy trì giữa các lần chạy.

Thay thế <https://your-secret-server/SecretServer> bằng URL gốc của phiên bản Secret Server của bạn để tránh lỗi kết nối.

Server sẽ khởi động trên cổng 8000 theo mặc định bằng cách sử dụng python server.py. Đặt tùy chọn port trong config.json để ghi đè mặc định. Bật debug: true để ghi nhật ký tất cả các yêu cầu HTTP đến.

Các script ví dụ

Script manual_secret_request.py minh họa cách lấy mã thông báo OAuth cho một secret ID cụ thể:

python scripts/manual_secret_request.py <Secret_ID>

Đặt các biến môi trường SECRET_USERNAME_<id> và SECRET_PASSWORD_<id> cho secret trước khi chạy script. Tùy chọn đặt DELINEA_BASE_URL để ghi đè https://localhost/SecretServer mặc định.

Chạy kiểm thử

Chạy các bài kiểm thử đơn vị với độ phủ (CI yêu cầu tối thiểu 70%):

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

Kiểm thử trực tiếp

Một số bài kiểm thử tích hợp yêu cầu thông tin xác thực hợp lệ. Đặt các biến môi trường sau và biến tùy chọn LIVE_SECRET_ID trước khi chạy bộ kiểm thử:

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>

Khi các biến này có mặt, các bài kiểm thử trực tiếp sẽ thực hiện các yêu cầu API thực.

Triển khai sản xuất

Các phụ thuộc được khóa chặt trong requirements.txt và các bản phát hành được gắn thẻ bằng Semantic Versioning. Xây dựng Docker image từ một commit được gắn thẻ và triển khai nó vào môi trường sản xuất của bạn, truyền các biến môi trường bắt buộc (DELINEA_USERNAME, DELINEA_PASSWORD, tùy chọn DELINEA_BASE_URL). Các tính năng tùy chọn phụ thuộc vào các biến bổ sung:

• PLATFORM_SERVICE_PASSWORD cùng với PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT và PLATFORM_TENANT_ID kích hoạt các công cụ quản lý người dùng.
• AZURE_OPENAI_KEY cùng với AZURE_OPENAI_ENDPOINT và AZURE_OPENAI_DEPLOYMENT kích hoạt trình hỗ trợ tạo báo cáo AI.
• SDM_API_ACCESS_KEY và SDM_API_SECRET_KEY kích hoạt các công cụ StrongDM thử nghiệm (yêu cầu gói bổ sung strongdm; xem docs/strongdm.md).

Khi chạy với giao thức vận chuyển OAuth hoặc SSE, bạn có thể cần cung cấp registration_psk và cấu hình external_hostname hoặc các tệp chứng chỉ HTTPS.

Cấu trúc kho lưu trữ

• delinea_mcp/ - gói chứa các công cụ MCP: tools.py (Secret Server), user_platform_tools.py (Delinea Platform), secretserver_users.py (người dùng SS-local), strongdm_tools.py (StrongDM, tùy chọn), cùng với transports/ (SSE + HTTP có thể truyền luồng) và auth/ (máy chủ ủy quyền OAuth nhúng).
• server.py - điểm vào mỏng đăng ký mọi thứ với MCP server.
• docs/ - tài liệu dự án và delinea-secret-server-openapi-spec.json đã được tạo.
• scripts/ - các ví dụ trợ giúp bao gồm manual_secret_request.py.

Cân nhắc bảo mật

Máy chủ ủy quyền OAuth nhúng là một tiện ích cho phát triển, kiểm thử và các triển khai nhỏ; các triển khai lớn hơn nên đặt máy chủ phía sau nhà cung cấp danh tính của tổ chức. Các biện pháp bảo vệ hiện tại:

• Đăng ký máy khách (/oauth/register) và biểu mẫu ủy quyền đều yêu cầu bí mật dùng chung registration_psk (được so sánh trong thời gian không đổi).
• Các giá trị redirect_uri được xác thực với các URI đã đăng ký cho máy khách trên cả biểu mẫu ủy quyền và chuyển hướng mã.
• Mã truy cập là RS256 JWT gắn với đối tượng; khám phá tài nguyên tuân theo RFC 9728 (/.well-known/oauth-protected-resource cộng với các tiêu đề WWW-Authenticate trong các phản hồi 401/403).
• Luôn triển khai với TLS (ssl_keyfile/ssl_certfile hoặc proxy kết thúc) — mã thông báo bearer và bí mật được truyền qua mọi yêu cầu.
• Giới hạn phạm vi tiếp xúc công cụ cho từng trường hợp sử dụng bằng enabled_tools; secret values được giữ ngoài ngữ cảnh mô hình theo thiết kế (tạo mật khẩu phía máy chủ, chuyển hướng script qua biến môi trường, bảo vệ trường mật khẩu).

Ghi chú phát hành

Xem CHANGELOG.md để biết tóm tắt các tính năng và mục lộ trình mới nhất.

Lộ trình

1. Xác thực chuyển tiếp
2. Hỗ trợ máy khách OAuth Client ID Metadata Documents (CIMD) (Dynamic Client Registration không được dùng nữa kể từ bản sửa đổi giao thức MCP 2026-07-28; luồng /oauth/register có cổng PSK vẫn hoạt động cho các bộ kết nối hiện tại)
3. Mở rộng phạm vi công cụ trên Delinea Platform và thêm các sản phẩm Delinea khác

Đóng góp

Rất hoan nghênh các đóng góp! Vui lòng mở issue hoặc pull request cho mọi cải tiến. Tất cả mã mới nên bao gồm các bài kiểm thử đơn vị và vượt qua bộ kiểm thử hiện có.

Giấy phép

Dự án này được cấp phép theo MIT License.