delinea-mcp

DelineaMCP

Delinea Secret Server 및 Platform API용 MCP 서버

---

소식

• 2026년 8월 11일 — MCP 프로토콜 v2(사양 개정 2026-07-28, streamable HTTP) 및 실험적 StrongDM API 지원이 추가되었습니다 — 자세한 내용은 릴리스 노트를 참조하세요.
• 2026년 8월 11일 — 저희는 "LLM에 비밀 노출 없음" 볼트 사용 사례의 원조 제공자입니다 — 모방품을 조심하세요 ;)

---

기능

• Secret Server에 대한 자동 인증
• 폴더, 비밀, 사용자, 그룹 및 역할 관리를 위한 광범위한 Secret Server 도구 세트. 받은 편지함 및 액세스 요청 도우미와 코딩 에이전트 유틸리티를 포함합니다.
• 제어된 AI 상호작용을 위한 ChatGPT 호환 도구(search 및 fetch).
• 선택적 Delinea Platform 사용자 관리 도구
• 선택적 실험적 StrongDM(SDM) 도구 — 액세스 권한 부여, 권한 감사, 사용자/역할 수명 주기, 상태 및 활동 보고서(자세한 내용은 docs/strongdm.md 참조; 설치 방법: pip install "delinea-mcp[strongdm]")
• Streamable HTTP(/mcp), 레거시 Server-Sent Events(/mcp/sse) 및 STDIO 전송
• MCP 사양에 따른 동적 클라이언트 등록을 지원하는 OAuth 2.0
• 보안 연결을 위한 TLS 지원
• 바로 실행 가능한 Docker 이미지 및 개발 서버 진입점
• ChatGPT, Claude Desktop, 원격 Claude 커넥터, VSCode Copilot 및 openwebui에서 테스트 완료

설치

[!NOTE]

이 프로젝트는 uv(https://github.com/astral-sh/uv)을 사용하지만, 이를 사용하지 않고 명령을 실행하려면 원하는 경우 평소처럼 pip 및 venv 명령을 사용할 수 있습니다.

• Uv 설치
• 프로젝트 초기화: uv pip sync requirements.txt
• uv run server.py --config config.json 사용

구성

비밀번호와 같은 비밀 값은 계속해서 환경 변수에서 가져옵니다. 셸 환경에 DELINEA_PASSWORD을 제공하세요. 선택적 기능은 AZURE_OPENAI_KEY 또는 PLATFORM_SERVICE_PASSWORD와 같은 추가 변수에 의존합니다.

비밀이 아닌 매개변수는 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": []
}

Secret Server Cloud의 경우 /SecretServer 없이 클라우드 URL을 사용하세요. HTTPS를 활성화하려면 ssl_keyfile 및 ssl_certfile을 지정하세요. Let's Encrypt의 경우 privkey.pem 및 fullchain.pem 파일을 사용하세요.

구성 파일은 다음 키를 지원합니다:

