TokenLab for Agents: 기계 판독 가능한 모델, 가격 책정, SDK 및 MCP

메모리에서 모델 ID를 선택하는 코딩 에이전트는 결국 존재하지 않는 모델을 선택하게 되며, 404 오류나 예상치 못한 청구서를 받은 후에야 이를 알게 됩니다. TokenLab MCP는 에이전트에게 실시간 카탈로그를 제공하여, 통합 코드를 작성하기 전에 모델 ID, 허용된 요청 형식 및 가격을 먼저 검증할 수 있도록 합니다. 당초 이 서버를 엄격한 읽기 전용으로 설명했으나, 2026년 10월 3일 확인된 문서에 따르면 그렇지 않으므로, 이번 버전에서는 이를 수정하고 작업 흐름을 추가했습니다.

핵심 요약

• TokenLab MCP 서버는 catalog(API 키 불필요), core, full의 세 가지 프로필을 제공합니다. catalog만 키 없이 사용할 수 있습니다.
• 키를 사용하면 모델 요청 전송, 미디어 생성, 파일 처리 및 비동기 작업 확인이 가능합니다. 즉, 읽기 전용이 아닙니다.
• tokenlab.accepted_request_formats, tokenlab.pricing, tokenlab.lifecycle 및 tokenlab.deliveryAvailability를 기반으로 라우팅하십시오. 추천 순서를 하드코딩하지 마십시오.
• Gemini Files, 재개 가능한 업로드 및 cachedContents는 어떤 MCP 프로필에도 포함되어 있지 않습니다.
• 프롬프트나 도구 인수에 API 키를 절대 붙여넣지 마십시오.

TokenLab MCP 서버가 코딩 에이전트에 제공하는 기능

MCP 서버 문서(2026년 10월 3일 확인)에 따르면, TokenLab MCP Server를 통해 클라이언트는 현재 모델과 가격을 탐색하고, 모델 요청을 보내고, 미디어를 생성하고, 파일을 작업하며, 비동기 작업을 확인할 수 있습니다. 문서에 명시된 기능은 다음과 같습니다:

• 모델 목록 조회 및 특정 모델의 기능 읽기(list_models, get_model)
• 현재 가격 읽기 또는 여러 모델 비교
• Chat Completions, Responses, Anthropic Messages 또는 Gemini 요청 전송
• evaluate_decisions를 통한 유형화된 결정 평가
• 이미지 생성 또는 편집; 비디오, 음악, 3D, 음성, 전사 또는 번역 생성
• OpenAI 호환 /v1/files API를 통한 파일 업로드 및 검색
• 임베딩 생성 또는 문서 재순위 지정(rerank)
• 지원되는 비동기 작업 확인 및 취소(폴링을 위한 get_task_status)

문서의 이번 버전에는 가격 책정이나 API 개요에 대한 도구 이름이 나열되어 있지 않습니다. 이전 초안에서는 get_model_pricing과 get_api_overview라는 이름을 사용했습니다. 해당 이름을 사용하기 전에 연결된 클라이언트의 도구 목록을 확인하십시오.

도구 가용성은 프로필에 따라 다릅니다:

프로필	API 키	포함 사항
catalog	불필요	모델 목록, 모델 세부 정보, 가격, 비교, API 개요
core	유료 호출 시 필요	일반 채팅, 결정, 미디어, 오디오, 파일, 작업, 임베딩, 재순위 지정 및 번역 도구
full	유료 호출 시 필요	core 및 추가 개발자 API

더 나은 모델 선택만 원한다면 catalog로 시작하십시오. 클라이언트가 콘텐츠를 생성하거나 모델을 호출해야 할 때는 core를 사용하십시오.

클라이언트에 TokenLab MCP 서버 설치

이 패키지는 Node.js 18.17 이상과 npx가 필요합니다. 로컬에서 stdio를 통해 실행되므로 전역 설치가 필요 없습니다. 먼저 활성 구성을 백업하고 TokenLab 항목만 추가하십시오. 다음 명령은 2026년 10월 3일 확인된 문서 기준입니다.

Claude Code:

claude mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  --scope user \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Codex:

codex mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Cursor (~/.cursor/mcp.json 또는 .cursor/mcp.json):

{
  "mcpServers": {
    "tokenlab": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server@0.6.26"],
      "env": {
        "TOKENLAB_MCP_TOOL_PROFILE": "catalog"
      }
    }
  }
}

VS Code는 servers 키와 "type": "stdio"를 포함하는 .vscode/mcp.json을 사용합니다. Claude Desktop은 claude_desktop_config.json에서 Cursor와 동일한 형식을 사용합니다. 문서 페이지에서 둘 다 복사하십시오.

유료 도구를 활성화하려면 Console → API keys에서 키를 생성하고 서버 환경에 두 변수를 설정하십시오:

{
  "env": {
    "TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>",
    "TOKENLAB_MCP_TOOL_PROFILE": "core"
  }
}

그런 다음 클라이언트를 다시 시작하고 claude mcp list 또는 codex mcp list를 실행하십시오. 에이전트에게 list_models를 호출하도록 요청하십시오. 비어 있지 않은 목록이 반환되면 패키지가 시작되어 TokenLab에 도달했음을 의미합니다. 실제 키가 공유 파일, 로그 또는 셸 기록에 남았다면 즉시 취소하고 새 키를 생성하십시오.

에이전트 워크플로우: 발견, 확인, 호출

다음은 우리가 사용하는 워크플로우입니다. 에이전트가 Node.js 앱에 이미지 생성 기능을 추가하라는 요청을 받았다고 가정해 봅시다. 아래 모든 값은 2026년 10월 3일 확인된 문서 및 실시간 모델 페이지에서 가져왔습니다.

1. 발견. MCP 도구 또는 일반 HTTP를 사용하여 현재 후보 목록을 요청하십시오:

{ "tool": "list_models", "arguments": { "recommended_for": "image" } }

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

유효한 recommended_for 값은 image, video, music, 3d, tts, stt, embedding, rerank 및 translation입니다. 에이전트가 nano-banana-pro를 선택했다고 가정합니다.

2. 형식 및 가격 확인. get_model을 호출하거나 GET /v1/models/nano-banana-pro(실시간 모델 API, 2026년 10월 3일 확인)를 호출하십시오. 결과는 다음과 같습니다:

• 허용된 요청 형식: gemini_generate_content (/v1beta/models/{model}:generateContent로 매핑됨)
• 기능: image-edit, image-to-image, text-to-image
• 가격: 0.067 USD의 per_request, 가격 범위는 0.067~0.12 USD (2026년 10월 2일 16:53:30.068Z에 업데이트됨)

Chat Completions를 가정했던 에이전트는 잘못된 코드를 작성했을 것입니다. gpt-image-2(실시간 모델 API)를 비교해 보십시오. 허용된 요청 형식이 나열되어 있지 않으며 토큰당 가격은 100만 토큰당 입력 3.5 USD, 출력 21 USD입니다. 가격 형태는 모델마다 다르므로 에이전트는 모델별로 읽어야 합니다.

3. 호출. 채팅 모델의 경우 형식 확인을 통해 엔드포인트가 결정됩니다. gpt-5.6-terra는 openai_chat_completions 및 openai_responses를 허용하므로(실시간 모델 API, 2026년 10월 3일 확인), 표준 SDK가 작동합니다:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Reply only with OK."}],
)
print(response.choices[0].message.content)

선택한 모델 ID를 명시적으로 전송하십시오. 문서에 따르면 TokenLab은 이를 자동으로 대체하지 않습니다. 가격이나 모델 선택이 이미 확인되지 않았다면 유료 호출 전에 클라이언트가 승인을 요청해야 합니다.

비용 추정을 위해 gpt-5.6-terra는 272K 입력 토큰까지 100만 입력 토큰당 0.6 USD를 청구합니다. 10,000 토큰 프롬프트의 경우 입력 비용은 약 10,000 / 1,000,000 × 0.6 = 0.006 USD입니다(출력 제외 추정치). 272K 입력 토큰을 초과하면 전체 요청은 입력 1.2 USD, 출력 5.4 USD의 더 높은 계층으로 이동합니다.

에이전트가 라우팅을 위해 신뢰해야 할 모델 API 필드

GET /v1/models/{model}(Get a Model, 2026년 10월 3일 확인)에서 다음 필드를 읽으십시오:

필드	라우팅 의미
tokenlab.accepted_request_formats	사용할 엔드포인트 제품군: openai_chat_completions는 /v1/chat/completions, openai_responses는 /v1/responses, anthropic_messages는 /v1/messages
tokenlab.pricing / pricing_unit	현재 공개 가격 및 per_token 또는 per_image와 같은 청구 단위
tokenlab.max_input_tokens, max_output_tokens	컨텍스트 및 출력 제한. gpt-5.6-terra의 경우: 1,050,000 및 128,000
tokenlab.supported_operations	텍스트-이미지 또는 이미지-비디오와 같은 작업
tokenlab.lifecycle	가용성, 출시일, 지원 종료일, 대체 모델
tokenlab.deliveryAvailability	구성된 verified 및 official 지원. 필드가 없으면 알 수 없음

두 가지 주의 사항이 있습니다. 첫째, 허용된 형식은 엔드포인트를 확인하지만 개별 도구와 필드는 모델마다 다를 수 있습니다. 둘째, deliveryAvailability는 구성된 지원일 뿐 실시간 보장이 아닙니다. recommended_for 결과는 후보 목록으로 취급하십시오. 문서에 따르면 순서를 고정하지 말아야 합니다.

