TokenLab MCP Server 是一个由 OpenAPI 自动生成的 Model Context Protocol（MCP）服务器，面向 TokenLab 公共 API，提供模型发现、定价查询、原生 LLM 端点、类型化决策、多模态生成、异步任务、文件、嵌入、重排、翻译、资源、提示词以及更广泛的开发者 API 能力。
用途 该服务器主要供智能体在调用 TokenLab API 之前进行模型选择、查看支持的请求格式或比较价格。它同时暴露公开目录工具和需要凭据的工具：公开目录工具无需 API 密钥；凭据工具覆盖文本推理、图像生成与编辑、视频、音乐、3D、异步任务轮询、嵌入、重排、类型化决策和文本翻译。
主要能力
- 公开目录工具：用于模型发现、定价比较和请求格式查看。
- 凭据工具：文本推理、图像生成与编辑、视频、音乐、3D、异步任务轮询、嵌入、重排、类型化决策、文本翻译。
- 原生 MCP 特性：JSON 工具响应包含 structuredContent，同时保留序列化文本以兼容旧客户端；HTTP 错误保留原始响应文本（最多 4,000 字符），并附带结构化状态、请求 ID 和重试时间；生成工具提供可读标题、标准只读/破坏性/幂等/开放世界注解以及响应请求 ID。
- 资源与提示词：三个资源分别暴露实时 API 概览、包的 OpenAPI 快照和紧凑的 MCP 公共契约；choose_tokenlab_model 和 build_tokenlab_request 提示词引导智能体使用实时模型信息并保留原生端点形态。
- 服务器指令：提示客户端确认计费或破坏性操作，并将外部模型/API 输出视为不可信内容。
工具配置档与模式
- TOKENLAB_MCP_TOOL_PROFILE=catalog：最小的仅公开工具列表。
- TOKENLAB_MCP_TOOL_PROFILE=core（默认）：核心工具集。
- TOKENLAB_MCP_TOOL_PROFILE=full：广泛的开发者 API。
- TOKENLAB_MCP_SCHEMA_MODE=portable（默认随配置档）、exact、strict。exact 仅在客户端需要完整嵌套 JSON Schema 且能接受更大/更深工具负载时使用；strict 适用于要求所有属性列入 required 且每个对象设置 additionalProperties: false 的提供方，复杂顶层参数以 JSON 编码字符串表示，并在规范验证前解码。 版本 0.6.30 生成 87 个端点工具；加上两个 MCP 专用复合发现工具，完整配置档从 tools/list 返回 89 个工具。所有配置档都包含 compare_models 和 get_api_overview，总数分别为 6、32 和 89。实时和仅流式操作被排除，因为 stdio MCP 工具调用只返回一个最终结果。
使用方式 从 npm 安装：
Agent 辅助安装器可遵循 llms-install.md 进行凭据安全设置和验证流程。 使用凭据 API 工具时添加 -e TOKENLAB_API_KEY。公开目录工具不需要密钥。 Claude Desktop 风格配置：
公开目录和定价操作不需要 TokenLab API 密钥。当凭据工具需要调用 TokenLab API 时设置 TOKENLAB_API_KEY。生成工具保留 OpenAI 兼容和原生端点的 OpenAPI 请求形态，而不是将其扁平化为共享提示格式。 多部分操作接受本地文件路径。小型图像和音频响应作为原生 MCP 内容返回；较大或其他二进制响应写入 TOKENLAB_ARTIFACT_DIR，并返回路径、MIME 类型和字节数。
同步与异步媒体结果 视频、音乐和 3D 创建工具始终返回异步任务。图像生成和编辑可能返回已完成结果或异步任务，取决于所选模型和请求。媒体工具在 response 下保留完整的 TokenLab API 响应，并添加规范化交付摘要。应使用 delivery.mode 而不是假设所有图像请求都是同步的。对于异步任务，调用 get_task_status 并传入 { "id": delivery.task_id }，直到 delivery.terminal 为 true。完成状态由 status 决定，而不是可选的 progress 字段。
环境变量
- 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
图像输入与 MIME 处理 对于 Chat Completions 图像输入，优先使用字节精确的数据 URL，例如 data:image/png;base64,...。如果 MCP 调用方将可识别的 PNG、JPEG、WebP 或 GIF 负载标记为 application/octet-stream，服务器会在转发前纠正该通用 MIME。无法识别的通用二进制负载会在本地以精确输入错误拒绝。
契约与发布 公共 OpenAPI 文档是 API 契约来源。overlay 仅包含 MCP 特定选择：配置档暴露、稳定工具别名、密钥省略、非流式约束、内容类型变体、异步任务语义以及网站和文档门禁使用的紧凑公共投影。手动契约同步前始终运行 git pull --ff-only。contract:check 仅证明内部一致性；contract:source-check 证明相对规范源的新鲜度。计划中的 Sync TokenLab OpenAPI contract 工作流运行完整写入序列，并仅将已验证的 OpenAPI 快照和生成清单提交到 main。获取失败、本地分支过期、生成输出脏、生成错误、schema 编译错误或测试失败都会使受跟踪契约保持不变。
MCP Registry 元数据 仓库包含用于官方 MCP Registry 的 server.json。发布元数据：npm 包 @tokenlabai/mcp-server@0.6.30；MCP registry 名称 io.github.hedging8563/tokenlab；package.json.mcpName 为 io.github.hedging8563/tokenlab。新版本发布时，在 package.json、package-lock.json 和 server.json 中提升匹配版本；推送匹配标签如 v0.6.0；发布工作流测试并通过可信发布发布 npm，然后通过 GitHub Actions OIDC 发布 MCP Registry 条目。同一工作流可从 main 手动运行，仅重新发布当前 MCP Registry 元数据。GitHub 中不存储 npm 或 MCP Registry 令牌。
安全建议 不需要凭据工具时使用 catalog 配置档。将 TOKENLAB_API_KEY 保存在本地 MCP 客户端的秘密环境中，为计费和破坏性调用启用人工确认，并在授予持久批准前审查工具注解。不要将 TokenLab API 密钥发送到不受信任的托管 MCP 服务器。
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-... 分开设置。在 Dashboard → API → Management Tokens 创建管理令牌。它仅在其工作区内授权管理操作，不限于 webhook。推理密钥不能替代它；创建/轮换返回的 whsec_... 仅用于接收方签名验证。将所有凭据排除在工具参数和提示词之外。Webhook 通知避免持续任务轮询。在轮询回退时，遇到终态、401/403/404 或 retryable: false 时停止；对瞬时失败进行退避。
适用场景 适用于需要通过 MCP 客户端接入 TokenLab API 的智能体工作流，包括模型选择与定价比较、文本推理、多模态生成、异步任务管理、嵌入与重排、翻译以及 webhook 管理。
限制 实时和仅流式操作被排除，因为 stdio MCP 工具调用只返回一个最终结果。API 操作中接受 stream 的会在内部固定为 false，不向提供方适配器暴露布尔常量；Gemini 查询字符串 API 密钥有意从工具参数中隐藏。create_gemini_content 暴露 camelCase Gemini 字段（systemInstruction、generationConfig、safetySettings、toolConfig、cachedContent），并隐藏其 snake_case proto 拼写。兼容性预算保持 core 不超过 60 KB 且深度 8，full 不超过 115 KB 且深度 8。测试还使用观察到的 OpenCode/Gemini 失败所用的 Google AI SDK 版本运行完整配置档，并将其函数声明保持在 90 KB 以内。
网站：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
