# A축 1편 실행 기록 — alpacahq/alpaca-mcp-server

실행일 **2026-09-21** (UTC 07:32~07:37 / KST 16:32~16:37).
환경: macOS 26.6.2 · arm64 · uv 0.10.12 · CPython 3.12.13.

> **계정 성격: 페이퍼 확정.** `paper-api.alpaca.markets` 200, `api.alpaca.markets`(실계좌) **401 unauthorized**.
> 계좌번호 접두사 `PA`, 초기 현금 $100,000. **실주문·실계좌 접근 없음. 가입 없음.**
> 키 값은 이 디렉터리 어디에도 기록하지 않았다. 계좌 id·번호는 `01-account-paper.json` 에서 마스킹했다.

## 파일

| 파일 | 내용 |
|---|---|
| `01-account-paper.json` | 페이퍼 계좌 조회 (id·계좌번호 마스킹) |
| `02-account-live-probe.json` | 실계좌 엔드포인트 401 — 이 키에 실계좌 권한 없음 |
| `10-venv.txt` · `11-install.txt` · `12-piplist.txt` | 설치 (캐시 있음) |
| `13-install-cold.txt` | **콜드 캐시 설치 실측 2.295초 / 67패키지** |
| `14-help.txt` | CLI 옵션 |
| `20-tools-list.txt` | `tools/list` → **72개** (실측) |
| `21-clock-account.txt` | `get_clock` · `get_account_info` |
| `22-s5-stock-closed.txt` | **벽 1** — 장 마감 중 주식 시장가 주문 → `accepted`, `filled_qty 0` |
| `23-s5-crypto-buy.txt` · `24-s5-crypto-fill.txt` · `25-s5-crypto-sell.txt` | **S5** 크립토 1회 왕복 |
| `26-reject-paths.txt` | **실패 경로 4종** (최대/최소 명목·자산없음·중복 client_order_id) |
| `27-liquidity-test.txt` | 0.0002 BTC vs 1.0 BTC 체결가 대조 |
| `28-close-position.txt` | 포지션 청산 |
| `29-d-bracket.txt` | **시나리오 D** 브래킷 3다리 |
| `30-s8-reconnect.txt` | **S8** MCP 서버 SIGKILL → 새 프로세스 재접속 |
| `31-activities.txt` | `get_account_activities_by_type FILL` — 체결 기록 반출 |
| `32-toolsets.txt` | `ALPACA_TOOLSETS` 로 주문 툴 제거 |
| `33-cleanup.txt` · `34-final-state.txt` | 전량 취소·정리 |
| `35-crypto-quote-bug.txt` | 필수 파라미터 누락 시 `{loc}` 템플릿이 그대로 전송됨 |
| `36-depth-vs-fill.txt` | **핵심 측정** — 호가 잔량의 995배 주문이 +5.92bp 로 전량 체결, 호가 불변 |
| `37-news-envelope.txt` | `get_news` 응답의 `external_text` 신뢰 경계 봉투 |
| `40-github.json` · `41-pypi.json` | 저장소·패키지 메타 (2026-09-21 관측) |

## 핵심 실측값

| | 값 |
|---|---|
| 콜드 설치 | **2.295초**, 67패키지 (`uv pip install --no-cache`) |
| MCP 툴 수 | **72** (`serverInfo` 는 `Alpaca MCP Server 3.4.7`, PyPI 패키지는 `2.3.2`) |
| 주식 시장가(장 마감 중) | `status=accepted`, `filled_qty=0`, `expires_at` 당일 20:00Z |
| 크립토 체결 지연 | 제출 → `filled_at` **약 2.3ms** (07:33:17.973465 → .975759) |
| 크립토 수수료 | 매수는 **현물 차감**(0.0005 → 0.00049875 = 25bp), 매도는 USD 차감 |
| 호가 잔량 | ask **0.001005 BTC** (약 $82) |
| 995배 주문 | 1.0 BTC 시장가 → **전량 체결**, 평균 81,599.95 = 호가 대비 **+5.92bp** |
| 체결 후 호가 | bid/ask **변화 없음** (81,531.58 / 81,551.68 동일) |
| 부분체결 분할 | 1.0 BTC → 4건, 전부 **같은 29마이크로초 안** (07:34:21.060545~.060574) |
| 주문당 명목 상한 | 200,000 USD (`40310000`) |
| 주문당 명목 하한 | 10 USD (`40310000`) |
| 세션 죽인 뒤 | 미체결 주문 2건·계좌 상태 **그대로**, 새 프로세스에서 즉시 조회됨 |
| 최종 상태 | 포지션 0 · 미체결 0 · 현금 98,912.43 (시작 100,000) |

