TokenLab for Agents：机器可读模型、定价、SDK 和 MCP

如果一个编码 Agent 从内存中选择模型 ID，最终必然会选到一个已不存在的模型，而且只有在遇到 404 错误或收到令人惊讶的账单后才会发现。TokenLab MCP 为 Agent 提供了一个实时目录以供先行检查，使其在编写任何集成代码之前，能够验证 ID、支持的请求格式以及价格。我们最初将该服务器描述为严格的只读模式。但 2026-10-03 观察到的文档显示并非如此，因此本版本对此进行了更正，并增加了一个工作流程。

关键要点

• TokenLab MCP 服务器有三种配置：catalog（无需 API key）、core 和 full。只有 catalog 是无需 key 的。
• 拥有 key 后，它还可以发送模型请求、创建媒体、处理文件以及检查异步任务。它并非只读。
• 请根据 tokenlab.accepted_request_formats、tokenlab.pricing、tokenlab.lifecycle 和 tokenlab.deliveryAvailability 进行路由。不要硬编码推荐顺序。
• Gemini Files、可恢复上传和 cachedContents 不包含在任何 MCP 配置中。
• 切勿将 API key 粘贴到提示词或工具参数中。

TokenLab MCP 服务器为编码 Agent 提供了什么

根据 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 使用带有 servers 键和 "type": "stdio" 的 .vscode/mcp.json。Claude Desktop 在 claude_desktop_config.json 中使用与 Cursor 相同的格式。请从文档页面复制两者。

要启用付费工具，请在 Console → API keys 中创建一个 key，并在服务器环境变量中设置以下两个变量：

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

然后重启客户端并运行 claude mcp list 或 codex mcp list。要求 Agent 调用 list_models。如果返回非空列表，则确认包已启动并连接到 TokenLab。如果真实的 key 进入了共享文件、日志或 shell 历史记录，请撤销它并创建一个新的。

一个 Agent 工作流程：发现、检查、调用

这是我们使用的工作流程。假设一个 Agent 被要求向 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。假设 Agent 选择了 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）

如果 Agent 假设使用 Chat Completions，就会写出错误的代码。比较 gpt-image-2（实时模型 API）。它没有列出支持的请求格式，并且按 token 定价，输入为 3.5 USD/1M tokens，输出为 21 USD/1M tokens。价格形式因模型而异，因此 Agent 必须针对每个模型进行读取。

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 以内的部分收取 0.6 USD/1M 输入 tokens。那么 10,000 个 token 的提示词输入成本约为 10,000 / 1,000,000 × 0.6 = 0.006 USD（估算值，不含输出）。超过 272K 输入 token 后，整个请求将进入更高层级，输入为 1.2 USD，输出为 5.4 USD。

Agent 在路由时应信任哪些模型 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	操作类型，如 text-to-image 或 image-to-video
tokenlab.lifecycle	可用性、发布日期、弃用日期、替代模型
tokenlab.deliveryAvailability	已配置的 verified 和 official 支持。字段缺失表示未知

有两点需要注意。首先，支持的格式确认了端点，但具体的工具和字段仍可能因模型而异。其次，deliveryAvailability 是已配置的支持，而非实时保证。请将 recommended_for 的结果视为候选列表，因为文档建议不要固定其顺序。

仅针对价格，GET /v1/models/{model}/pricing 是仅定价端点。复杂的条目可能包含分级定价。例如，seedance-2.0 的输出价格取决于分辨率和视频输入，从 2.04 到 6.545 USD/1M tokens 不等（实时模型 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 Agent 使用。https://api.tokenlab.sh/llms.txt 是一个简洁的概览，包含首次请求、常用端点和错误指南。2026-10-03 观察到的文档未涵盖 llms-full.txt 文件或我们早期草稿中的 model-data 快照文件。在依赖这些 URL 之前，请自行验证。有关实时状态和成本，请参阅公开的 Models 目录。

常见问题解答

我需要 API key 才能使用 TokenLab MCP 服务器吗？

不需要，浏览时不需要。catalog 配置无需 key 即可列出模型、详情、价格和比较。付费模型或媒体请求需要在服务器环境变量中提供 TOKENLAB_API_KEY，并使用 core 或 full 配置。

我应该从哪个 MCP 配置开始？

如果您只需要更好的模型选择，请从 catalog 开始。当客户端需要调用模型或创建媒体时，请转到 core。仅当 Agent 确实需要额外的开发者 API 时，才使用 full。

Agent 在选择模型时应信任哪些模型字段？

信任 accepted_request_formats（用于端点）、pricing 及其单位（用于成本）、token 限制、supported_operations 和 lifecycle。将 deliveryAvailability 视为已配置的支持，而非实时可用性。

为什么我的 Agent 收到了 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 中创建一个 key，然后使用上述命令将 catalog 配置添加到您的客户端。