TokenLab for Agents: 機械可読なモデル、価格設定、SDK、および MCP

メモリからモデルIDを選択するコーディングエージェントは、いずれ存在しないIDを選択してしまい、404エラーや予期せぬ請求が発生した後に初めてその事実に気づくことになります。TokenLab MCPは、エージェントにライブカタログを提供して最初に確認させることで、統合コードを書く前にID、受け入れ可能なリクエスト形式、および価格を検証できるようにします。当初、このサーバーは厳密に読み取り専用であると説明していましたが、2026年10月3日に確認されたドキュメントではそうではないことが示されています。そのため、本バージョンではその点を修正し、具体的なワークフローを追加しました。

重要なポイント

• TokenLab MCPサーバーには、catalog（APIキー不要）、core、fullの3つのプロファイルがあります。キーが不要なのは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を通じたファイルのアップロードおよび取得
• 埋め込み（embeddings）の作成またはドキュメントの再ランキング（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は.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に到達したことが確認できます。実際のキーが共有ファイル、ログ、またはシェル履歴に残ってしまった場合は、それを無効化して新しいキーを作成してください。

エージェントのフロー：発見、確認、呼び出し

私たちが使用しているフローは以下の通りです。エージェントが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
• 価格：1リクエストあたり0.067 USD、価格範囲は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	text-to-imageやimage-to-videoなどの操作
tokenlab.lifecycle	可用性、リリース日、廃止日、代替モデル
tokenlab.deliveryAvailability	設定されたverifiedおよびofficialサポート。フィールドがない場合は不明

2つの注意点があります。第一に、受け入れ可能な形式はエンドポイントを確認しますが、個々のツールやフィールドはモデルによって異なる場合があります。第二に、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 and cacheに従い、HTTP呼び出しが必要です。
• これはSkillではありません。TokenLab Skillはnpx skills addで指示をインストールし、MCPサーバーを起動しません。
• タイムアウト時にポーリングを行うことはありません。ステータスチェックがタイムアウトしても、2つ目のタスクを作成しないでください。
• それ自体で決定を信頼できるものにするわけではありません。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に依存する前に、自身で確認してください。ライブステータスとコストについては、公開されているModels catalogを参照してください。

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階層に供給がない可能性があります。retryableがfalseの場合、リクエストを繰り返さないでください。GET /v1/modelsで可用性を確認し、ユーザーの承認を得て別のモデルを選択してください。

MCPサーバーはGemini FilesやcachedContentsをサポートしていますか？

いいえ。ドキュメントによると、Gemini Files、レジューム可能なアップロード、およびcachedContentsは現在HTTP呼び出しが必要です。MCPファイルツールはOpenAI互換の/v1/files APIを使用します。

Console → API keysでキーを作成し、上記のコマンドを使用してクライアントにcatalogプロファイルを追加してください。