Siebel MCP Gateway

Oracle Siebel REST API를 streamable HTTP를 통해 MCP 도구로 노출하여, 에이전트 클라이언트가 Siebel 자격 증명을 직접 보유하지 않고도 Siebel 레코드를 조회/생성/업데이트/삭제하고 객체 카탈로그를 가져올 수 있게 합니다.

Mock 모드는 합성 헬스케어 추천 데모 스키마(환자 → 커뮤니티/병원 추천 → Form 17 약정 → 치료 이력)를 모델링하며, 문서화된 의도적인 데이터 품질 문제를 매끄럽게 덮지 않고 충실히 전달하도록 설계되었습니다. 두 조직에 걸친 중복 환자 레코드, 실제로는 긴급도를 담고 있는 상태 필드, Workflow의 명시된 한도를 조용히 덮어쓰는 스크립트, 서로 어긋나는 두 개의 "방문 잔여 횟수" 필드 등이 포함됩니다. 모든 데이터는 합성 데이터입니다.

스택

Python 3.12+, 공식 mcp SDK(MCPServer, 이전 SDK 버전에서 FastMCP라고 불리던 것의 현재 이름), 아웃바운드 Siebel 호출용 httpx, ASGI 서버로 uvicorn.

Related MCP server: MCP Gateway

로컬 실행

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Fill in .env, or for a first run without a live Siebel instance:
#   MOCK_MODE=true
#   MCP_GATEWAY_TOKEN=<any string you'll also give your client>
MOCK_MODE=true MCP_GATEWAY_TOKEN=dev-token \
  uvicorn app.server:app --host 0.0.0.0 --port 8000

헬스 체크: curl http://localhost:8000/healthz → {"status":"ok"} (인증 불필요, 플랫폼 헬스 체커가 동작할 수 있음).

MCP 엔드포인트: http://localhost:8000/mcp — 공개 배포 후에는 엔드포인트 자체에 다른 접근 제어가 없으므로 모든 요청에 Authorization: Bearer <MCP_GATEWAY_TOKEN>이 필요합니다.

테스트

python3 -m pytest -v

모든 테스트는 인메모리 mock 저장소 또는 mock HTTP 전송을 대상으로 실행됩니다. 네트워크 호출 없음, 실제 Siebel 인스턴스 불필요.

Render에 배포하기

1. 이 저장소를 GitHub에 푸시합니다.

2. 아직 연결되지 않았다면 먼저 Render에 저장소 접근 권한을 부여합니다. Render의 GitHub App은 명시적으로 접근 권한이 부여된 저장소만 볼 수 있습니다. 새 저장소는 소유자라도 Render의 저장소 선택기에 표시되지 않습니다. github.com/settings/installations로 이동 → Render 찾기 → Configure → "All repositories"로 전환하거나 이 저장소를 허용 목록에 추가 → Save. 그 후에야 Render의 연결 화면에 다시 나타납니다.

3. Render 대시보드에서: New → Blueprint ("Web Service"가 아님 — 이 저장소에는 render.yaml이 있으며 Blueprint가 이를 읽습니다). 저장소를 연결하고 main 브랜치와 기본 render.yaml 경로를 확인합니다.

4. Render는 render.yaml에서 sync: false로 표시된 모든 환경 변수에 대한 양식을 표시합니다. 배포 전에 다음을 입력하세요:

   • MCP_GATEWAY_TOKEN — 생성, 예: openssl rand -hex 32

   • MOCK_MODE — true로 설정하면 즉시 mock 데이터를 제공하기 시작합니다(실제 Siebel 인스턴스가 아직 준비되지 않은 경우 권장). 아래에 실제 Siebel 자격 증명을 입력할 수 있다면 false로 설정

   • SIEBEL_BASE_URL / SIEBEL_USERNAME / SIEBEL_PASSWORD — MOCK_MODE=false인 경우에만 필요. mock 모드로 시작하는 경우 비워 둡니다.

5. Deploy Blueprint를 클릭합니다. Render가 https://<your-service>.onrender.com을 할당합니다.

나중에 이러한 값을 변경하려면(예: 실제 Siebel 인스턴스가 준비되면 MOCK_MODE 전환): 서비스(Blueprint 아님)를 열고 → Environment 탭 → 값 편집 → Save Changes를 클릭하면 재배포가 트리거됩니다.

