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

TokenLab MCP 是一个只读的 Model Context Protocol (MCP) 服务器，它能让编码代理在编写任何集成代码之前，直接、结构化地访问 TokenLab 的公共模型目录、定价和 API 概览。它能回答发现类问题——例如当前存在哪些模型 ID、它们的成本是多少、支持哪些模态——并且它不会代表你调用付费推理 API。

许多代理集成错误并非始于第一次 API 调用，而是始于更早的阶段：当代理从过时的示例、缓存的记忆或六个月前的教程中选择模型 ID，直到遇到 404 错误或定价意外时才发现不匹配。

编码代理编写代码的速度很快。它们并不总是先阅读。除了 TokenLab MCP，TokenLab 还发布了精简版的 llms.txt、更详尽的 llms-full.txt 以及公共模型数据 JSON 文件——这些就是你可以自行浏览的 模型目录 和 定价 页面——因此代理在硬编码任何内容之前可以先核实当前的模型 ID 和成本。

本文介绍了这些页面是什么、它们不是什么，以及如何配置代理以在硬编码模型名称之前使用它们。有关完整的端点参考，请参阅 集成文档。

关键要点

• TokenLab 在 api.tokenlab.sh/llms.txt 和 llms-full.txt 发布了代理可读的 API 概览，Web 域名也会重定向到相同的源。
• 公共模型数据中心文件（目录 JSON、最新 JSON、趋势 JSON、摘要 Markdown）为代理提供了 TokenLab 当前所提供内容的实时可查询快照。
• TokenLab MCP 服务器公开了 list_models、get_model、get_model_pricing 和 get_api_overview——且它是只读的。它不代理付费推理。
• 公共文档建议代理在硬编码模型名称之前调用 /v1/models 或阅读 llms.txt，并对图像、视频或嵌入等非聊天任务使用 recommended_for 过滤。
• 在重试失败的非聊天请求之前读取模型和定价端点，可以避免针对错误的模型系列进行重复的失败调用。

为什么代理首先会选择过时的模型 ID

编码代理生成的模型 ID 来自于它们在训练期间学到的内容，而不是当前可用的内容。训练数据有截止日期，因此代理对“当前模型”的内在认知固定在权重最后一次更新时的状态。当你要求代理调用模型 API 时，它会自信地使用它记忆中的 ID——即使该 ID 此后已被重命名、弃用或替换。

这不是代理推理中的错误；这是任何依赖记忆知识而非实时查询的系统的结构性限制。解决方法不是更聪明的提示词，而是给代理一个在编写代码前进行核实的地方。

这就是 TokenLab 的模型数据文件和 API 存在的原因。在生成请求之前，代理（或审查其输出的人类）可以查询实时端点，以确认模型 ID 是否确实存在、它支持什么模态以及成本是多少——而不是盲目信任从记忆中提取的名称。

端点	用途
https://tokenlab.sh/model-data/catalog.json	已跟踪模型的完整目录，结构化以便程序化查找
https://tokenlab.sh/model-data/latest.json	以轻量级、代理友好格式呈现的当前模型列表
https://tokenlab.sh/en/models	人类可读的模型浏览器
https://tokenlab.sh/en/pricing	按模型和模态划分的当前定价

博客文章（包括本文）只是一个快照。它反映的是撰写时的真实情况，并且会像代理的训练数据一样逐渐过时。实时端点没有这个问题：它们反映的是当下的真实情况，这就是为什么在代码发布前检查它们比检查静态文章更安全。

TokenLab 为代理发现公开的内容

llms.txt 层

https://api.tokenlab.sh/llms.txt 是 API 的紧凑型、代理可读概览：存在哪些端点、请求是什么样子的，以及在哪里可以找到更详细的信息。它的设计足够简短，代理可以在单个上下文窗口中读取它，而无需消耗大量的 token 预算来定位自己。

https://api.tokenlab.sh/llms-full.txt 是更完整的版本——包含更多端点细节、更多示例，以及代理在生成可运行的集成代码（而非草稿）之前所需的更多表面信息。

如果你访问的是 Web 域名而不是 API 主机，tokenlab.sh/llms.txt 和 tokenlab.sh/llms-full.txt 会重定向到相同的 API 托管源。这对代理很重要：无论它们抓取或获取哪个入口点，它们最终都会得到相同的规范文本，而不是两个分歧的副本。

模型数据中心

除了文本概览，TokenLab 还发布了代理（或构建脚本）可以直接拉取的结构化 JSON 文件：

• https://tokenlab.sh/model-data/catalog.json — 更完整的模型目录。
• https://tokenlab.sh/model-data/latest.json — 面向当前最新内容的快照。
• https://tokenlab.sh/model-data/summary.md — 人类和代理均可读的 Markdown 摘要，当你想要快速对比代码库当前硬编码的内容时非常有用。

