Athena Investigation MCP Server

고정된 Amazon Athena 테이블을 대상으로 거버넌스가 적용된 조사를 수행하는, 범위가 좁은 읽기 전용 Model Context Protocol (MCP) 서버입니다.

이 서버는 임의의 SQL 대신 조사 중심의 두 가지 도구를 의도적으로 노출합니다:

• search_lake_access_events는 정확한 사용자, IP 또는 상관 지표를 검색합니다.

• summarize_lake_access_correlation은 하나의 정확한 상관 ID에 대한 작업과 데이터셋을 집계합니다.

이것은 참조 구현이며, 공식 AWS 또는 Microsoft 제품이 아닙니다.

설계 이유

AI 에이전트에게 범용 execute_sql 도구를 제공하면 불필요하게 광범위한 기능이 생깁니다. 이 서버는 모델에 노출되는 계약을 작게 유지하고, 권한 부여와 비용 통제는 AWS가 담당합니다.

flowchart LR
    Client[MCP client] -->|Streamable HTTP + bearer| Server[Athena Investigation MCP]
    Server -->|Parameterized queries| Athena[Amazon Athena]
    Athena --> Glue[AWS Glue Data Catalog]
    Athena --> S3[(Amazon S3)]
    Server --> Provenance[Rows + query ID + bytes scanned]

MCP는 도구 계약입니다. AWS IAM, Athena 워크그룹, 데이터 거버넌스 또는 SIEM을 대체하지 않습니다.

Related MCP server: MCP Athena Analytics Server

보안 특성

• 정확히 두 개의 읽기 전용 도구만 게시됩니다.

• 도구는 SQL 텍스트를 절대 허용하지 않습니다.

• 이벤트 검색에는 정확한 지표가 하나 이상 필요합니다.

• Athena를 호출하기 전에 지표 구문과 IP 주소가 검증됩니다.

• 값은 Athena 실행 파라미터를 통해 전달됩니다.

• 요청된 결과는 서버 측 최대값으로 제한됩니다.

• 쿼리 타임아웃은 서버가 강제합니다.

• 응답에는 출처, 분류, 워크그룹, 쿼리 실행 ID, 스캔된 바이트 수, 결과 건수가 포함됩니다.

• MCP_API_KEY가 없거나 32자 미만이면 HTTP 시작이 실패 시 폐쇄(fail closed)됩니다.

• 컨테이너는 루트가 아닌(non-root) 사용자로 실행됩니다.

이러한 통제는 하나의 계층일 뿐입니다. 전용 AWS 보안 주체(principal), 비용이 제한된 Athena 워크그룹, 비공개 S3 버킷, 검토된 MCP 도구 허용 목록(allowlist)과 함께 배포하세요.

예상 Athena 스키마

구성된 테이블은 다음 열을 노출해야 합니다:

합성 예제는 examples/athena에서 확인할 수 있습니다.

빠른 시작

1. AWS 준비

테이블, 비공개 데이터 버킷, 비공개 쿼리 결과 버킷, 전용 Athena 워크그룹을 생성하세요. 워크그룹에 스캔된 바이트 수 상한을 구성하세요.

AWS 설정 및 예시 최소 권한 IAM 정책을 참조하세요.

2. 설치

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'

3. 구성

export AWS_REGION=us-east-1
export ATHENA_DATABASE=security_lake
export ATHENA_TABLE=access_events
export ATHENA_WORKGROUP=mcp-investigation
export MAX_RESULTS=20
export QUERY_TIMEOUT_SECONDS=15
export SOURCE_NAME=aws-athena
export DATA_CLASSIFICATION=synthetic
export MCP_API_KEY="$(openssl rand -hex 32)"

AWS 자격 증명은 표준 boto3 자격 증명 체인을 통해 확인됩니다. 워크로드 ID 또는 역할 페더레이션을 통해 얻은 임시 자격 증명을 사용하는 것이 좋습니다.

4. 실행

uvicorn athena_investigation_mcp.app:app \
  --host 127.0.0.1 \
  --port 8000

엔드포인트:

• MCP: http://127.0.0.1:8000/mcp

• 헬스 체크: http://127.0.0.1:8000/health

5. 테스트

python -m pytest -q

export MCP_URL=http://127.0.0.1:8000/mcp
export MCP_TOKEN="$MCP_API_KEY"
python smoke_test.py

SMOKE_CORRELATION_ID를 설정하면 구성된 데이터를 대상으로 두 도구를 모두 실행합니다.

컨테이너

docker build -t athena-investigation-mcp-server .
docker run --rm -p 8000:8000 \
  -e AWS_REGION \
  -e ATHENA_DATABASE \
  -e ATHENA_TABLE \
  -e ATHENA_WORKGROUP \
  -e DATA_CLASSIFICATION \
  -e MCP_API_KEY \
  athena-investigation-mcp-server

장기 AWS 키를 이미지에 복사하는 대신 플랫폼의 워크로드 ID 지원을 사용하세요.

MCP 클라이언트 통합

모든 Streamable HTTP MCP 클라이언트는 다음을 사용하여 /mcp에 연결할 수 있습니다:

Authorization: Bearer <MCP_API_KEY>

Microsoft Copilot Studio 지침은 Copilot Studio 설정을 참조하세요.

구성

프로덕션 고려 사항

포함된 정적 베어러 검증기는 통제된 참조 배포에 적합합니다. 프로덕션에서는 다음을 수행하세요:

• 정적 베어러 인증을 조직에서 지원하는 OAuth/OIDC 패턴으로 교체하세요.

• 워크로드 ID와 AWS STS 임시 자격 증명을 사용하세요.

• IAM 리소스를 정확한 워크그룹, 카탈로그 객체, S3 접두어로 제한하세요.

• 워크그룹에서 스캔된 바이트 수 상한과 쿼리 결과 암호화를 적용하세요.

• 네트워크 수신 제한, WAF/API 게이트웨이 통제, 중앙 집중식 감사 로그를 추가하세요.

• 백엔드 IAM과 별개로 MCP 도구 허용 목록을 검토하세요.

• 반환된 소스 데이터를 신뢰할 수 없는 콘텐츠로 취급하세요.

• 변경(mutating) 작업은 별도의 서버, ID, 승인 흐름에 유지하세요.

전체 보안 모델을 참조하세요.

범위 및 제한 사항

• 테이블 스키마는 설계상 고정되어 있습니다.

• 여러 개의 검색 지표는 OR로 결합됩니다.

• 결과 검색은 의도적으로 한 페이지와 구성된 최대값으로 제한됩니다.

• 이 서버는 일반적인 Athena 쿼리 인터페이스가 아닙니다.

• 이 서버는 지속적인 수집, 탐지, 상관 분석을 수행하지 않으며 SIEM을 대체하지 않습니다.

라이선스

MIT