배포된 게이트웨이에 MCP 클라이언트 연결하기

• URL: https://<your-service>.onrender.com/mcp

• 전송: streamable HTTP

• 인증: OAuth가 아닌 정적 bearer 토큰/API 키 — 헤더를 Authorization: Bearer <MCP_GATEWAY_TOKEN>(위 4단계의 동일한 값)으로 설정합니다. 클라이언트의 인증 UI가 결합된 헤더 대신 헤더 이름과 원시 값을 별도로 요구하는 경우, 헤더 이름은 Authorization이고 값은 Bearer <token>("Bearer" 단어 포함)입니다. 401이 발생하면 일부 클라이언트가 Bearer 접두사를 자체적으로 추가하므로 원시 토큰만 제공해 보세요.

실제 배포에서 얻은 참고 사항

• Mock 저장소는 인메모리 전용입니다. 세션 중 생성/업데이트/삭제된 모든 것은 해당 서버 프로세스가 유지되는 동안만 유지됩니다. 재배포 또는 Render 무료 티어 인스턴스가 약 15분 유휴 후 종료되고 다음 요청 시 콜드 스타트되면 원래 시드 데이터로 재설정됩니다. 이는 예상된 mock 모드 동작이며 버그가 아닙니다.

• mcp Python SDK의 클라이언트 측 전송 종속성은 httpx2 입니다. 일반 httpx가 아닙니다. 이 게이트웨이에 대해 SDK의 streamable_http_client 헬퍼를 사용하여 자체 MCP 클라이언트를 작성하는 경우에만 관련됩니다. 고수준 클라이언트 앱 대신 http_client= 인수에 일반 httpx.AsyncClient가 아닌 httpx2.AsyncClient가 필요합니다.

실사용 전환 체크리스트

실제 Siebel 인스턴스가 준비되면:

• SIEBEL_BASE_URL을 실제 인스턴스로 설정(끝에 슬래시 없음), 예: https://<siebel-host>/siebel/v1.0

• SIEBEL_USERNAME / SIEBEL_PASSWORD 설정

• 인스턴스가 여전히 자체 서명 인증서를 사용하는 경우에만 SIEBEL_VERIFY_TLS=false 설정 — 실제 인증서가 있으면 true로 되돌리기

• MOCK_MODE=false 설정

• 재배포 후 실제 에이전트 트래픽을 보내기 전에 siebel_list_objects 및 search_facilities로 스모크 테스트

도구

일반용(모든 비즈니스 컴포넌트에서 작동: Contact, Employee, Medical Facility, Appointment Slot, Referral Request, Commitment Form, Treatment History):

편의 래퍼, 일반적인 데모 요청에 더 얇은 표면:

여기에 내장된 Siebel REST API 가정에 대한 참고 사항

• 모든 아웃바운드 호출에 HTTP Basic 인증이 사용됩니다(이 게이트웨이의 인바운드 MCP 요청에 대한 자체 bearer 토큰 검사와는 별개 — 두 개의 서로 다른 인증 계층, 혼동하지 마세요).

• URL 문법은 {BASE}/data/{BusinessObject}/{BusinessComponent}입니다. BO와 BC는 여기서 항상 같은 이름이 아닙니다. 예: Referral Request는 Patient Referral BO의 하위 BC이고, Appointment Slot은 Appointment Management의 하위 BC입니다. 도구는 BC 이름을 사용하며 클라이언트가 내부적으로 올바른 BO를 조회합니다. 경로 세그먼트는 URL 인코딩되므로 여러 단어 이름이 작동합니다.

• 목록 응답은 {"items": [...]}로 도착합니다. 각 레코드의 "links" 배열은 토큰을 절약하기 위해 모델에 반환하기 전에 제거됩니다.

• 2xx가 아닌 응답은 HTTP 상태 코드와 Siebel 자체 메시지 텍스트로 표시됩니다. 401은 "Siebel 자격 증명 확인" 접두사가 명확하게 붙습니다. 아웃바운드 호출은 30초 후에 시간 초과됩니다.

• 여러 필드는 계산 필드로 저장되지 않습니다(Age, Days Waiting, Visits Remaining, Is Expired, Entry Gap Days, Facility/Doctor/Patient 조인 필드) — 실제 비즈니스 컴포넌트의 계산/조인 필드처럼 물리적 열이 아닌 매 읽기마다 새로 파생됩니다.