TokenLab MCP Server

TokenLab MCP サーバー

TokenLab の公開モデルの検索、料金、ネイティブ LLM エンドポイント、型付き判断、マルチモーダル生成、非同期タスク、ファイル、埋め込み、再ランキング、翻訳、リソース、プロンプト、および幅広い開発者向け API に対応した、OpenAPI 生成の Model Context Protocol サーバーです。

TokenLab API を呼び出す前に、モデルを選択したり、対応するリクエスト形式を確認したり、料金を比較したりする必要があるエージェント向けに、公開カタログツールを提供します。認証情報が必要なツールでは、テキスト推論、画像生成と編集、動画、音楽、3D、非同期タスクのポーリング、埋め込み、再ランキング、型付き判断、テキスト翻訳に対応します。

生成されたツールプロファイル

チェックイン済みの generated/tools.json マニフェストは、TokenLab の公開 OpenAPI ドキュメントと、contract/mcp-overlay.json にある MCP 専用の小規模なオーバーレイから生成されます。バージョン 0.6.38 では 87 個のエンドポイントツールが生成されます。さらに、MCP 専用の複合ディスカバリーツールが 2 個あり、完全なプロファイルでは tools/list から 89 個のツールが返されます。

プロファイル	エンドポイントツール	登録済みツールの合計	モデル向けスキーマ	対応範囲
catalog	4	6	完全	公開モデルのディスカバリーと料金のみ。API キーは不要です
core（デフォルト）	30	32	ポータブル	カタログと料金、Chat Completions、Responses、Anthropic Messages、Gemini generateContent、System One の型付き判定、画像、動画、音楽、3D、音声と文字起こし、非同期タスク、ファイル、埋め込み、リランキング、翻訳
full	87	89	ポータブル	チェックイン済み OpenAPI スナップショットにある、許可リスト登録済みの開発者向け API 操作すべて。core に加え、レスポンスのライフサイクル、バッチ、ワールド、ネイティブなモデルディスカバリーを含みます

登録済みツールの合計数は、tools/list が返すツール数です。すべてのプロファイルに compare_models と get_api_overview が含まれ、ツール数の合計は 6、32、89 です。stdio の MCP ツール呼び出しでは最終結果が 1 つだけ返されるため、リアルタイム操作とストリーミング専用操作は除外されます。stream を受け付ける API 操作では、プロバイダーアダプターにブール値の const を公開せず、内部で false に固定します。また、Gemini のクエリ文字列の API キーは意図的にツール引数から隠されています。create_gemini_content では、Gemini の camelCase フィールド（systemInstruction、generationConfig、safetySettings、toolConfig、cachedContent）を公開し、API が別名として受け付ける snake_case の proto 表記は隠します。

ポータブルな投影では、最上位の引数をすべて保持しつつ、モデル向けの深くネストしたスキーマを制限します。API リクエストを送信する前に、サーバーは完全な生成済み OpenAPI スキーマに照らして呼び出しを引き続き検証します。互換性の上限により、core はサイズ 60 KB 以下、深さ 8 以下、full は完全な tools/list レスポンスでサイズ 115 KB 以下、深さ 8 以下に保たれます。テストでは、観測された OpenCode/Gemini の障害で使用されていた Google AI SDK のバージョンを使って full プロファイルも実行し、その関数宣言を 90 KB 以内に保ちます。

最小限の公開専用ツールリストを使用するには TOKENLAB_MCP_TOOL_PROFILE=catalog を設定し、幅広い開発者向け API を使用するには TOKENLAB_MCP_TOOL_PROFILE=full を設定してください。完全なネスト型 JSON Schema が必要で、より大きく深いツールペイロードを許容できるクライアントに限り、TOKENLAB_MCP_SCHEMA_MODE=exact を設定してください。すべてのプロパティを required に列挙し、すべてのオブジェクトで additionalProperties: false を設定する必要があるプロバイダーでは、strict を使用してください。複雑な最上位の引数は JSON エンコードされた文字列として表現され、正規の検証前にデコードされます。正規のツール名、説明、入力 JSON Schema、HTTP バインディング、コンテンツタイプ、認証要件、タスクの動作は、generated/tools.json で確認できます。

より小規模な generated/public-contract.json は、TokenLab のウェブサイトやその他の公開利用者が使う、機械可読な投影です。エンドポイントスキーマをすべて複製することなく、パッケージの識別情報、プロファイル数、core のツールレイヤー、リソース、プロンプト、ソースハッシュを含みます。

ネイティブ MCP 機能

