MCP 서버

PolyTest MCP(Model Context Protocol) 서버를 사용하면 AI 도구가 PolyTest 마켓 데이터를 직접 읽을 수 있습니다. Claude Code, Cursor, VS Code, Codex, Gemini CLI, Claude Desktop을 비롯한 MCP 클라이언트에서 동작합니다. 모든 도구는 읽기 전용입니다.

연결

호스팅 서버 주소는 https://mcp.polytest.io/mcp이며 Streamable HTTP를 사용합니다. Claude Code 명령은 키 없이 서버를 추가하고, 그다음 PolyTest 계정으로 로그인합니다. 나머지 예시는 POLYTEST_KEY 환경 변수에서 읽은 API 키를 보냅니다. 두 방법은 인증에서 설명합니다.

claude mcp add --transport http polytest https://mcp.polytest.io/mcp

Claude Code와 Gemini CLI 명령은 터미널에서 실행하세요. Cursor 블록은 ~/.cursor/mcp.json에, VS Code 블록은 .mcp.json에, Codex 블록은 ~/.codex/config.toml에 넣습니다.

인증

클라이언트가 OAuth를 지원하면 PolyTest 계정으로 로그인하세요. Claude Code에서는 /mcp를 실행하고 polytest를 선택한 뒤 Authenticate를 고르세요. 데스크톱 앱 안의 Claude Code처럼 /mcp를 쓸 수 없다면 대신 서버를 추가한 폴더에서 터미널로 claude mcp login polytest를 실행하세요. 다른 클라이언트는 연결할 때나 처음 도구를 호출할 때 로그인을 요청합니다.

브라우저가 qpzofvjvtdvdnvgpxplg.supabase.co의 로그인 링크를 엽니다. PolyTest가 로그인에 쓰는 Supabase Auth의 주소입니다. 이어서 www.polytest.io로 넘어가면 거기서 연결을 승인합니다. 나중에 설정의 연결된 앱에서 제거할 수 있습니다.

API 키를 Authorization: Bearer <key> 헤더로 보낼 수도 있습니다. X-API-Key도 됩니다. API 키 페이지에서 키를 만들고, 키를 URL에 넣지 마세요.

Claude Code에서는 키를 --header 옵션에 넣습니다.

Claude Code
claude mcp add --transport http polytest https://mcp.polytest.io/mcp --header "Authorization: Bearer $POLYTEST_KEY"

로컬에서 실행

npx -y @polytest/mcp는 npm 패키지 @polytest/mcp로 서버를 내 컴퓨터에서 실행합니다. Node 20 이상이 필요하며, 키는 POLYTEST_KEY 환경 변수에서 읽습니다.

claude mcp add --transport stdio --env POLYTEST_KEY=$POLYTEST_KEY polytest -- npx -y @polytest/mcp

Claude Desktop 블록은 claude_desktop_config.json에 넣습니다. pt_live_...를 내 키로 바꾸세요.

도구

서버에는 도구가 다섯 개 있습니다. 마지막 열은 한 번 호출할 때 드는 API 요청 수입니다.

도구반환값API 요청 수
polytest_list_markets한 코인의 특정 market_type 마켓을 최신순으로 반환합니다. 각 행에는 기간, status, 시작과 종료 시점의 현물 가격, 승자, 거래량이 있습니다.1
polytest_get_marketmarket_id 또는 slug로 지정한 마켓 하나. 토큰 ID와 결과 확정 필드를 포함합니다.1
polytest_get_snapshots한 마켓의 스냅샷을 오래된 순으로 반환하며, 각 행에 time, spot_price, price_up, price_down이 있습니다. include_orderbook을 쓰면 각 행에 양쪽 오더북도 포함됩니다.1
polytest_get_price_series한 마켓 전체에서 일정한 간격으로 뽑은 가격 포인트. 오래된 순입니다.1회에 샘플마다 1회 추가, 기본값이면 21회
polytest_get_limits플랜의 한도: 등급, 요청 한도, 동시 요청 상한, 데이터 접근 범위, 키 개수 상한, 체험 예산.1

price_up은 Up 오더북의 최저 매도 호가, 즉 그 순간 Up을 살 때 내야 하는 가격입니다. price_down은 Down에 대한 같은 값입니다. 둘 다 0부터 1 사이이며, 그쪽에 매도 주문이 하나도 없으면 null입니다. 중간가도 마지막 체결가도 아닙니다. 둘 다 매도 호가이므로 Up과 Down을 더하면 보통 1보다 조금 큽니다.

