TokenLab MCP Server

TokenLab MCP Server

基于 OpenAPI 生成的 Model Context Protocol 服务，适用于 TokenLab 的公开模型发现、定价、原生 LLM 端点、类型化决策、多模态生成、异步任务、文件、嵌入、重排序、翻译、资源、提示词及更广泛的开发者 API。

它提供公开目录工具，供需要选择模型、查看支持的请求格式或在调用 TokenLab API 前比较价格的 Agent 使用。需要凭证的工具涵盖文本推理、图像生成与编辑、视频、音乐、3D、异步任务轮询、嵌入、重排序、类型化决策和文本翻译。

生成的工具配置

已纳入版本控制的 generated/tools.json 清单由 TokenLab 的公开 OpenAPI 文档和 contract/mcp-overlay.json 中仅供 MCP 使用的小型覆盖文件生成。版本 0.6.38 会生成 87 个端点工具；加上两个仅供 MCP 使用的组合发现工具，完整配置会从 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 操作，包括核心功能，以及响应生命周期、批处理、worlds 和原生模型发现

已注册工具总数是 tools/list 返回的数量。所有配置都包含 compare_models 和 get_api_overview，因此工具总数分别为 6、32 和 89。实时和仅流式操作不在范围内，因为 stdio MCP 工具调用只返回一个最终结果。对于接受 stream 的 API 操作，内部会将其固定为 false，不会向提供方适配器公开布尔型 const；Gemini 查询字符串中的 API 密钥也会有意从工具参数中隐藏。create_gemini_content 会公开驼峰格式的 Gemini 字段（systemInstruction、generationConfig、safetySettings、toolConfig、cachedContent），并隐藏其蛇形格式的 proto 名称；API 会将这些名称作为别名接受。

便携投影会保留每个顶层参数，但会限制面向模型的深层嵌套结构。服务器仍会在发出 API 请求前，使用完整生成的 OpenAPI 模式验证调用。兼容性预算将 core 的完整 tools/list 响应控制在不超过 60 KB、深度不超过 8，将 full 控制在不超过 115 KB、深度不超过 8。测试还会使用观察到 OpenCode/Gemini 故障时所用的 Google AI SDK 版本运行完整配置，并将其函数声明控制在 90 KB 以内。

设置 TOKENLAB_MCP_TOOL_PROFILE=catalog 可获取最精简的纯公开工具列表；设置 TOKENLAB_MCP_TOOL_PROFILE=full 可获取范围广泛的开发者 API。只有当客户端需要完整的嵌套 JSON Schema 且能接受更大、更深的工具负载时，才设置 TOKENLAB_MCP_SCHEMA_MODE=exact。对于要求所有属性都列在 required 中且每个对象都设置 additionalProperties: false 的提供方，请使用 strict；复杂的顶层参数会以 JSON 编码字符串表示，并在规范验证前解码。规范工具名称、描述、输入 JSON Schemas、HTTP 绑定、内容类型、身份验证要求和任务行为可在 generated/tools.json 中查看。

较小的 generated/public-contract.json 是 TokenLab 网站及其他公开使用方所用的机器可读投影。它包含软件包标识、配置计数、核心工具层、资源、提示词和源文件哈希，不会复制所有端点模式。

原生 MCP 功能

• JSON 工具响应包含 structuredContent，同时保留序列化文本，以兼容旧版客户端。
• HTTP 错误会保留原始响应文本（最多 4,000 个字符），包括公开的修正提示，并附带结构化状态、请求 ID 和重试时间信息。仅公开请求 ID 和重试相关标头；失败的生成请求绝不会自动重新提交。
• 生成的工具会提供易读的标题、标准的只读／破坏性／幂等／开放世界注释，以及可用时的响应请求 ID。
• 工具架构会直接以 JSON Schema 的形式发布和验证。运行时不会将生成的工具架构经由 Zod 往返转换；exact 模式在字节形态上与生成的规范架构等效。
• 三个资源分别提供实时 API 概览、软件包的 OpenAPI 快照，以及精简的 MCP 公共契约。
• choose_tokenlab_model 和 build_tokenlab_request 提示词会引导 Agent 使用实时模型信息，并保留原生端点形态。
• 服务说明会告知客户端确认可计费或破坏性操作，并将外部模型／API 输出视为不可信内容。

运行

npm install
npm start

从 npm 安装：

npx -y @tokenlabai/mcp-server

Agent 辅助安装程序可按照 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 创建工具始终返回异步任务。图像生成和编辑则会根据所选模型和请求，返回已完成的结果或异步任务。

媒体工具会在 response 下保留完整的 TokenLab API 响应，并添加经过规范化的 delivery 摘要：

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

请使用 delivery.mode，不要假设所有图像请求都是同步的。对于异步任务，请使用 { "id": delivery.task_id } 调用 get_task_status，直到 delivery.terminal 为 true。任务是否完成由 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：可选，非内联响应产物的输出目录，默认为操作系统临时目录下的 tokenlab-mcp

对于 Chat Completions 图像输入，优先使用字节准确的数据 URL，例如 data:image/png;base64,...。如果 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 注册表元数据。GitHub 中不会存储 npm 或 MCP 注册表令牌。

安全

无需使用需要凭据的工具时，请使用 catalog 配置文件。将 TOKENLAB_API_KEY 保存在本地 MCP 客户端的机密环境变量中，对计费和破坏性调用启用人工确认，并在授予持久批准前检查工具注释。请勿将 TokenLab API 密钥发送给不可信的托管 MCP 服务。

每个 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
• Skills：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 指南。