## 안 한 것 / 미확인

- 옵션 주문, 대차(locates), 워치리스트, 법인행위 툴 — 호출 안 함
- 장중(09:30–16:00 ET) 주식 체결 — 실행 시각이 장 마감 중이라 **미확인**
- 실계좌 전환 — **하지 않음.** `ALPACA_PAPER_TRADE=false` 는 시도조차 하지 않았다
- 알파카 유료 시장 데이터(SIP, $99/월) — 구매하지 않음. 무료 IEX 티어만

## 화면 캡처 (2026-09-22 KST 02:26~02:47 추가)

본문(09-21)과 **다른 시각에 같은 절차를 다시 돌려** 찍었다. 숫자는 손대지 않았고, 본문과 갈리는 칸은 글의 캡션에 적었다.

| 파일 | 무엇 | 절 |
|---|---|---|
| `shots/01-install-mcp-add.png` | `--version 2.3.2` → `claude mcp add` → `claude mcp list \| grep alpaca` = **✔ Connected** | 2 |
| `shots/02-mcp-connect.png` | `initialize`(Alpaca MCP Server 3.4.7) · `tools/list` **72** · `get_clock`(**is_open true** — 본문과 반대) · `get_account_info` | 3 |
| `shots/03-alpaca-dashboard.png` | 알파카 페이퍼 웹 대시보드 첫 화면 (계좌번호 마스킹) | 3 |
| `shots/04-mcp-order-roundtrip.png` | **대표 그림** — 0.0005 BTC 매수 → `filled` **1.7ms** → 포지션 → `close_position` → `[]` | 4 |
| `shots/05-dashboard-orders.png` | 같은 주문이 대시보드 `Recent Orders` 에 `source=access_key` 로 (API 키 마스킹) | 4 |
| `shots/06-weltiq-stop-required.png` | weltiq `live_orders: false` · 중지 조건 없이 슬롯 생성 시 **HTTP 422** · 실행 중 슬롯 조회만 | 5 |

- 캡처용 스크립트: `shots/a01_demo.py` (알파카 MCP), `shots/weltiq_shot.py` (weltiq 조회). 크리덴셜 값은 출력하지 않는다.
- 캡처 중 낸 알파카 주문은 전부 **페이퍼**. 시작 전 `api.alpaca.markets` **401** 재확인. 포지션은 매번 닫았다.
- weltiq 쪽은 **조회와 거절되는 POST 하나뿐** — 슬롯을 만들지도, 실행 중인 슬롯을 건드리지도 않았다.

## 본문 정정 (2026-09-22)

캡처를 붙이며 5-2 표의 숫자 두 칸이 틀린 것을 발견해 고쳤다.

| | 종전 | 고침 | 근거 |
|---|---|---|---|
| 알파카 자산 | 미국 주식 약 11,000 · 크립토 56페어 | **거래가능 미국 주식·ETF 13,479 · 크립토 73페어** | `/v2/assets?status=active` 직접 카운트 (2026-09-22) |
| weltiq MCP 툴 수 | 49개 (실행 35 + 분석 14) | **56개 (실행 42 + 분석 14)** | `weltiq/api/mcp_server.py` 의 `@trading.tool` 42 · `@analyst.tool` 14 |

> 참고: `docs/research/COMPETITOR_PAPER_TRADING_2026-09-21.md` 114행도 같은 49 를 쓰고 있어 **아직 옛 숫자다.** 그 문서는 이번 작업 범위 밖이라 고치지 않았다.

---

## 독자판 재편 시 본문에서 내린 것 (2026-09-24)

독자판(`docs/tutorials/a/01-alpaca-mcp-server.md`)을 ≤3,000어절로 줄이면서 본문에서 뺀 실측·기록을 여기에 옮겨 적는다. **지운 것이 아니라 옮긴 것이다.**

### 안 돌린 것 — 본문 표에서 내림