• JSON ツールのレスポンスには structuredContent が含まれ、旧バージョンのクライアント向けにシリアライズされたテキストも維持されます。
• HTTP エラーでは、構造化されたステータス、リクエスト ID、再試行タイミングとともに、公開されている修正のヒントを含む元のレスポンステキスト（最大 4,000 文字）が保持されます。公開されるのはリクエスト ID と再試行ヘッダーのみです。失敗した生成リクエストが自動的に再送信されることはありません。
• 生成されたツールには、人が読めるタイトル、標準の読み取り専用／破壊的／冪等／オープンワールドの注釈、および利用可能な場合はレスポンスのリクエスト ID が含まれます。
• ツールスキーマは JSON Schema として直接公開され、検証されます。ランタイムでは、生成されたツールスキーマを Zod 経由で往復変換しません。exact モードでは、生成された正規スキーマとバイト単位で同じ形状になります。
• ライブ API の概要、パッケージの OpenAPI スナップショット、簡潔な MCP 公開コントラクトを公開する 3 つのリソースがあります。
• choose_tokenlab_model および build_tokenlab_request プロンプトは、ライブのモデル情報を使用し、ネイティブなエンドポイントの形状を維持するようエージェントをガイドします。
• サーバーの指示では、課金対象または破壊的な操作をクライアントに確認するよう求め、外部モデル／API の出力を信頼できないコンテンツとして扱うよう伝えます。

実行

npm install
npm start

npm からインストールします：

npx -y @tokenlabai/mcp-server

エージェントを利用したインストーラーは、認証情報を安全に扱うセットアップと検証の手順として、llms-install.md に従うことができます。

Docker で実行します：

docker build -t tokenlab-mcp-server .
docker run --rm -i tokenlab-mcp-server

認証情報が必要な API ツールを使用する場合は、-e TOKENLAB_API_KEY を追加してください。公開カタログツールではキーは不要です。

Claude Desktop 形式の設定：

{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": {
        "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
      }
    }
  }
}

公開カタログと料金の操作に TokenLab API キーは必要ありません。認証情報が必要なツールで TokenLab API を呼び出す場合は、TOKENLAB_API_KEY を設定してください。生成されたツールは、OpenAI 互換エンドポイントとネイティブエンドポイントの OpenAPI リクエスト形式を維持し、共通のプロンプト形式に平坦化しません。

マルチパート操作では、ローカルのファイルパスを指定できます。小さな画像および音声のレスポンスはネイティブ MCP コンテンツとして返されます。それより大きいレスポンスやその他のバイナリレスポンスは TOKENLAB_ARTIFACT_DIR に書き込まれ、MIME タイプとバイト数を添えたパスとして返されます。

同期および非同期のメディア結果

動画、音楽、3D の生成ツールは、常に非同期タスクを返します。画像の生成および編集では、選択したモデルとリクエストに応じて、完了済みの結果または非同期タスクが返されます。

メディアツールは、TokenLab API の完全なレスポンスを response の下に保持し、正規化された delivery の概要を追加します：

{
  "delivery": {
    "mode": "async",
    "task_id": "ldtask_...",
    "status": "pending",
    "poll_url": "/v1/tasks/ldtask_...",
    "terminal": false,
    "next_tool": "get_task_status"
  },
  "response": {}
}

すべての画像リクエストが同期的だと仮定せず、delivery.mode を使用してください。非同期タスクの場合は、delivery.terminal が true になるまで、{ "id": delivery.task_id } を指定して get_task_status を呼び出してください。完了は status に基づいて判定され、任意の進捗フィールドには基づきません。

環境変数

• TOKENLAB_API_BASE：任意。デフォルトは https://api.tokenlab.sh です
• TOKENLAB_API_KEY：任意。テキスト推論、マルチモーダル生成、非同期タスク、埋め込み、リランク、判断、翻訳の各ツールで必要です
• TOKENLAB_MCP_TOOL_PROFILE：任意。catalog、core（デフォルト）、または full
• TOKENLAB_MCP_SCHEMA_MODE：任意。portable、exact、または strict。デフォルトは、選択したプロファイルでテスト済みのモードです
• TOKENLAB_REQUEST_TIMEOUT_MS：任意。リクエストのタイムアウト（ミリ秒）。デフォルトは 120000 です
• TOKENLAB_MCP_MAX_FILE_BYTES：任意。ファイルごとのローカルアップロードサイズの上限。デフォルトは 104857600（100 MiB）です
• TOKENLAB_MCP_INLINE_BYTES：任意。インラインで返すバイナリ／JSON レスポンスサイズの上限。デフォルトは 2097152（2 MiB）です
• TOKENLAB_ARTIFACT_DIR：任意。インラインで返さないレスポンス成果物の出力ディレクトリ。デフォルトは OS の一時ディレクトリ配下の tokenlab-mcp です