보통은 polytest_list_markets로 마켓을 찾고, polytest_get_price_series로 그 마켓의 흐름을 본 다음, polytest_get_snapshots로 틱 단위 데이터나 특정 시점의 오더북을 읽습니다.

제공 범위와 최신성

PolyTest에는 btc, eth, sol의 5m, 15m, 1hr 마켓이 있고, 4hr와 24hr 마켓은 btc만 있습니다.

PolyTest는 새 마켓을 일괄로 불러오기 때문에 가장 최근 마켓은 실시간보다 몇 시간 또는 며칠 늦을 수 있습니다. 지연 정도는 코인과 마켓 유형에 따라 다릅니다.

각 마켓 행에는 status 필드가 있으며 값은 다음 중 하나입니다.

  • upcoming: 기간이 아직 시작되지 않았습니다.
  • open: 기간이 아직 진행 중입니다.
  • resolved: 승자가 정해졌습니다.
  • ended_no_result: 기간이 끝났으며 PolyTest에는 이 기간의 결과가 없습니다.

end_time 없이 가장 최근 마켓 목록을 조회할 때 그중 가장 최근 마켓이 현재 시각보다 한참 전에 시작됐다면 polytest_list_markets가 그 사실을 알리는 메모를 덧붙입니다. 아직 진행 중인 마켓이면 polytest_get_price_series는 미래 구간을 샘플링하지 않고 현재 시각에서 멈춥니다. 시리즈의 마지막 버킷들이 비어 있으면 데이터가 어디서 끝나는지 알려 줍니다. 아직 시작하지 않은 마켓처럼 현재 시각 이후에 시작하는 범위를 요청하면 오류가 반환됩니다.

한도와 비용

도구 호출은 모두 일반 API 요청을 보내므로 REST 호출과 같은 플랜 한도에 포함됩니다.

  • 요청 한도는 키별로 적용되므로 MCP 서버 전용 키를 따로 만드세요.
  • 동시 요청 수는 계정에서 실행 중인 다른 작업과 함께 계산됩니다. 빈 슬롯이 없으면 서버가 잠깐 재시도합니다.
  • polytest_get_limits는 유료 계정을 포함한 모든 계정에 trial_budget을 반환합니다. 무료 체험 3일 동안 쓸 수 있는 요청, 레코드, 바이트의 총량이며 체험 기간에만 적용됩니다. 도구로는 남은 양을 볼 수 없습니다. REST API는 남은 양을 응답 헤더로만 알려 주는데, MCP 클라이언트는 이 헤더를 보지 못합니다.
  • 결과는 AI 컨텍스트 윈도우에 맞춘 크기입니다. 페이지가 작고 오더북은 선택한 깊이까지만 남깁니다. 대량 수집이나 백테스트에는 AI에게 TypeScript SDK나 REST API로 코드를 작성하게 하세요.

사용해 보기

서버를 연결했다면 평소 쓰는 말로 요청하면 됩니다. 예를 들면 다음과 같습니다.

  • PolyTest에서 가장 최근 BTC 5m 마켓 다섯 개를 나열하고, 가장 최신 마켓에서 Up 가격이 어떻게 움직였는지 보여 줘.

  • PolyTest에서 가장 최근에 결과가 확정된 BTC 15m 마켓을 찾아서 종료 30초 전의 양쪽 오더북을 보여 줘.

  • 내 PolyTest 플랜 한도를 확인하고, 샘플 40개짜리 가격 시리즈에 API 요청이 몇 번 드는지 알려 줘.

문제 해결

도구 오류가 API 키가 없거나 거부되었다고 알려 줍니다
오류 메시지에 사용 중인 설정에 맞는 해결 방법이 나옵니다. POLYTEST_KEY를 설정하거나, Authorization 헤더를 추가하거나, 다시 로그인하세요. 키는 API 키 페이지에 있습니다.
도구 오류에 내 플랜이 언급됩니다
플랜에 포함되지 않은 요청입니다. AI에게 polytest_get_limits를 호출해 플랜에 포함된 범위를 확인하게 하세요.
클라이언트가 서버에 인증이 필요하다고 표시합니다
클라이언트가 로그인을 안내하면 로그인하거나, 인증에 나온 Authorization 헤더를 추가하세요.
도구 오류가 요청 한도에 도달했다고 알려 줍니다
오류 메시지에 재시도 전에 얼마나 기다려야 하는지 나옵니다.