通过 MCP（Model Context Protocol） 调用 TokenHub 大模型服务平台能力的 MCP Server。客户在任何支持 MCP 的客户端（WorkBuddy / Claude Desktop / Cursor / 各类 AI IDE）中配置 TokenHub API Key，即可用自然语言调用文生图、图生图、可灵（Kling）视频生成等能力。
不需要在配置里改模型。MCP 内置模型注册表，AI 会先通过 tokenhub_list_models 查询可用模型，再按你对话中指定的模型调用对应工具并构建请求：
用户："用 kling-video-v3 生成一个海边日落的视频" → AI 查模型注册表 → 调用
tokenhub_kling_text_to_video(model="kling-video-v3", ...)→ 返回 task_id → 轮询tokenhub_kling_get_task直到拿到视频
TOKENHUB_MODEL 环境变量仅作为兜底默认值（不传 model 时使用），日常使用建议直接对话指定模型。
Related MCP server: Vertex AI Imagen MCP Server
在 MCP 客户端配置中新增一个命令类型的 MCP Server：
客户端 | 配置位置 |
WorkBuddy |
|
Claude Desktop |
|
Cursor | Settings → MCP → Add new MCP server |
{
"mcpServers": {
"tokenhub": {
"type": "stdio",
"command": "npx",
"args": ["-y", "tokenhub-aigc-model"],
"env": {
"TOKENHUB_API_KEY": "你的 TokenHub API Key",
"TOKENHUB_BASE_URL": "https://tokenhub.tencentmaas.com",
"TOKENHUB_TIMEOUT_MS": "120000"
},
"description": "TokenHub 生图/生视频 MCP"
}
}
}
TOKENHUB_MODEL可不配：默认在对话中指定模型；不指定时生图用custom-model-og-v2、视频用kling-video-v3。⚠️ 超时配置：
TOKENHUB_TIMEOUT_MS（毫秒）为单次请求超时，默认120000（120 秒）。文生图/图生图为同步接口，高画质/大尺寸下生成耗时可能较长；若日志出现"请求超时"，请调大该值（如300000）。
{
"mcpServers": {
"tokenhub": {
"url": "https://你的服务域名/mcp",
"headers": { "x-mcp-auth-token": "部署时设置的 MCP_AUTH_TOKEN" }
}
}
}变量 | 必填 | 默认值 | 说明 |
| 是（调用时报错） | - | TokenHub 控制台获取的 API Key，请求头 |
| 否 |
| 站点域名（见下），末尾无需斜杠 |
| 否 |
| 兜底默认模型：仅当调用不传 model 时生效。推荐在对话中直接指定模型 |
| 否 |
| 单次请求超时（毫秒）。生图为同步接口，高画质/大尺寸生成耗时长，超时请调大（如 |
| 否（HTTP 模式建议） | - | HTTP 模式可选鉴权，设置后 /mcp 请求必须携带 |
TokenHub 按地域分站部署，不同站点的客户需填写对应域名。默认是国内站广州：
站点 | 域名（示例） |
国内站 · 广州 |
|
其他站点（国内新加坡 / 国际站广州、新加坡、美西等） | 请联系 TokenHub 商务/技术支持获取对应域名，填入 |
工具 | 能力 | 适用模型 | 文档 |
| 查询可用模型注册表（对话式选模型的入口） | - | - |
| 文生图（同步） | custom-model-og-v2 | |
| 图生图 / 图片编辑（同步） | custom-model-og-v2 | |
| 可灵文生视频（异步提交） | kling-video-v3 等 4 款 | |
| 可灵图生视频（异步提交） | kling-video-v3 等 4 款 | |
| 可灵任务查询 / 轮询 | 所有 kling 视频任务 |
以
tokenhub_list_models实时返回为准，下表为当前注册内容（v0.3.0）。
模型 | 厂商 | 能力 | 可用工具 | 文档 |
custom-model-og-v2 | og-image | 文生图 / 图生图 | generate_image, edit_image | |
kling-video-v3（默认） | kling | 文生视频 / 图生视频 | kling_text_to_video, kling_image_to_video (+ get_task 轮询) | |
kling-video-v3-turbo | kling | 文生视频 / 图生视频 | 同上 | |
kling-video-v2.6 | kling | 文生视频 / 图生视频 | 同上 | |
kling-video-v2.5-turbo | kling | 文生视频 / 图生视频 | 同上 |
用户：画一只在竹林中跳舞的小猫，2048x2048
AI（内部动作）：
tokenhub_list_models→ 发现 custom-model-og-v2 → 调用tokenhub_generate_image({ model: "custom-model-og-v2", prompt: "一只在竹林中跳舞的小猫", size: "2048x2048" })AI 返回：图片 URL + request_id + token 用量
用户：用 kling-video-v3 生成 5 秒 16:9 的视频：黄昏海滩上女孩看日落
AI（内部动作）：
tokenhub_list_models→ 调用tokenhub_kling_text_to_video({ model: "kling-video-v3", prompt: "黄昏海滩上女孩看日落", settings: { aspect_ratio: "16:9", duration: 5 } })AI 返回：
task_id: 251435731-WandVideo-xxxx，并说明："任务已提交，视频生成需要几分钟，我可以帮你持续查询进度。"用户：查询进度
AI（内部动作）：
tokenhub_kling_get_task({ task_id: "251435731-WandVideo-xxxx" })→ status=processing → 回复："正在生成中，约 3~5 秒后再查一次。"用户：再查一下
AI（内部动作）：
tokenhub_kling_get_task(...)→ status=succeeded → 返回视频地址："生成完成！视频链接：https://...mp4（临时链接，请及时保存）"
用户：用这张图作为首帧，让画面中的猫转头，模型用 kling-video-v3
AI（内部动作）：
tokenhub_list_models→ 调用tokenhub_kling_image_to_video({ model: "kling-video-v3", contents: [{ type: "prompt", text: "让画面中的猫自然转头" }, { type: "first_frame", url: "https://...jpg" }] })→ 拿 task_id → 轮询tokenhub_kling_get_task→ 返回视频
工具调用失败返回 isError: true，错误信息包含 status、上游错误 code、request_id。
HTTP 200 但业务 code != 0（可灵等统一外壳接口）：同样按错误透传 code 与 message。
出现权限/限流/参数错误时，请保留 request_id 提交给 TokenHub 技术支持定位。
未配置 TOKENHUB_API_KEY 时，工具调用直接返回明确提示（server 可正常启动，tokenhub_list_models 不受影响）。
# 本地启动（默认 stdio）
npx -y tokenhub-aigc-model
# HTTP 模式
TOKENHUB_API_KEY=xxx MCP_AUTH_TOKEN=部署密钥 \
npx -y tokenhub-aigc-model --transport=http --port=3000 --host=127.0.0.1端点：
POST /mcp、GET /mcp：MCP 协议入口
GET /health：健康检查
部署到公网时务必：
设置 MCP_AUTH_TOKEN，或在前置网关/反向代理（如 EdgeOne、CLB、Nginx）做鉴权；
使用 HTTPS；
base_url 支持单次覆盖，仅建议在可信环境下开放。
npm install # 安装依赖
npm run build # TypeScript 构建到 dist/
npm test # 单元测试 + stdio/HTTP 冒烟测试（共 37 个用例）
npm pack --dry-run # 查看发布内容发布到 npmjs（当前 registry 若是腾讯镜像，需显式指定）：
npm run build
npm test
npm version 0.3.0 # 升版本（或手改 package.json）
npm publish --access public --registry=https://registry.npmjs.org
git tag v0.3.0 && git push --tags开白：TokenHub 模型多为白名单制，需联系 TokenHub 产品/后台人员提交 UIN 和 Appid 开白后方可使用；未开白调用会返回权限错误（保留 request_id 排查）。
API Key：请在 TokenHub 控制台 为对应模型创建专属 Key；Key 只在创建时展示一次，请妥善保存。
计费：TokenHub 按 Token 计费（约 10 元/百万 token），小时结算。生视频单次任务消耗远高于生图（可达数十万 token），请商务及时为客户申请折扣。
同步生图超时：文生图/图生图为同步接口，单次请求可能耗时较长（默认超时 120 秒）。如遇"请求超时"，请在 MCP 配置中调大 TOKENHUB_TIMEOUT_MS（如 300000）。
视频临时链接：tokenhub_kling_get_task 返回的视频地址为临时链接（约 12 小时有效），请及时下载转存。
调用 TokenHub 接口，基于 1-16 张输入图 + 文本描述同步生成图片（模型默认 custom-model-og-v2，需开白）。支持局部重绘（mask）。输入图支持 URL 或 base64。返回图片 URL 列表、request_id 与 token 用量。
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | 生成图片数量 1-10，默认 1 | |
| mask | No | 局部重绘蒙版图，尺寸需与输入图一致 | |
| size | No | 生成尺寸 "宽x高"，如 2048x2048。约束：单边≤3840px、宽高为 16 的倍数、长短边比≤3:1、总像素 655360~8294400 | |
| model | No | 单次覆盖模型名。不传时用环境变量 TOKENHUB_MODEL（默认 custom-model-og-v2） | |
| images | Yes | 输入图 1-16 张，支持 URL 或 base64 | |
| prompt | Yes | 文本描述，最大 32000 字符 | |
| quality | No | 画质，默认 auto | |
| base_url | No | 单次覆盖站点域名（如 https://tokenhub.tencentmaas.com）。不传时用环境变量 TOKENHUB_BASE_URL | |
| background | No | 图像背景透明度：transparent 透明 / opaque 不透明 / auto 自动判断，默认 auto | |
| output_format | No | 输出格式，默认 png | |
| response_format | No | 返回格式：url（图片地址）或 b64_json（base64 数据），默认 url | |
| output_compression | No | JPEG 压缩级别 0-100，仅 output_format=jpeg 时生效 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the model default, whitelist requirement, mask support, URL/base64 input acceptance, and return fields. It does not mention error behavior, rate limits, or auth mechanics, but it covers the main operational characteristics well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, informative, and well-front-loaded. It covers the core operation, constraints, input formats, mask feature, and return payload in four sentences with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 12-parameter schema and absence of an output schema, the description provides enough operational context: input requirements, image count range, model default and whitelist, mask support, and response contents. It falls short of 5 only because of missing explicit alternative-tool routing and access/auth context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description mentions mask, input images, model default, and input formats, but most of these details are already documented in the schema. It adds only high-level context like whitelist and return metadata, not substantial new parameter-level semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: calling TokenHub to generate an image from 1-16 input images plus a text prompt, with support for mask-based local repainting. It also specifies the output contents (image URL list, request_id, token usage), making the tool's purpose and scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual signals for when to use this tool: when existing images are provided as input and editing/repainting is needed. It doesn't explicitly exclude or name the alternative tokenhub_generate_image, so the routing guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
调用 TokenHub 接口，根据文本描述同步生成图片（模型默认 custom-model-og-v2，需在 TokenHub 控制台开白并配置专属 API Key）。返回图片 URL 列表、request_id 与 token 用量。
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | 生成图片数量 1-10，默认 1 | |
| size | No | 生成尺寸 "宽x高"，如 2048x2048。约束：单边≤3840px、宽高为 16 的倍数、长短边比≤3:1、总像素 655360~8294400 | |
| model | No | 单次覆盖模型名。不传时用环境变量 TOKENHUB_MODEL（默认 custom-model-og-v2） | |
| prompt | Yes | 文本描述，最大 32000 字符 | |
| quality | No | 画质，默认 auto | |
| base_url | No | 单次覆盖站点域名（如 https://tokenhub.tencentmaas.com）。不传时用环境变量 TOKENHUB_BASE_URL | |
| background | No | 图像背景透明度：opaque 不透明 / auto 自动判断，默认 auto | |
| output_format | No | 输出格式，默认 png | |
| response_format | No | 返回格式：url（图片地址）或 b64_json（base64 数据），默认 url | |
| output_compression | No | JPEG 压缩级别 0-100，仅 output_format=jpeg 时生效 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the call is synchronous, requires the user to have whitelisted the model and configured a dedicated API key, and that the response includes image URLs, request_id, and token usage. It does not cover error behavior or rate limits, but the key behavioral constraints are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, information-dense sentences with no redundancy. It ends with the action and auth prerequisite, then return values. Every word contributes to the agent's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters and no output schema, the description covers the important context: synchronous, auth required, default model, return shape. The schema covers parameter details, and what is missing (timeouts, error behavior) is minor for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all 10 parameters with detailed per-parameter descriptions, so the description adds very little for parameters. Mentioning the default model is useful but overlaps with the schema's model field. This is the expected baseline since schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: calling TokenHub to synchronously generate an image from a text description, and identifies the resource (image). It does not explicitly contrast with tokenhub_edit_image, but the 'generate from text' wording is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the appropriate scenario (generate an image from a prompt) and provides essential prerequisites (whitelist + dedicated API key). However, it gives no explicit guidance on when to prefer this over tokenhub_edit_image or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0tokenhub_edit_imagetokenhub_generate_imageScored across 2 tools
The two tools have clearly distinct purposes: one generates an image purely from text, while the other edits/generates from 1-16 input images with optional masking. There is no realistic confusion between them.
Both tools follow the same tokenhub_<verb>_image pattern with static verb prefixes: edit and generate. The naming convention is consistent and predictable.
With only two tools, the server is slightly thin, but each tool covers a distinct core task in the image-generation domain. The focused scope makes the small count reasonable.
The two primary workflows—text-to-image generation and image editing/reinpainting—are covered, and the synchronous design avoids needing result-status tools. A minor gap is the lack of model-list or capability-discovery tooling, but agents can still complete the core tasks.
Generate AI images and videos from any compatible MCP client.
Generate images with any major model — one API key, one prepaid balance, one MCP.
Multi-model AI image and video generator. 14 models behind one OAuth-secured MCP endpoint.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
