MCP 서버
tossctl을 MCP(Model Context Protocol) 서버로 노출 — 공식 조회·주문에 더해 WTS 전용 기능까지 에이전트가 자연어로 사용
tossctl mcp 는 tossctl 을 MCP(Model Context Protocol) 서버로 띄웁니다. Claude Code·Claude
Desktop·Codex 등 MCP 호스트에 등록하면, 에이전트가 자연어로 계좌·잔고·시세·호가·체결·캔들(공식)과
인기 순위·수급·AI 시그널·스크리너·업종·어닝·브리핑·배당 등 WTS 전용 조회까지 다루고,
주문(매수/매도·취소·정정) 도 실행할 수 있습니다. stdin/stdout(JSON-RPC 2.0)으로 동작하며 별도
서버·포트가 필요 없습니다.
빠른 시작 — 3단계
MCP 는 tossctl 바이너리의 한 모드라 CLI 를 먼저 설치한 뒤 인증(공식 키·웹 세션 중 최소
하나)을 연결하고 호스트에 등록하면 됩니다.
# 1) tossctl 설치
curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh
# 2) 인증 — 하나만 있어도 시작됩니다 (없는 인증의 오퍼레이션만 비활성)
tossctl openapi login # 공식 Open API: 공식 조회 + 주문
tossctl auth login # WTS 웹 세션: WTS 전용 조회(인기순위·수급·AI시그널 등)
# 3) MCP 호스트에 등록 + 연결 확인 (Claude Code 예시)
claude mcp add tossctl tossctl mcp
claude mcp list # → "tossctl: tossctl mcp - ✔ Connected"Claude Desktop·Codex 등 JSON 설정 방식 호스트는 아래 JSON 설정을 쓰세요.
왜 catalog 방식인가 — 상시 컨텍스트를 3개로 고정
MCP 의 고질적 비용은 툴 스키마가 모델 컨텍스트에 상시 상주한다는 점입니다. API 하나당 툴 하나로 등록하면 그 툴의 이름·설명·파라미터 스키마 전부가 대화 내내 컨텍스트를 차지합니다. tossctl 의 API 표면은 40여 개 오퍼레이션(계속 증가) — 개별 툴로 노출하면 그만큼의 스키마가 항상 떠 있어 토큰을 먹고, 비슷한 툴 사이 오판(툴 선택 노이즈)도 커집니다.
tossctl 은 KIS_MCP_Server 의 catalog 모드를 참조해, 앞단에 고정 3개 툴만 노출하고 나머지 오퍼레이션 전부는 필요할 때만 스키마를 꺼내오는 구조로 뒤에 둡니다.
| 툴 | 역할 |
|---|---|
list_operations | 사용 가능한 오퍼레이션 목록(id·요약·backend·write 여부) 조회, query 로 필터 |
describe_operation | 특정 오퍼레이션의 파라미터 스키마를 그 순간에만 조회 |
call_operation | id + 파라미터로 실제 호출 |
결과: 상시 컨텍스트 = 딱 3개 툴 스키마. 오퍼레이션이 40개든 100개든 상주 비용은 3으로
고정됩니다. 에이전트는 list_operations 로 찾고 → describe_operation 으로 그때 스키마를 읽고 →
call_operation 으로 호출하므로, 안 쓰는 오퍼레이션의 스키마가 컨텍스트를 차지하지 않습니다.
업데이트는 자동입니다
호스트는 tossctl mcp 라는 명령어를 저장해 세션마다 새로 실행하므로, brew upgrade tossinvest-cli(또는 tossctl update)로 바이너리만 갱신하면 다음 세션·호스트 재시작 때 새
오퍼레이션이 재등록 없이 반영됩니다(catalog 는 서버 시작 시 바이너리에서 구성). 현재 노출되는
오퍼레이션 전체 목록은 항상 list_operations 가 정답입니다.
노출 범위 — 조회는 공식+WTS, 쓰기는 공식 전용
MCP 는 조회를 공식 Open API + WTS 전용 기능 모두 노출하고, 주문(write)은 공식 API 경로만
씁니다. 각 오퍼레이션은 list_operations 결과에 backend("wts" 또는 공식)로 표시됩니다.
- 조회(read) — 공식 API(계좌·시세·호가·체결·캔들 등)와 WTS 전용(인기 순위·수급·AI 시그널·
스크리너·업종·어닝·브리핑·배당·실현손익·거래내역·관심종목 등, 공식으로 막히는 것 →
tossctl 로 되는 것 참고)을 함께 노출합니다. WTS 조회는 웹 세션이 필요하고, 없으면 해당 오퍼레이션이
tossctl auth login안내를 돌려줍니다. - 주문(write) — 생성·취소·정정은 항상 공식 API 경로만 사용합니다(WTS 미경유). 에이전트에 주문을 맡기는 이상 제출 경로는 토스가 공식 승인한 API 여야 안전하고 정직하기 때문입니다.
- 인증 분리 — 공식 조회·주문은 공식 키(
openapi login), WTS 조회는 웹 세션(auth login). 둘 중 하나만 있어도 MCP 서버는 뜨고, 각 오퍼레이션이 자기에게 필요한 인증을 확인합니다.auth_status오퍼레이션으로 어떤 백엔드가 연결됐는지·언제 만료되는지 진단할 수 있습니다.
주문 안전 게이트
주문 실행은 CLI(tossctl order)와 동일하게 게이트됩니다. 안전 모델 참고.
- config 의
trading.*+allow_live_order_actions토글로 켜야 함 (기본 전부 꺼짐) - 기본 호출은 dry-run preview(
confirm_token·경고 반환) - 실제 제출은
execute: true+confirm: <token>을 함께 넘겨야 함 - 주문은 공식 API 경로만 사용(WTS 미경유)
자율 에이전트엔 조회 전용 권장
config 에서 trading.* 를 끈 상태(기본값)면 MCP 는 조회만 가능하고, 주문 오퍼레이션은 호출돼도
게이트에서 막힙니다. 거래까지 열려면 사람이 명시적으로 config 를 켜야 하며, 실제 제출은 매번
execute:true + 유효한 confirm 토큰이 필요합니다.
MCP 호스트 JSON 설정
Claude Code 는 위 빠른 시작의 claude mcp add 한 줄로 끝납니다. Claude
Desktop·Codex 등 JSON 설정 방식 호스트는 다음을 설정 파일에 넣으세요(tossctl 이 PATH 에 있어야
합니다).
{
"mcpServers": {
"tossinvest": { "command": "tossctl", "args": ["mcp"] }
}
}CLI 와 MCP — 언제 무엇을 (상호 보완)
같은 tossctl 바이너리의 두 입구이고, 둘 다 AI 에이전트와 잘 맞습니다. 경쟁이 아니라 연결
방식이 다를 뿐입니다.
CLI (tossctl ...) | MCP (tossctl mcp) | |
|---|---|---|
| 실행 방식 | 셸 명령 | 구조화된 MCP 툴 (JSON-RPC, 셸 불필요) |
| 어디서 | 셸이 있는 어디서든 — 터미널·스크립트·cron, 그리고 셸을 쓰는 AI 에이전트 | MCP 네이티브 호스트 — 오퍼레이션을 툴로 호출 (catalog 3툴로 컨텍스트 최소화) |
| 에이전트가 아는 법 | 프롬프트·스킬·AGENTS.md/CLAUDE.md 로 알려줘야 함 | 등록 시 툴 목록에 자동 노출 |
| 인증 | 웹 세션만으로 전부 동작(공식 키 연결 시 자동 라우팅) | 공식 조회·주문엔 공식 키, WTS 조회엔 웹 세션 — 최소 하나 |
| 커버 범위 | 전부 — 공식 + WTS(조회·주문·실시간 스트리밍·관심종목 쓰기 등) | 조회는 공식+WTS, 주문은 공식 경로. 실시간 스트리밍·WTS 쓰기는 미포함 |
- 스크립트·cron·파이프·재현 가능한 자동화는 CLI 가 자연스럽습니다(같은 명령 = 같은 결과).
- MCP 네이티브 에이전트는 등록만 하면 별도 안내 없이 툴로 호출합니다.
- 무엇을 쓰든 조회 데이터·주문 안전 게이트는 동일합니다.
전체 명령·오퍼레이션은 명령 레퍼런스, 공식 vs WTS 경로 차이는 자동 라우팅 가이드를 참고하세요.