• delinea_username - Secret Server 사용자 이름. 수행하려는 작업에 대한 권한이 있는 프로그래매틱 사용자여야 합니다.
• delinea_base_url - Secret Server 인스턴스의 기본 URL.
• platform_hostname - Platform 테넌트 호스트 이름(Platform 도구 활성화).
• platform_service_account - Platform API에 사용되는 서비스 계정.
• platform_tenant_id - Platform API 요청용 테넌트 ID.
• strongdm_api_host - StrongDM 제어 평면(기본값 app.strongdm.com:443; UK/EU 변형 사용 가능). 자격 증명은 SDM_API_ACCESS_KEY / SDM_API_SECRET_KEY 환경 변수에서 가져옵니다. docs/strongdm.md 참조.
• azure_openai_endpoint - Azure OpenAI 엔드포인트. 자동 보고서 생성을 원하는 경우에만 사용합니다(대부분의 에이전트는 자체적으로 보고서 SQL을 생성할 수 있으므로 필요하지 않으면 활성화하지 마세요).
• azure_openai_deployment - Azure OpenAI의 배포 이름.
• auth_mode - 인증 모드(none 또는 oauth). OAuth는 당연히 stdio 전송에서는 작동하지 않습니다.
• transport_mode - 명령줄용 stdio 또는 HTTP용 sse. sse 모드에서 서버는 /mcp의 streamable HTTP 엔드포인트 (현재 MCP 전송, 프로토콜 개정 2024-11-05부터 2026-07-28까지 지원)와 /mcp/sse + /messages/의 레거시 HTTP+SSE 엔드포인트를 모두 노출합니다.
• streamable_http_stateless - 기본값 true; 서버 측 세션 없이 /mcp 실행(원격 커넥터에 권장). false로 설정하면 독립형 GET 스트림과 함께 세션 기반 작업이 활성화됩니다.
• streamable_http_json_response - 기본값 true; /mcp에서 SSE 프레임 응답 대신 일반 JSON으로 응답합니다.
• chatgpt_disable_scope_checks - ChatGPT 요청에 대한 범위 검증 건너뛰기. ChatGPT 연결에 문제가 있는 경우에만 활성화하세요.
• port - sse 모드에서 HTTP 서버의 포트.
• debug - 상세 로깅 활성화.
• external_hostname - OAuth 토큰 대상 그룹 구성 시 사용되는 호스트 이름. HTTP(S) 접두사나 포트를 추가하지 마세요.
• ssl_keyfile - HTTPS용 SSL 키 경로. (예: privkey.pem)
• ssl_certfile - HTTPS용 SSL 인증서 경로. (예: fullchain.pem)
• registration_psk - OAuth 클라이언트 등록에 필요한 사전 공유 키. OAuth 연결을 승인하려면 브라우저에서 이 비밀을 입력해야 합니다.
• jwt_key_path - OAuth 토큰에 사용되는 RSA 키 쌍의 위치. 기본값은 .cache/jwt.json. 존재하지 않으면 자동 생성됩니다.
• oauth_db_path - OAuth 데이터베이스 파일 경로. 기본값은 .cache/oauth.db. 존재하지 않으면 자동 생성됩니다.
• enabled_tools - 등록할 도구 이름 목록. 빈 목록은 모든 도구를 활성화합니다. 사용 사례나 작업별로 도구를 선택적으로 활성화하는 것이 좋습니다. 몇 가지 예는 docs/ 폴더를 참조하세요.
• search_objects - search 도구에 허용되는 객체 유형. 기본값은 ["secret"]이지만 user, folder, group 및 role를 포함할 수 있습니다.
• fetch_objects - fetch 도구에 허용되는 객체 유형. 기본값은 ["secret"]이지만 search_objects와 동일한 값을 포함할 수 있습니다.

서버 실행

개발 모드에서 서버를 로컬로 시작:

python server.py

시작 시 서버는 베어러 토큰을 요청하고 이후 API 요청을 위해 저장합니다. 이 프로젝트는 Secret Server API와의 통합을 더욱 확장할 예정입니다.

MCP 도구

서버는 Secret Server, Delinea Platform ID 디렉터리 및 (선택적으로) StrongDM용 MCP 도구를 노출합니다. 모든 도구는 tools/list을 통해 동작 주석(읽기 전용/파괴적 힌트)을 게시합니다.

ChatGPT / deep-research 호환성

• search(query) - {id, title, url} 결과를 반환하는 통합 검색; 객체 유형은 search_objects 구성 키로 제한됩니다(기본값: 비밀만).
• fetch(id) - search이 표시한 단일 객체 검색; fetch_objects로 제한됩니다.

Secret Server

