TokenLab for Agents：機器可讀模型、定價、SDK 與 MCP

一個從記憶中挑選模型 ID 的程式設計代理（coding agent）最終會選到一個已不存在的模型，而且通常是在收到 404 錯誤或看到驚人的帳單後才發現。TokenLab MCP 為代理提供了一個即時目錄，讓它在編寫任何整合程式碼之前，能先驗證 ID、接受的請求格式以及價格。我們最初將此伺服器描述為嚴格的唯讀模式。但根據 2026-10-03 觀察到的文件顯示並非如此，因此本版本修正了該描述並新增了一個工作流程。

重點摘要

• TokenLab MCP 伺服器有三種設定檔：catalog（無需 API key）、core 與 full。只有 catalog 是無需金鑰的。
• 若有金鑰，它還能發送模型請求、建立媒體、處理檔案以及檢查非同步任務。它並非唯讀。
• 請根據 tokenlab.accepted_request_formats、tokenlab.pricing、tokenlab.lifecycle 與 tokenlab.deliveryAvailability 進行路由。請勿將推薦順序寫死（hard-code）。
• Gemini Files、可續傳上傳與 cachedContents 不包含在任何 MCP 設定檔中。
• 切勿將 API key 貼入提示詞或工具參數中。

TokenLab MCP 伺服器為程式設計代理提供了什麼

根據 MCP 伺服器文件（觀察於 2026-10-03），TokenLab MCP Server 讓客戶端可以瀏覽當前模型與價格、發送模型請求、建立媒體、處理檔案以及檢查非同步任務。文件列出了以下功能：

• 列出模型並讀取單一模型的功能（list_models, get_model）
• 讀取當前價格或比較多個模型
• 發送 Chat Completions、Responses、Anthropic Messages 或 Gemini 請求
• 使用 evaluate_decisions 評估型別化決策
• 建立或編輯圖像；建立影片、音樂、3D、語音、轉錄或翻譯
• 透過 OpenAI 相容的 /v1/files API 上傳與檢索檔案
• 建立嵌入（embeddings）或對文件進行重排序（rerank）
• 檢查並取消支援的非同步任務（使用 get_task_status 進行輪詢）

此版本的文件未列出定價或 API 概覽的工具名稱。我們之前的草稿曾命名為 get_model_pricing 與 get_api_overview。在依賴這兩個名稱之前，請先檢查您所連接客戶端的工具列表。

工具的可用性取決於設定檔：

設定檔	API key	包含內容
catalog	不需要	模型列表、模型詳細資訊、價格、比較、API 概覽
core	付費呼叫需要	常見的聊天、決策、媒體、音訊、檔案、任務、嵌入、重排序與翻譯工具
full	付費呼叫需要	core 加上額外的開發者 API

如果您只需要更好的模型選擇，請從 catalog 開始。當客戶端需要建立內容或呼叫模型時，請使用 core。

在您的客戶端安裝 TokenLab MCP 伺服器

該套件需要 Node.js 18.17 或更新版本以及 npx。它透過 stdio 在本地執行，因此無需全域安裝。請先備份您目前的設定，並僅新增 TokenLab 項目。這些指令來自 2026-10-03 觀察到的文件。

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 使用 .vscode/mcp.json，其中包含 servers 鍵與 "type": "stdio"。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。如果真實金鑰不慎進入共用檔案、日誌或 Shell 歷史記錄中，請立即撤銷並建立新金鑰。

代理工作流程：探索、檢查、呼叫

這是我們使用的工作流程。假設代理被要求在 Node.js 應用程式中新增圖像生成功能。以下所有數值均來自 2026-10-03 觀察到的文件與即時模型頁面。

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-03）。它回報：

• 接受的請求格式：gemini_generate_content，對應至 /v1beta/models/{model}:generateContent
• 功能：image-edit, image-to-image, text-to-image
• 價格：每次請求（per_request）0.067 USD，價格範圍為 0.067 至 0.12（定價更新於 2026-10-02T16:53:30.068Z）

如果代理假設使用 Chat Completions，就會寫出錯誤的程式碼。比較 gpt-image-2（即時模型 API）。它未列出任何接受的請求格式，且以 Token 計價，每 100 萬個 Token 輸入為 3.5 USD，輸出為 21 USD。價格形式因模型而異，因此代理必須針對每個模型進行讀取。

3. 進行呼叫。 對於聊天模型，格式檢查決定了端點。gpt-5.6-terra 接受 openai_chat_completions 與 openai_responses（即時模型 API，觀察於 2026-10-03），因此標準 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 輸入 Token 以內，每 100 萬個輸入 Token 收費 0.6 USD。一個 10,000 Token 的提示詞成本約為 10,000 / 1,000,000 × 0.6 = 0.006 USD（估算值，不含輸出）。超過 272K 輸入 Token 後，整個請求將進入較高的層級，輸入為 1.2 USD，輸出為 5.4 USD。

代理應信任哪些模型 API 欄位進行路由

請從 GET /v1/models/{model} 讀取這些欄位（取得模型，觀察於 2026-10-03）：

欄位	對路由的意義
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 萬個 Token 從 2.04 到 6.545 USD 不等（即時模型 API，觀察於 2026-10-03）。

引導恢復的錯誤欄位

在 OpenAI 相容的 Chat Completions 與 Responses 錯誤中，錯誤指南（觀察於 2026-10-03）列出了選用的 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 回答是一個機率，而非布林值。請針對您自己的標記案例進行驗證。

catalog 設定檔完全無法進行付費呼叫。圖像工具根據模型不同，會回傳結果或任務。影片、音樂與 3D 總是回傳任務。

您仍需使用純 HTTP 介面的情況

在我們的管線中，我們保留了 HTTP 探索端點與 MCP 並存，以服務非 MCP 代理。https://api.tokenlab.sh/llms.txt 是一個精簡的概覽，包含首次請求、常見端點與錯誤指南。2026-10-03 觀察到的文件未涵蓋 llms-full.txt 檔案或我們早期草稿中的 model-data 快照檔案。在依賴這些 URL 之前，請自行驗證。關於即時狀態與成本，請參閱公開的 模型目錄。

常見問題 (FAQ)

使用 TokenLab MCP 伺服器需要 API key 嗎？

不需要，瀏覽時不需要。catalog 設定檔無需金鑰即可列出模型、詳細資訊、價格與比較。付費模型或媒體請求需要在伺服器環境中使用 TOKENLAB_API_KEY，並搭配 core 或 full 設定檔。

我應該從哪個 MCP 設定檔開始？

如果您只需要更好的模型選擇，請從 catalog 開始。當客戶端需要呼叫模型或建立媒體時，請改用 core。僅在代理確實需要額外的開發者 API 時才使用 full。

代理在選擇模型時應信任哪些模型欄位？

信任 accepted_request_formats（用於端點）、pricing 及其單位（用於成本）、Token 限制、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 設定檔新增至您的客戶端。