这些是静态的、可获取的文件。构建配置文件、.env 模板或模型选择下拉菜单的代理可以直接拉取 JSON，而不是要求人类粘贴一个两周后就会过时的模型列表。

MCP 服务器——只读的，且有必要明确这一点

https://github.com/hedging8563/tokenlab-mcp-server 是公开的。它公开了四个与发现相关的工具：

• list_models — 枚举可用内容，可选择过滤。
• get_model — 拉取特定模型 ID 的详细信息。
• get_model_pricing — 拉取特定模型的当前定价。
• get_api_overview — 读取 llms.txt 的 MCP 原生等效项。

重要的限制：此服务器是只读的。它不会代表你调用付费推理 API，也不会代理生成请求。它回答有关模型、定价和 API 形状的问题。如果你的代理确实需要运行推理，它仍然会使用你自己的密钥通过 TokenLab 的正常 API 进行——MCP 服务器是一个发现层，而不是执行层。将两者混为一谈是一个常见的错误，值得在你编写的任何代理提示词或技能文件中明确避免。

TokenLab MCP 发现示例

TokenLab 公开了一个只读的 Model Context Protocol (MCP) 服务器，让编码代理能够发现可用模型和定价，而无需执行任何推理。MCP 服务器提供四个工具：

• list_models — 列出可用模型，可选择按 recommended_for 过滤（例如 image、video、embedding、rerank、translation）
• get_model — 检索特定模型的详细信息
• get_model_pricing — 检索特定模型的定价信息
• get_api_overview — 检索 TokenLab API 的摘要

示例：通过 MCP 列出模型

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

示例：按推荐用途过滤模型

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

如果你更愿意直接查询 API 而不是通过 MCP，等效的 REST 调用如下：

# 列出所有模型
curl https://api.tokenlab.sh/v1/models \
  -H "Authorization: Bearer sk-KEY"

# 列出推荐用于图像任务的模型
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-KEY"

请注意，MCP 服务器是严格只读的——它旨在用于发现（列出模型、检查定价和审查 API 功能），本身不执行任何推理。

有关设置说明和集成详情，请参阅：

• TokenLab MCP Server
• Coding Agent Skill

技能仓库

https://github.com/hedging8563/tokenlab-skills 将此发现模式打包成编码代理框架可以直接加载的内容——一个技能定义，告诉代理“在编写 TokenLab 集成代码之前阅读此内容”，而不是依赖代理独立决定去检查。

推荐的代理工作流程

公共文档描述了一个特定的序列，在实践中非常有效：

1. 在硬编码任何模型名称之前，调用 /v1/models 或阅读 llms.txt 以确认该 ID 现在确实存在。
2. 对于非聊天任务——图像、视频、音乐、3D、TTS、STT、嵌入、重排序、翻译——使用 /v1/models?recommended_for=<task> 进行过滤，而不是假设聊天导向的模型能处理该任务，或凭记忆猜测模型名称。
3. 在重试失败的非聊天请求之前，阅读 /v1/models/:model 和 /v1/models/:model/pricing。针对错误模态模型的失败请求在重试相同输入时通常会再次失败；先检查模型的实际模态和定价可以节省重试循环。

这个序列很重要，因为它预先解决了两种最常见的故障模式：错误的模型 ID 和任务对应的错误模型系列。

将此集成到代理中的实用检查清单

步骤	检查内容	位置
1	此模型 ID 是否仍然有效？	/v1/models 或 llms.txt
2	这是任务对应的正确模型系列吗（聊天 vs 图像 vs 嵌入等）？	/v1/models?recommended_for=<task>
3	此模型的当前输入/输出定价是多少？	/v1/models/:model/pricing 或 get_model_pricing (MCP)
4	上下文窗口和模态是什么？	/v1/models/:model 或 get_model (MCP)
5	是否有名称相似的新模型取代了此模型？	catalog.json / latest.json
6	代理在生成集成代码前是否阅读了 llms.txt？	在代理的工具调用日志中确认

如果代理跳过步骤 1 和 2，下游的一切——重试、错误处理、成本估算——都建立在假设而非事实之上。

为什么这对非聊天任务尤为重要

聊天模型获得了大部分关注，但 recommended_for 过滤器的存在是因为非聊天任务会以不太明显的方式失败。一个为文本到文本生成而构建的模型在对图像请求返回格式错误的响应时，并不总是会抛出清晰、不言自明的错误。有时它只是返回代理不知道如何解析的内容。