• run_report(sql_query, report_name=None) - 임시 보고서 생성 및 실행.
• ai_generate_and_run_report(description) - Azure OpenAI를 사용하여 SQL을 생성하고 실행. Azure OpenAI 변수가 필요합니다.
• list_example_reports() - 샘플 쿼리 및 테이블 정보 나열.
• get_secret(id, summary=False) - 비밀 또는 요약 세부 정보 검색.
• get_folder(id) - 폴더 메타데이터 및 하위 항목 가져오기.
• search_secrets(query, lookup=False) - 비밀 검색 또는 조회.
• search_folders(query, lookup=False) - 폴더 검색 또는 조회.
• get_secret_environment_variable(secret_id, environment) - 지정된 셸에서 비밀 자격 증명을 가져오는 스크립트 출력.
• check_secret_template(template_id) - 비밀 템플릿 세부 정보 가져오기.
• check_secret_template_field(template_id, field_id) - 템플릿에 필드가 포함되어 있는지 확인.
• get_secret_template_field(field_id) - ID로 특정 비밀 템플릿 필드에 대한 세부 정보 검색.
• handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - 액세스 요청 승인 또는 거부.
• get_pending_access_requests() - 대기 중인 액세스 요청 목록.
• get_inbox_messages(read_status_filter=None, take=20, skip=0) - 받은 편지함 메시지 검색.
• mark_inbox_messages_read(message_ids, read=True) - 메시지를 읽음 또는 읽지 않음으로 표시.
• create_secret_with_generated_password(name, secret_template_id, password_field_id, items, folder_id=None, site_id=None, comment=None) - 비밀번호가 서버 측에서 생성되는 비밀 생성; 정리된 메타데이터만 반환되며 값은 모델에 도달하지 않습니다.
• update_secret_generated_password(secret_id, field_slug, password_field_id, comment=None) - 값을 표면화하지 않고 서버 측에서 비밀의 비밀번호를 순환.
• update_secret_fields(secret_id, field_updates, comment=None, allow_password_fields=False) - 템플릿 읽기 → 비밀번호가 아닌 필드 변경 → 검증 흐름; 명시적으로 허용되지 않는 한 비밀번호 표시 필드를 거부합니다.
• set_secret_field_environment_variable(secret_id, field_slug, environment, source="stdin", comment=None) - 값을 로컬에서 읽어 비밀 필드에 푸시하는 셸 스크립트(bash/powershell/cmd)를 생성하므로 값이 모델을 완전히 우회합니다.
• bulk_user_response(user_ids, scenario, comment, confirm=False) - 대량 사용자 작업 API에 대한 의견 기반 인시던트 결합기. 시나리오: compromise, offboard, unlock, reenable, force_logout; confirm=True 및 비어 있지 않은 감사 주석이 필요하며, 확인되지 않은 경우 미리 봅니다.
• role_management(action, role_id=None, data=None, params=None) - 역할 관리. action은(는) list, get, create 또는 update일 수 있습니다. 역할을 나열할 때 params로 선택적 쿼리 매개변수를 전달하세요. 예: role_management("update", role_id=3, data={"name": "New Role"}).
• user_role_management(action, user_id, role_ids=None) - 사용자에게 역할 할당 또는 제거. action은(는) get, add 또는 remove이고 role_ids는 추가/제거 작업을 위한 역할 식별자 목록입니다.
• group_management(action, group_id=None, data=None, params=None) - 그룹 처리. action은(는) get, list, create 또는 delete일 수 있습니다. get/delete에는 group_id을, 그룹 생성 시에는 data을 제공하세요.
• folder_management(action, folder_id=None, data=None, params=None) - 폴더 관리. action은(는) get, list, create, update 또는 delete일 수 있습니다. get, update 또는 delete에는 folder_id을 제공하고 폴더 생성 또는 업데이트 시에는 data을 제공하세요.
• user_group_management(action, user_id, group_ids=None) - 사용자의 그룹 구성원 자격 관리. action은(는) get, add 또는 remove입니다. 구성원 자격을 추가하거나 제거할 때 group_ids 목록을 제공하세요.
• group_role_management(action, group_id, role_ids=None) - 그룹의 역할 제어. list, add 또는 remove 작업을 사용하세요. 추가 또는 제거 시 role_ids을 제공하세요.
• health_check() - Secret Server 상태 확인 엔드포인트를 쿼리하고 현재 서비스 상태를 반환합니다.

Delinea Platform 사용자 및 역할

v1.0.0부터 표준 사용자 도구는 Delinea Platform ID 디렉터리를 대상으로 합니다(platform_hostname + PLATFORM_SERVICE_* 자격 증명 필요; 없으면 도구는 실패하는 대신 안내를 반환합니다):

