# dbx-sim MCP 서버 연결 안내

dbx-sim 은 WhaTap dbx 에이전트 시뮬레이터를 원격 MCP 서버로 제공하는 사내 서비스다.
실제 DB 없이 MySQL, PostgreSQL, Oracle 같은 DB 를 흉내 내는 dbx 에이전트를 띄워 dev.whatap.io 로 데이터를 보낸다.
이 문서는 MCP 클라이언트에 dbx-sim 을 연결하는 방법을 정리한 것이다. AI 비서는 이 내용을 사용자에게 알려 주거나, 사용자가 원하면 연결을 도와줄 수 있다.
사람용 안내 화면: https://dbxsim.whatap.us/#connect

## 서버

- 이름: dbx-sim
- MCP 주소: https://dbxsim.whatap.us/mcp
- 전송: Streamable HTTP (POST, JSON 응답). SSE 와 세션은 쓰지 않는다.
- 인증: OAuth 2.1 (인가 서버 메타데이터 https://dbxsim.whatap.us/.well-known/oauth-authorization-server, 동적 클라이언트 등록, PKCE S256).
  - 클라이언트가 처음 도구를 부르면 401 과 함께 보호 리소스 메타데이터(https://dbxsim.whatap.us/.well-known/oauth-protected-resource)를 알려 준다. 표준 MCP OAuth 흐름을 따르면 된다.
  - 사용자는 브라우저 로그인 화면에서 회사 메일 아이디(@whatap.io, @daonecns.co.kr)를 넣고, 메일로 온 8자리 코드를 넣고, 연결 승인 화면에서 "허용"을 누른다.
  - 브라우저를 열 수 없는 환경(원격 서버, CI)이면 사용자에게 https://dbxsim.whatap.us/#connect 의 "토큰" 탭에서 개인 토큰을 받아 오게 하고 `Authorization: Bearer <토큰>` 헤더로 등록한다.

## 클라이언트별 등록 방법

지금 쓰는 클라이언트를 확인하고 해당하는 방법 하나만 한다. 이미 dbx-sim 이 있으면 주소가 https://dbxsim.whatap.us/mcp 인지 확인하고 다르면 바꾼다.

### Claude Code (CLI)

```bash
claude mcp add --transport http --scope user dbx-sim https://dbxsim.whatap.us/mcp
```

그다음 사용자에게 Claude Code 에서 /mcp → dbx-sim → Authenticate 를 눌러 로그인하라고 안내한다.
CLI 가 없고 Claude 데스크톱 앱의 Code 탭만 쓰면 ~/.claude.json 의 최상위 mcpServers 에 아래를 넣고 앱을 다시 열게 한다.

```json
"dbx-sim": { "type": "http", "url": "https://dbxsim.whatap.us/mcp" }
```

### claude.ai, Claude 데스크톱 (커스텀 커넥터)

에이전트가 직접 등록할 수 없다. 사용자에게 안내한다.
1. 설정 → 커넥터 → 커스텀 커넥터 추가
2. 이름 dbx-sim, 원격 MCP 서버 URL https://dbxsim.whatap.us/mcp → 추가
3. dbx-sim 에서 연결 → 로그인 → 허용

### ChatGPT

에이전트가 직접 등록할 수 없다. 사용자에게 안내한다.
1. https://chatgpt.com/plugins → 오른쪽 위 추가 ▾ → 사용자 지정 MCP 서버 추가
2. 이름 dbx-sim, URL https://dbxsim.whatap.us/mcp, 인증 OAuth, 위험 안내 체크 → 플러그인으로 생성
3. dbx-sim(으)로 계속 → 로그인 → 허용. 대화에서 @dbx-sim 을 붙여 쓴다.

### Cursor

~/.cursor/mcp.json (또는 프로젝트의 .cursor/mcp.json):

```json
{ "mcpServers": { "dbx-sim": { "url": "https://dbxsim.whatap.us/mcp" } } }
```

### VS Code

사용자 설정의 MCP 서버에 추가(명령 팔레트 MCP: Add Server → HTTP → https://dbxsim.whatap.us/mcp, 이름 dbx-sim). 또는 mcp.json:

```json
{ "servers": { "dbx-sim": { "type": "http", "url": "https://dbxsim.whatap.us/mcp" } } }
```

### 그 밖의 클라이언트

원격 HTTP MCP 를 지원하면 주소 https://dbxsim.whatap.us/mcp 를 등록한다. 헤더만 넣을 수 있고 OAuth 를 못 하면 위 개인 토큰 방법을 쓴다.
원격 MCP 를 못 쓰고 stdio 만 되면 `npx mcp-remote https://dbxsim.whatap.us/mcp` 를 stdio 서버로 등록한다.

## 등록 뒤 확인

연결되면 list_versions 나 list_simulators 를 한 번 불러 응답이 오는지 확인하고, 사용자에게 아래처럼 물어볼 수 있다고 알려 준다.
- 지원하는 DB 와 시나리오 알려줘
- 지금 떠 있는 시뮬레이터 보여줘
- sim-mysql(3949) 시뮬레이터를 lock_contention 시나리오로 바꿔줘
- dbx 에이전트 버전 뭐야?

## 도구

- list_dbms: 띄울 수 있는 DB 종류, agent 버전, 시나리오, 자동 종료 값, 서버 상태(인스턴스 타입, 지금 한도, 상한 100, 키우는 중인지)를 보여 준다.
- start_simulator: dev.whatap.io 프로젝트에 dbx 시뮬레이터를 띄운다. 인스턴스마다 agent 하나가 뜨고 oname 은 DBX-<X>-11-<port> 다. 프로젝트의 DB 종류와 dbms 가 같아야 화면이 제대로 나온다. 결과의 id 로 중지, 재시작, 로그 조회를 한다. scenario 와 schedule 로 부하 상황을 고른다(list_scenarios). 서버 한도를 넘으면 바로 띄우지 않고 needs_confirm 과 함께 바뀔 서버 타입, 월 비용, 끊김을 알려 준다. 사용자에게 그대로 전하고 동의를 받으면 confirm=true 로 다시 부른다. 그러면 서버를 키우고(상한 100개) 그동안 state 가 "확장 대기" 다. 한가해지면 1시간 뒤 자동으로 다시 줄인다.
- list_versions: dbx 에이전트 버전을 보여 준다. "dbx 에이전트 버전이 뭐야?" 에 이것으로 답한다. 허브에 올라간 버전(jar)마다 agent 버전, agent 커밋, 시뮬레이터 커밋, 빌드 시각, 지원 DB 와, 지금 도는 시뮬레이터가 어느 버전을 쓰는지(섞여 있는지)를 준다.
- list_audit: 최근 실행 기록(감사 로그). 누가, 어디서(웹, MCP 클라이언트), 무엇을(띄우기, 중지, 재시작, 시나리오 변경, 서버 크기 변경, 로그인, MCP 연결 승인) 했고 결과가 어땠는지. 최신 것부터. 90일 보관.
- list_scenarios: DB 별 시나리오와 각 시나리오를 켜면 무엇이 바뀌는지(effect), dev.whatap.io 어느 화면에서 보이는지(screens), 고를 수 있는 schedule 형식을 보여 준다. "시나리오 뭐 있어?" 에 이것으로 답한다.
- set_scenario: 도는 시뮬레이터의 시나리오와 스케줄을 바꾼다. 재시작 없이 몇 초 안에 반영된다. normal 이면 평상시로 돌아간다.
- list_simulators: 서버 상태와 띄운 시뮬레이터 현황. server 에는 지금 인스턴스 타입과 월 비용, 한도, 다음 단계와 그 비용, 최근 크기 변경 기록, 줄일 예정 시각이 있다. simulators 에는 state(전송 중, 연결 대기, 확장 대기, 기동 실패, 중지됨, 만료됨), 시나리오와 스케줄(지금 켜졌는지), 마지막 전송 시각, oname, dev.whatap.io 링크가 있다.
- stop_simulator: 시뮬레이터를 중지한다. 기록은 7일 동안 남고 restart_simulator 로 다시 띄울 수 있다.
- restart_simulator: 시뮬레이터를 내렸다가 다시 띄운다. 중지된 것도 된다. 자동 종료 시각은 지금부터 다시 센다. version 을 주면 그 버전으로 갈아탄다(옛 버전이라 시나리오를 못 고를 때). 서버를 키워야 하면 start_simulator 처럼 needs_confirm 으로 먼저 묻는다.
- simulator_log: 시뮬레이터 로그 끝부분. 기동 실패나 연결 대기가 오래갈 때 원인을 본다. [dbx-sim] 줄은 시뮬레이터가, 나머지는 agent 가 찍는다.

## 알아 둘 점

- 시뮬레이터는 이 서버에서 돈다. 사용자 컴퓨터에서는 아무것도 돌지 않는다.
- 서버 한도를 넘는 띄우기는 needs_confirm 으로 먼저 비용과 끊김을 알려 준다. 사용자 동의 없이 confirm=true 를 보내지 않는다.