Chat Completions の画像入力には、data:image/png;base64,... のようなバイト単位で正確なデータ URL を使用してください。MCP 呼び出し元が、認識可能な PNG、JPEG、WebP、または GIF のペイロードを application/octet-stream としてラベル付けした場合、サーバーは転送前に汎用 MIME タイプを修正します。認識できない汎用バイナリペイロードは、明確な入力エラーとともにローカルで拒否されます。

コントラクトの同期

公開 OpenAPI ドキュメントが API コントラクトのソースです。オーバーレイには MCP 固有の選択肢のみが含まれます。プロファイルの公開、安定したツールエイリアス、シークレットの除外、非ストリーミングの制約、コンテンツタイプのバリエーション、非同期タスクのセマンティクス、ウェブサイトとドキュメントのゲートで使用されるコンパクトな公開用プロジェクションです。

npm run contract:source-check # compare the snapshot with the live canonical OpenAPI (read-only)
npm run contract:check        # check generated output against the checked-in snapshot (offline)
npm run contract:sync         # fetch OpenAPI and regenerate; refuses dirty outputs or a stale branch
npm test                      # compile profiles and test exact/portable/strict schemas, provider conversion, routing, tasks, files, and binary output

手動でコントラクトを同期する前に、必ず git pull --ff-only を実行してください。contract:check で確認できるのは内部整合性のみです。contract:source-check では正規ソースに対する最新性を確認できます。スケジュール実行される Sync TokenLab OpenAPI contract ワークフローは、書き込み処理一式を実行し、検証済みの OpenAPI スナップショットと生成されたマニフェストのみを main にコミットします。フェッチの失敗、ローカルブランチの古さ、生成物の変更、生成エラー、スキーマのコンパイルエラー、またはテストの失敗が発生した場合、追跡対象のコントラクトは変更されません。

MCP レジストリのメタデータ

このリポジトリには、公式 MCP レジストリ用の server.json が含まれています。

リリースのメタデータ：

• npm パッケージ：@tokenlabai/[email protected]
• MCP レジストリ名：io.github.hedging8563/tokenlab
• package.json.mcpName：io.github.hedging8563/tokenlab

新しいリリースを作成する場合：

1. package.json、package-lock.json、server.json の対応するバージョンを更新します。
2. v0.6.0 のような一致するタグをプッシュします。
3. 公開ワークフローが信頼された公開を通じてテストと npm への公開を行った後、GitHub Actions OIDC を通じて MCP レジストリのエントリーを公開します。

同じワークフローを main から手動で実行すると、現在の MCP レジストリのメタデータのみを再公開できます。npm または MCP レジストリのトークンは GitHub に保存されません。

セキュリティ

認証情報が必要なツールを使わない場合は、catalog プロファイルを使用してください。TOKENLAB_API_KEY はローカル MCP クライアントのシークレット環境に保管し、課金対象の呼び出しや破壊的な呼び出しには人間による確認を有効にして、永続的な承認を与える前にツールの注釈を確認してください。信頼できないホスト型 MCP サーバーに TokenLab API キーを送信しないでください。

各 API リクエストでは X-TokenLab-Client-Source: mcp-<tool name>（例：mcp-create_image）が送信されるため、TokenLab は使用されたツールを集計できます。tokenlab://api/overview リソースを読み取ると、mcp-resource-api_overview が送信されます。このヘッダーに含まれるのは小文字化されたツール名のみで、64 文字で切り詰められます。ツール引数は含まれません。

リンク

• ウェブサイト：https://tokenlab.sh/mcp
• ドキュメント：https://tokenlab.sh/docs
• OpenAPI：https://tokenlab.sh/docs/openapi.json
• モデルカタログ：https://api.tokenlab.sh/v1/models
• スキル：https://github.com/hedging8563/tokenlab-skills

Webhook の管理

full プロファイルを使用すると、list_webhooks、create_webhook、get_webhook、update_webhook、delete_webhook、rotate_webhook_secret、test_webhook、list_webhook_deliveries を使ってワークスペースの Webhook を設定できます。

TOKENLAB_MANAGEMENT_TOKEN=mt-... は TOKENLAB_API_KEY=sk-... とは別に設定してください。管理トークンはダッシュボード → API → 管理トークンで作成できます。このトークンはワークスペース内の管理操作のみを許可するもので、Webhook に限定されません。推論キーで代用することはできません。また、作成またはローテーション時に返される whsec_... は、受信側での署名検証専用です。すべての認証情報をツール引数やプロンプトに含めないでください。

Webhook 通知を使うと、タスクを継続的にポーリングする必要がありません。ポーリングにフォールバックする場合は、終端ステータス、401／403／404、または retryable: false で停止し、一時的な障害ではバックオフしてください。ペイロード、署名、重複排除、配信履歴についてはWebhook の完全ガイドをご覧ください。