• user_management(action, user_id=None, data=None, username=None) - Platform 사용자 CRUD. action은(는) get, create, update, delete 또는 search을 허용합니다.
• search_users(query) - Platform 사용자 디렉터리 검색.
• platform_role_management(action, role_id=None, data=None, page_size=100, query="%") - Platform 역할 CRUD(list, get, create, update, delete); 역할 변경은 검색 기반이며 API 범위에 노출되지 않는 테넌트에 대해서는 안내를 반환합니다.
• platform_user_role_management(action, role_id, user_principals=None) - Platform 역할에 list, add 또는 remove 사용자.
• platform_user_management(...) - user_management의 더 이상 사용되지 않는 별칭.

Secret Server 로컬 사용자(레거시)

Platform이 구성되지 않은 SS 전용 배포의 경우:

• secretserver_local_user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - v1.0.0 이전의 Secret Server 사용자 작업: get, create, update, delete, list_sessions, reset_2fa, reset_password, lock_out. 예: secretserver_local_user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
• search_secretserver_local_users(query) - Secret Server의 로컬 사용자 저장소 검색.

StrongDM 도구(선택 사항, 실험적)

실험적: StrongDM 백엔드는 아직 실제 SDM 조직에 대해 검증되지 않았습니다(SDK 표면에 대해서만 단위 테스트됨). 거친 부분이 있을 수 있으며 문제를 보고해 주세요. strongdm 엑스트라를 통해 설치됩니다. 전체 가이드는 docs/strongdm.md를 참조하세요. sdm_search, sdm_audit_access, sdm_grant_access (시간 제한 적시 또는 상시 권한), sdm_revoke_access, sdm_user_management (온보딩/오프보딩 흐름), sdm_role_management, sdm_resource_health, sdm_access_requests, sdm_activity_report, sdm_network_status. 파괴적 작업은 감사 주석과 함께 확인 게이트가 적용됩니다. 모호한 이름 일치는 변경 없이 후보를 반환합니다.

위에서 설명한 서버 구성 변수를 사용하여 인증하세요. Azure OpenAI 변수가 없으면 AI 도구는 자동으로 비활성화됩니다. config.json에 나열된 도구 이름만 등록됩니다. 빈 목록은 모든 도구를 활성화합니다.

사용 사례

문서는 도구를 서버에 연결하기 위한 여러 워크플로를 다룹니다:

• ChatGPT 사용자 지정 커넥터
• Claude Desktop
• 원격 Claude 커넥터
• 관리용 openwebui
• VSCode Copilot

Docker 빠른 시작

로컬에 Python 종속성을 설치하지 않고 MCP 서버를 실행할 수 있도록 Dockerfile이(가) 제공됩니다.

1. 이미지를 빌드합니다:

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

2. 서버를 실행합니다(환경 변수를 통해 자격 증명을 전달):

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

위에 표시된 대로 config.json에 사용자 이름과 URL을 입력합니다.

컨테이너는 oauth.db 및 jwt.json을(를) /app/data에 저장합니다. 이 파일과 HTTPS 인증서가 실행 간에 유지되도록 볼륨(위에 mcp-data로 표시됨)을 마운트합니다.

연결 오류를 방지하려면 <https://your-secret-server/SecretServer>을(를) Secret Server 인스턴스의 기본 URL로 바꾸십시오.

서버는 기본적으로 python server.py을(를) 사용하여 포트 8000에서 시작됩니다. 기본값을 재정의하려면 config.json에서 port 옵션을 설정합니다. 들어오는 모든 HTTP 요청을 기록하려면 debug: true을(를) 활성화합니다.

예제 스크립트

manual_secret_request.py 스크립트는 특정 시크릿 ID에 대한 OAuth 토큰을 검색하는 방법을 보여줍니다:

python scripts/manual_secret_request.py <Secret_ID>

스크립트를 실행하기 전에 시크릿에 대한 환경 변수 SECRET_USERNAME_<id> 및 SECRET_PASSWORD_<id>을(를) 설정합니다. 선택적으로 DELINEA_BASE_URL을(를) 설정하여 기본 https://localhost/SecretServer을(를) 재정의합니다.

테스트 실행

커버리지와 함께 단위 테스트를 실행합니다(CI는 최소 70%를 적용):

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

실시간 테스트

일부 통합 테스트에는 유효한 자격 증명이 필요합니다. 테스트 스위트를 실행하기 전에 다음 환경 변수와 선택적 LIVE_SECRET_ID을(를) 설정합니다:

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>