通过 recommended_for=image、recommended_for=video、recommended_for=embedding 等进行过滤，可以在代理编写请求体之前缩小候选集。考虑到在 模型目录 中随时可能存在许多不同的图像生成条目——nano-banana-2 (Gemini 3.1 Flash Image)、nano-banana-pro (Gemini 3 Pro Image)、nano-banana-2-lite (Gemini 3.1 Flash Lite Image)、openai/gpt-image-2、reve/reve-2.0、microsoft/mai-image-2.5——凭记忆猜测哪一个是“图像模型”正是此工作流程旨在防止的故障模式。视频生成有其自己的一套任务特定模型（包括 seedance、veo-3 等），具有不同的定价和模态形状；同样的过滤逻辑也适用。

有关此处命名的任何特定模型的准确当前定价、上下文限制和模态，请直接查看 模型目录 和 定价页面——这就是不将其硬编码到博客文章中的全部意义所在。如果你正在评估用于代理驱动开发工作的模型，请参阅 2026 年最佳 AI 编码模型。

此功能不做什么

在此处保持精确与工作流程本身同样重要：

• MCP 服务器不执行付费推理。它回答发现类问题。运行实际的生成请求仍然需要通过标准 API 并使用你自己的凭据。
• llms.txt 和模型数据中心文件是定期快照，而不是实时数据库连接。刷新时间并非固定在严格的时间表上，因此请将这些页面上的任何日期视为近似值。对于任何价格敏感或安全敏感的内容，定价端点 和 仪表板 API 在请求时仍然是事实来源。
• 这些内容都不能取代阅读完整的 API 文档以了解身份验证、速率限制或错误处理语义。发现层告诉代理存在什么；它们不能取代关于如何正确调用它的集成文档。

常见问题解答

代理在选择 TokenLab 模型之前应该阅读什么？ 在硬编码任何模型 ID 之前，请阅读 llms.txt（或 llms-full.txt 以获取更多详细信息）并调用 /v1/models。对于非聊天任务，请使用 recommended_for 进行过滤，而不是凭记忆猜测模型名称。

TokenLab MCP 是否调用付费推理 API？ 不。公共 TokenLab MCP 服务器是只读的。它的工具（list_models、get_model、get_model_pricing、get_api_overview）回答有关模型和定价的发现类问题。实际的推理调用会使用你自己的密钥通过标准 API 进行。

代理何时应该使用 recommended_for？ 只要任务不是纯聊天——图像、视频、音乐、3D、TTS、STT、嵌入、重排序或翻译。按任务过滤可以将模型列表缩小到确实为该模态构建的变体，而不是假设聊天导向的模型能处理它。

这如何减少生成代码中过时的模型 ID？ 通过将发现作为第一步而不是事后补救。一个在编写代码前阅读 llms.txt、检查 /v1/models 并确认定价的代理，是基于当前快照工作的，而不是基于可能已经过时几个模型世代的训练时记忆。

来源与新鲜度

• TokenLab llms.txt — https://api.tokenlab.sh/llms.txt — 观测于 2026-07-09
• TokenLab llms-full.txt — https://api.tokenlab.sh/llms-full.txt — 观测于 2026-07-09
• TokenLab MCP Server 文档 — https://docs.tokenlab.sh/integrations/tokenlab-mcp-server — 观测于 2026-07-09
• TokenLab API 集成技能文档 — https://docs.tokenlab.sh/integrations/coding-agent-skill — 观测于 2026-07-09
• TokenLab MCP Server 仓库 — https://github.com/hedging8563/tokenlab-mcp-server — 观测于 2026-07-09
• TokenLab 技能仓库 — https://github.com/hedging8563/tokenlab-skills — 观测于 2026-07-09
• TokenLab 模型数据中心 — https://tokenlab.sh/model-data/catalog.json, https://tokenlab.sh/model-data/latest.json, https://tokenlab.sh/model-data/summary.md — 观测于 2026-07-09

本文中的模型 ID、定价和模态详情反映了撰写时的快照。像本文和 llms.txt 这样的快照页面会定期更新，但不是以固定或保证的节奏更新——不要围绕假设的刷新间隔构建重试逻辑或成本估算。在发布集成代码之前，请根据 定价页面 和 模型目录 核实当前值。有关定价如何在模型系列中构建的更深入了解，请参阅 Gemini API 开发者定价。

TokenLab MCP 的后续步骤

要开始使用 TokenLab MCP 进行模型发现：

1. 从 TokenLab 仪表板 获取 API 密钥。
2. 按照 编码代理集成指南 连接你的代理。
3. 直接在 tokenlab.sh/en/models 浏览目录，查看当前模型覆盖范围和元数据。
4. 在 tokenlab.sh/en/pricing 查看你计划使用的模型的定价。

如果你正在决定哪些模型适合你的工作流程，请参阅我们关于 2026 年最佳 AI 编码模型 和 Gemini API 开发者定价 的分析。

请记住，MCP 严格来说是一个发现层——它呈现模型元数据、功能和定价，以便你的代理可以做出明智的决定。实际的推理调用仍然使用你自己的 API 密钥通过标准 TokenLab API 进行；MCP 不路由或代理请求。