| | 결과 |
|---|---|
| 글로벌 종목 하나 보기 | **됨.** `get_crypto_bars` 로 BTC/USD 일봉 정상 수신. 이 편의 초점이 아니라 본문 미수록 |
| 한국 종목 하나 보기 | **이 도구로는 안 됨.** 알파카에 한국 주식 없음. 자기 문서가 "international equities are on our roadmap" |
| 내 실행 기록 복기 | 부분적으로 함 — `31-activities.txt` (`FILL` 반출) |
| 여러 종목 훑어 후보 좁히기 | `get_market_movers`·`get_most_active_stocks` 툴은 있으나 **호출 안 함. 미확인** |
| 판단 → 주문 고리 한 바퀴 | 이 도구 단독으로는 판단하는 쪽이 없음. 판단 도구와 짝지어야 성립 |
| 수수료 바꿔 다시 재기 | **이 도구로는 안 됨.** 페이퍼에서 주식 수수료를 아예 안 매기므로 바꿔 볼 요율이 없음 |
| 둘·셋 나란히 돌려 비교 | 별도 트랙 |

### `ALPACA_TOOLSETS` 유효 이름 11개

`account, trading, watchlists, assets, stock-data, crypto-data, options-data, corporate-actions, news, fixed-income-data, locates`

없는 이름을 적으면 **오류 없이** 툴 5개짜리 서버가 된다 (본문 「막히는 자리」 표에서 링크로 넘긴 항목).

### MCP 를 거치지 않는 같은 조회 (본문 접은 블록에서 내림)

```bash
export ALPACA_API_KEY=... ALPACA_SECRET_KEY=... ALPACA_PAPER_TRADE=true
curl -s -H "APCA-API-KEY-ID: $ALPACA_API_KEY" -H "APCA-API-SECRET-KEY: $ALPACA_SECRET_KEY" \
  https://paper-api.alpaca.markets/v2/clock
curl -s -H "APCA-API-KEY-ID: $ALPACA_API_KEY" -H "APCA-API-SECRET-KEY: $ALPACA_SECRET_KEY" \
  https://paper-api.alpaca.markets/v2/account
```

이 글의 실행은 클라이언트 설정 대신 **MCP 프로토콜로 직접 붙는 60줄짜리 클라이언트**로 했다 — stdio 로 `initialize` → `tools/list` → `tools/call` 을 주고받으므로 대화창에서 쓰는 것과 오가는 내용은 같다.

### 종전 5-2 나란히 표에서 내린 weltiq 쪽 칸

독자판 5절은 승패 표가 아니라 **용도별 선택표**로 바꿨다. 그 과정에서 표에만 있던 weltiq 쪽 수치를 여기 남긴다.

| 칸 | 값 (2026-09-22 관측) |
|---|---|
| MCP 도구 수 | **56개** (실행 42 + 분석 14), 수기 정의 |
| 주문 왕복 실적 | 2026-09-17 페이퍼 런 **162체결** 기록 있음. **이 편 작업에서는 안 돌렸음** |
| 끊고 붙기 | 재시작 시 저널에서 포지션 재구성, 대사가 끝나기 전 신규 주문 금지 |
| 체결 모델 | 호가 20레벨 소진 + 대기열 + 잠김/역전 호가 거절 |
| 수수료 | 실제 수수료표 **17종** (한국 증권사 5곳 포함) |
| 한국 주식 | `krx` 열려 있음 — 봉 자료는 채우는 중 |
| 에이전트 자가 확대 | 한도 확대 툴이 **존재하지 않음** |
| 인젝션 방어 | **없음** (알파카에는 있음) |

### 캡처판과 본문의 수수료 차이 — 미확인

09-21 본문 판은 0.0005 BTC 매수에 **25bp**(포지션 0.00049875), 09-22 캡처 판은 **22bp**(포지션 0.0004989). **왜 갈렸는지 확인하지 않았다. 미확인.**

### 본문 정정 (2026-09-24) — "공개 배포 없음"

종전 판 §5-2 표가 weltiq 칸을 **"공개 배포 없음 · 공개 등재 없음"** 한 칸에 몰아 적었다. 셋을 갈라야 맞다.

| | 사실 | 근거 |
|---|---|---|
| 패키지 배포 | **없음** (맞음) | 내려받을 PyPI/npm 패키지가 없다 |
| 서비스 접속 | **공개돼 있음 — 종전 서술이 틀렸다** | 가입·키 발급 뒤 `claude mcp add weltiq --transport http https://weltiq.ai/mcp --header "Authorization: Bearer <키>"` 한 줄. 8편 §2.4 에 저쪽 호스티드 MCP 와 나란히 놓은 실호출이 있다 |
| 디렉터리 등재 | **없음** (맞음) | 8편 §5 표 — 저쪽은 MCP Registry·Glama·Smithery·mcp.so·PulseMCP·MCP Market 등재, weltiq 는 없음 |

독자판 5절 「필자가 고친 것 셋」의 ③ 이 이 내용이다.