이 변수가 있으면 실시간 테스트가 실제 API 요청을 수행합니다.

프로덕션 배포

종속성은 requirements.txt에 고정되어 있으며 릴리스는 시맨틱 버전 관리를 사용하여 태그가 지정됩니다. 태그가 지정된 커밋에서 Docker 이미지를 빌드하고 필수 환경 변수(DELINEA_USERNAME, DELINEA_PASSWORD, 선택적으로 DELINEA_BASE_URL)를 전달하여 프로덕션 환경에 배포합니다. 선택적 기능은 추가 변수에 의존합니다:

• PLATFORM_SERVICE_PASSWORD은(는) PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT 및 PLATFORM_TENANT_ID와 함께 사용자 관리 도구를 활성화합니다.
• AZURE_OPENAI_KEY은(는) AZURE_OPENAI_ENDPOINT 및 AZURE_OPENAI_DEPLOYMENT와 함께 AI 보고서 생성 도우미를 활성화합니다.
• SDM_API_ACCESS_KEY 및 SDM_API_SECRET_KEY은(는) 실험적 StrongDM 도구를 활성화합니다(strongdm 추가 기능 필요; docs/strongdm.md 참조).

OAuth 또는 SSE 전송으로 실행할 때 registration_psk을(를) 제공하고 external_hostname 또는 HTTPS 인증서 파일을 구성해야 할 수 있습니다.

저장소 구조

• delinea_mcp/ - MCP 도구를 포함하는 패키지: tools.py (Secret Server), user_platform_tools.py (Delinea Platform), secretserver_users.py (SS-로컬 사용자), strongdm_tools.py (StrongDM, 선택), transports/ (SSE + 스트리밍 가능 HTTP) 및 auth/ (내장 OAuth 권한 부여 서버).
• server.py - 모든 것을 MCP 서버에 등록하는 얇은 진입점.
• docs/ - 프로젝트 문서 및 생성된 delinea-secret-server-openapi-spec.json.
• scripts/ - manual_secret_request.py을(를) 포함한 도우미 예제.

보안 고려 사항

내장 OAuth 권한 부여 서버는 개발, 테스트 및 소규모 배포를 위한 편의 기능입니다. 대규모 배포에서는 조직의 ID 공급자로 서버 앞단을 구성해야 합니다. 현재 보호 장치:

• 클라이언트 등록(/oauth/register) 및 권한 부여 양식 모두 registration_psk 공유 비밀(상수 시간 비교)이 필요합니다.
• redirect_uri 값은 권한 부여 양식과 코드 리디렉션 모두에서 클라이언트에 등록된 URI에 대해 검증됩니다.
• 액세스 토큰은 대상(audience)이 바인딩된 RS256 JWT입니다. 리소스 검색은 RFC 9728(401/403 응답의 /.well-known/oauth-protected-resource 및 WWW-Authenticate 헤더)을 따릅니다.
• 항상 TLS(ssl_keyfile/ssl_certfile 또는 종료 프록시)로 배포하십시오. 베어러 토큰과 시크릿은 모든 요청에서 전송됩니다.
• enabled_tools을(를) 사용하여 사용 사례별로 도구 노출 범위를 지정합니다. 시크릿 _값_은 설계상 모델 컨텍스트에서 제외됩니다(서버 측 암호 생성, 환경 변수 스크립트 간접 참조, 암호 필드 가드).

릴리스 노트

최신 기능 및 로드맵 항목 요약은 CHANGELOG.md를 참조하십시오.

로드맵

1. 패스스루 인증
2. OAuth 클라이언트 ID 메타데이터 문서(CIMD) 클라이언트 지원(동적 클라이언트 등록은 MCP 프로토콜 개정 2026-07-28부터 더 이상 사용되지 않음. PSK 게이트 /oauth/register 흐름은 현재 커넥터에서 계속 작동함)
3. Delinea Platform의 도구 범위를 확장하고 다른 Delinea 제품 추가

기여

기여를 환영합니다! 개선 사항이 있으면 이슈 또는 풀 리퀘스트를 열어 주십시오. 모든 새 코드에는 단위 테스트가 포함되어야 하며 기존 테스트 스위트를 통과해야 합니다.

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.