가격만 확인하려면 GET /v1/models/{model}/pricing 엔드포인트를 사용하십시오. 복잡한 항목은 계층을 가질 수 있습니다. 예를 들어 seedance-2.0은 해상도 및 비디오 입력에 따라 100만 토큰당 2.04~6.545 USD의 출력 가격을 가집니다(실시간 모델 API, 2026년 10월 3일 확인).

복구를 안내하는 오류 필드

OpenAI 호환 Chat Completions 및 Responses 오류 발생 시, 오류 가이드(2026년 10월 3일 확인)에는 선택적 did_you_mean, suggestions, hint, retryable 및 retry_after가 나열되어 있습니다. HTTP 상태와 code를 먼저 처리하십시오. 400 model_not_found에는 did_you_mean이 포함될 수 있습니다. 모델을 자동으로 교체하지 말고 사용자에게 이를 보여주십시오. 503 all_channels_failed는 retryable: false일 수 있으며, 반복 시도는 도움이 되지 않습니다. Anthropic Messages와 Gemini는 고유한 오류 형식을 유지합니다.

MCP 서버가 수행하지 않는 작업

문서에 명시된 제한 사항은 다음과 같습니다:

• 클라이언트의 기본 모델 제공업체를 변경하지 않습니다. 해당 클라이언트의 자체 설정 가이드를 사용하십시오.
• Gemini Files, 재개 가능한 업로드 또는 cachedContents를 다루지 않습니다. Gemini Files 및 캐시에 따라 HTTP 호출이 필요합니다.
• Skill이 아닙니다. TokenLab Skill은 npx skills add로 지침을 설치하며 MCP 서버를 시작하지 않습니다.
• 시간 초과 시 폴링을 수행하지 않습니다. 상태 확인이 시간 초과되면 두 번째 작업을 생성하지 마십시오.
• 결정을 스스로 신뢰할 수 있게 만들지 않습니다. evaluate_decisions의 Noul 답변은 확률일 뿐 Boolean이 아닙니다. 자체 레이블이 지정된 사례와 비교하여 검증하십시오.

catalog 프로필은 유료 호출을 전혀 수행할 수 없습니다. 이미지 도구는 모델에 따라 결과 또는 작업을 반환합니다. 비디오, 음악 및 3D는 항상 작업을 반환합니다.

일반 HTTP 인터페이스가 여전히 필요한 경우

우리는 파이프라인에서 비 MCP 에이전트를 위해 MCP와 함께 HTTP 발견 엔드포인트를 유지했습니다. https://api.tokenlab.sh/llms.txt는 첫 번째 요청, 일반적인 엔드포인트 및 오류 지침이 포함된 간략한 개요입니다. 2026년 10월 3일 확인된 문서에는 llms-full.txt 파일이나 이전 초안의 model-data 스냅샷 파일이 포함되어 있지 않습니다. 의존하기 전에 해당 URL을 직접 확인하십시오. 실시간 상태 및 비용은 공개 모델 카탈로그를 참조하십시오.

FAQ

TokenLab MCP 서버를 사용하려면 API 키가 필요한가요?

아니요, 탐색에는 필요하지 않습니다. catalog 프로필은 키 없이 모델, 세부 정보, 가격 및 비교를 나열합니다. 유료 모델 또는 미디어 요청에는 core 또는 full 프로필과 함께 서버 환경에 TOKENLAB_API_KEY가 필요합니다.

어떤 MCP 프로필로 시작해야 하나요?

더 나은 모델 선택만 원한다면 catalog로 시작하십시오. 클라이언트가 모델을 호출하거나 미디어를 생성해야 할 때 core로 이동하십시오. 에이전트가 추가 개발자 API가 반드시 필요한 경우에만 full을 사용하십시오.

모델을 선택할 때 에이전트가 신뢰해야 할 모델 필드는 무엇인가요?

엔드포인트는 accepted_request_formats, 비용은 pricing(단위 포함), 토큰 제한, supported_operations 및 lifecycle을 신뢰하십시오. deliveryAvailability는 실시간 가용성이 아닌 구성된 지원으로 취급하십시오.

에이전트가 503 all_channels_failed 오류를 받는 이유는 무엇인가요?

선택한 배송 계층(Delivery tier)에 공급이 없을 수 있습니다. retryable이 false인 경우 요청을 반복하지 마십시오. GET /v1/models로 가용성을 확인하고 사용자의 승인을 받아 다른 모델을 선택하십시오.

MCP 서버가 Gemini Files나 cachedContents를 지원하나요?

아니요. 문서는 Gemini Files, 재개 가능한 업로드 및 cachedContents가 현재 HTTP 호출을 필요로 한다고 명시합니다. MCP 파일 도구는 OpenAI 호환 /v1/files API를 사용합니다.

Console → API keys에서 키를 생성한 다음, 위의 명령을 사용하여 클라이언트에 catalog 프로필을 추가하십시오.