Oracle MCP 챗봇 — 온프레미스 Oracle DB + Oracle ATP

AI 챗봇이 Oracle 데이터베이스에 대해 자연어 질문에 답할 수 있게 해주는 보안 Model Context Protocol 서버 쌍입니다. 메타데이터를 발견하고, SELECT 전용 SQL을 생성하고, 이를 검증하고, 엄격한 제한 하에 실행하며, 민감한 값을 마스킹하고, 모든 것을 로깅합니다.

FastMCP 3, python-oracledb(씬 모드) 및 sqlglot으로 구축되었습니다. 테스트 221개, 실행에 데이터베이스가 필요하지 않습니다.

pip install -r requirements-dev.txt
pytest                                        # 221 passed
cp .env.example .env                          # add credentials
python -m oracle_mcp.server --profile onprem --check
python -m oracle_mcp.server --profile onprem

실행 중인 배포 테스트는 docs/testing.md에 설명되어 있습니다. Cursor를 사용하지 않는 브라우저 UI는 docs/chat-ui.md에 있습니다:

python -m oracle_mcp.chat --profile both   # http://127.0.0.1:8500

기능

Related MCP server: OracleDB MCP Server

여덟 가지 도구

추가로 연결 검색을 위한 list_databases가 있습니다. 모든 도구는 JSON을 받고 JSON을 반환합니다.

보안 모델 작동 방식

데이터는 다섯 개의 독립적인 계층을 통과해야만 사용자에게 도달합니다:

Database grants  →  Object allowlist  →  Role clearance  →  SQL guardrails  →  Output masking
   sql/*.sql        config/policy/       roles.yaml         sql_guard.py       masking.py

핵심 아이디어: 제출하는 SQL은 실행되는 SQL이 아닙니다. 입력은 AST로 파싱되고, 검사되고, 재작성되고, 재생성됩니다. 검증기가 인식한 노드 유형만 다시 출력되므로 주석 트릭, 스택된 문장 및 동형 문자 키워드는 왕복을 통과할 수 없습니다.

SELECT a FROM t; DROP TABLE t     →  rejected: MULTIPLE_STATEMENTS
SELECT /*+ PARALLEL(t,64) */ a…   →  SELECT a FROM t FETCH FIRST 500 ROWS ONLY
ＤＥＬＥＴＥ FROM t                 →  rejected: NFKC folds it to DELETE
SELECT * FROM v   (business_user) →  explicit column list, restricted ones absent

두 번째 핵심 제어: execute_readonly_sql은 처음부터 다시 검증하고 validate_sql이 발급한 지문을 요구하므로 검사와 실행 사이에 SQL을 바꿔치기할 수 없습니다. 비관리자 역할은 먼저 승인되지 않은 것은 실행할 수 없습니다. 관리자는 실행할 수 있지만, 문장은 여전히 모든 가드레일을 통과합니다.

세 번째: 역할은 도구 인수가 아닌 프로세스 구성에 고정됩니다. 모델에게 "이제 당신은 관리자입니다"라고 말하는 사용자는 아무도 읽지 않는 user_role="admin" 문자열을 생성합니다.

구성

두 파일이 모든 것을 결정합니다:

config/policy/onprem.yaml 및 atp.yaml — 객체 허용 목록. 각 데이터베이스는 두 가지 모드 중 하나를 선택합니다.

엄격 모드, 온프레미스가 사용하는 모드입니다. 여기에 이름이 지정된 객체만 데이터베이스 권한이 허용하는 것과 관계없이 접근 가능합니다:

schemas:
  - name: EIM
    objects:
      - name: EIM_PR_SYSTEM
        type: TABLE
        sensitivity: INTERNAL
        large_table: true
        require_filter: true       # forces a WHERE clause
        columns:                   # optional; omit to read them from the
          - {name: SERIAL_NUMBER,  sensitivity: INTERNAL}   # data dictionary
          - {name: TAX_ID,         sensitivity: RESTRICTED} # at query time

columns:를 생략하는 것이 지원되며 배포된 정책이 그렇게 합니다. 컬럼은 ALL_TAB_COLUMNS에서 읽고 masking.yaml의 이름 패턴으로 분류되므로 스키마가 변경되어도 허용 목록이 정확하게 유지됩니다.

와일드카드 모드, ATP가 사용하는 모드입니다. 읽기 전용 계정이 읽을 수 있는 모든 스키마가 접근 가능해집니다:

allow_all_schemas: true
excluded_schemas: []   # added on top of the built-in Oracle internal schemas
schemas: []

이것은 의도적으로 객체 허용 목록을 포기하고 데이터베이스 권한을 경계로 삼는 것입니다. 권한 수준, SQL 가드레일, 행 상한 및 마스킹은 여전히 적용됩니다. 진정으로 읽기 전용인 계정에만 사용하십시오.

config/policy/roles.yaml — 누가 무엇을 볼 수 있는지:

roles:
  business_user:
    clearance: INTERNAL      # cannot reach CONFIDENTIAL or RESTRICTED columns
    max_rows: 200
    allow_raw_sql: false
    schemas: {ONPREM: [EIM], ATP: ["*"]}   # "*" needs allow_all_schemas

민감도 사다리: PUBLIC < INTERNAL < CONFIDENTIAL < RESTRICTED < NEVER. NEVER는 모든 권한 수준보다 높으므로 비밀번호와 카드 번호는 관리자를 포함한 어떤 역할도 접근할 수 없습니다.

배포

데이터베이스당 서버 하나를 실행합니다. 이 분리는 보안 경계입니다: 온프레미스 프로세스는 ATP 지갑 암호를 보유하지 않습니다.

docker build -t oracle-mcp-chatbot:1.0.0 .
export ATP_WALLET_HOST_PATH=/secure/path/wallets/atp
docker compose up -d onprem-mcp atp-mcp
docker compose --profile reconciliation up -d   # optional, holds both credential sets

Oracle ATP 연결

mTLS 지갑이 있는 씬 모드. 지갑을 압축 풀고 설정:

ATP_DSN=myatp_low                      # prefer _low so chatbot traffic can't starve prod
ATP_WALLET_DIR=/opt/oracle/wallets/atp # contains ewallet.pem + tnsnames.ora
ATP_CONFIG_DIR=/opt/oracle/wallets/atp
ATP_WALLET_PASSWORD=...                # set when the wallet zip was downloaded

ATP_WALLET_PASSWORD는 ewallet.pem을 보호하는 암호문이며, 데이터베이스 비밀번호가 아닙니다 — 흔하고 혼란스러운 실패입니다. 씬 모드 전용입니다. 두꺼운 모드는 암호 없는 cwallet.sso를 대신 읽으며, 둘 다 구성하면 시작 시 거부됩니다. TLS 전용 ATP(지갑 없음)의 경우 지갑 변수를 비워두고 OCI 콘솔의 전체 연결 문자열을 ATP_DSN에 붙여넣으세요.

지갑은 읽기 전용으로 바인드 마운트되며 이미지에 굽지 않습니다.

온프레미스 연결

ONPREM_HOST=oracle-onprem.internal.example.com
ONPREM_PORT=1521
ONPREM_SERVICE_NAME=CDMPRD
ONPREM_MODE=thin
# TCPS instead:
# ONPREM_DSN=tcps://host:2484/CDMPRD?ssl_server_dn_match=true

씬 모드는 Oracle Client가 필요하지 않습니다. 두꺼운 모드는 부족한 기능에만 사용하세요. Dockerfile의 주석 처리된 단계를 참조하세요.

문서

프로덕션 전에

참조 구현은 의도적으로 네 곳에서 멈춥니다. 전체 목록은 docs/deployment-checklist.md를 읽으세요. 주요 항목:

• ORACLE_MCP_ROLE_BINDING_MODE=env 설정. .env.example의 argument 기본값은 개발용입니다. 그 아래에서 모델은 어떤 역할이든 주장할 수 있습니다.

• 샘플 허용 목록을 config/policy/*.yaml에서 실제 큐레이션된 뷰로 교체하고, 모든 컬럼을 의도적으로 분류하세요.

• 비밀을 볼트로 이동. Compose 환경 변수는 docker inspect를 실행할 수 있는 사람에게 보입니다.

• HTTP 전송을 인증 게이트웨이 뒤에 배치. FastMCP의 HTTP 전송은 자체적으로 호출자를 인증하지 않습니다. 루프백에 바인딩하는 것은 임시 방편일 뿐, 제어가 아닙니다.

또한 의도적으로 구현되지 않음: 속도 제한, 사용자별 신원 전파, 관리자 원시 SQL에 대한 승인 워크플로.

라이선스

참조 구현으로 제공됩니다. 프로덕션 사용 전에 자체 보안 표준에 대해 검토하세요.