요약
토스증권 Open API를 Claude에 연결하는 로컬 MCP 서버입니다. Claude에게 "내 포트폴리오 위험도 봐줘"라고 하면 시세·잔고·체결 내역을 직접 조회해서 답할 수 있게 만들었습니다.
2026년 6월 8일 하루 동안 Claude Code와 페어로 설계, 구현, 보안 리뷰, 실데이터 확인까지 마쳤습니다. 제 계좌에서만 쓰는 개인 도구이고, 주문 도구는 만들었지만 실제 주문은 아직 한 번도 내지 않았습니다.
| 항목 | 내용 |
|---|---|
| 도구 | 조회 16개 + 주문 3개 = MCP 도구 19개 |
| 코드 | 서버 약 800줄 + 분석 스크립트 약 500줄, 런타임 의존성은 MCP SDK 하나 |
| 검증 | 스모크 테스트 7/7, stdio 핸드셰이크에서 도구 19개 확인, 실계좌 조회 E2E 1회 |
| 보안 리뷰 | Critical 0 · High 0 · Medium 1 · Low 3 |
주문 권한을 어디까지 줄 것인가
AI가 증권 계좌에 접근할 때 가장 무서운 건 의도하지 않은 주문입니다. 설계 첫 단계에서 권한 정책부터 정했습니다.
| 단계 | 내용 |
|---|---|
| 선택지 | 조회만 허용 / 주문까지 자동 허용 / 조회는 자유, 주문은 매번 사람 승인 |
| 결정 | 세 번째. 주문 도구는 별도 설정으로 켜지 않으면 아예 동작하지 않고, 켜져 있어도 호출할 때마다 사람의 승인을 거칩니다 |
| 확인 | 정책을 정한 뒤 다른 증권 API 연동 사례를 찾아보니, 공식 연동들도 "미리보기 → 확인" 2단계를 쓰고 있었습니다 |
토큰은 하나, 주문은 재시도 없음
토스증권 API는 클라이언트당 토큰이 하나이고, 새로 발급하면 이전 토큰이 즉시 죽습니다. 여러 도구가 동시에 토큰을 요청하면 서로의 토큰을 무효화합니다.
- 토큰 발급은 단일 비행(single-flight) 캐시로 묶어 동시 요청이 와도 한 번만 발급합니다
- 토큰 버킷으로 호출 속도를 제한하고, 401이 오면 한 번만 다시 시도합니다
보안 리뷰에서는 "주문 요청이 재시도되면 같은 주문이 두 번 나갈 수 있다"는 지적이 나왔습니다. 주문 POST는 429나 401이 와도 자동 재시도하지 않게 바꾸고, 주문마다 무작위 clientOrderId를 붙여 중복을 막고, 요청 시간 제한을 15초로 걸었습니다.
실데이터에서 찾은 함정
실제 계좌로 조회해 보니 잔고 API의 "일간 손익"이 장중 세션 기준이었습니다. 한국 시간 아침에 보면 전날 미국장에서 크게 떨어진 보유 종목의 하락이 손익에 잡히지 않았습니다. 일간 등락은 일봉 종가 대비로 다시 계산하도록 바꿨습니다. 모의 데이터로만 테스트했다면 놓쳤을 문제입니다.
지금 상태
- 개인용 로컬 MCP 서버로 동작합니다. 공개 저장소나 배포는 없습니다
- 포트폴리오 브리핑, 미국장 요약 같은 Claude 스킬이 이 서버의 조회 도구를 씁니다
- 실주문 0건이라, 주문 경로는 설계와 리뷰까지만 검증된 상태입니다
배운 점
돈이 걸린 도구는 "할 수 있는 것"보다 "하면 안 되는 것"을 먼저 정해야 합니다. 권한 정책을 첫 단계로 두고, 재시도처럼 평소엔 좋은 습관이 주문에서는 사고가 된다는 점을 리뷰로 확인한 것이 이 프로젝트의 핵심이었습니다.