MCP(Model Context Protocol)을 통해 TokenHub 대규모 모델 플랫폼의 이미지 생성 기능을 호출하는 MCP Server입니다. 고객은 MCP를 지원하는 모든 클라이언트(WorkBuddy / Claude Desktop / Cursor / 각종 AI IDE)에서 TokenHub API Key만 설정하면 자연어로 직접 텍스트-이미지 생성, 이미지-이미지 생성/이미지 편집 인터페이스를 호출할 수 있습니다.
현재 내장 샘플 모델: custom-model-og-v2(GPT 계열 이미지 생성 모델, 동기 반환).
두 개의 도구
tokenhub_generate_image: 텍스트-이미지 생성(POST /v1/wand/og-image/generation, 동기 반환)
tokenhub_edit_image: 이미지-이미지 생성/이미지 편집(POST /v1/wand/og-image/edits, 동기 반환, 입력 이미지 1-16장, mask 부분 리터칭 지원)
이중 전송
stdio(기본값): 로컬 클라이언트에 직접 연결, 배포 불필요
streamable-http: 원격 엔드포인트로 배포하여 외부 고객/팀이 원격으로 연결
유연한 구성: API Key, 사이트 도메인, 모델명을 모두 환경 변수로 구성 가능하며 단일 호출에서 도메인/모델을 재정의할 수 있습니다(사이트나 모델 전환 시 구성 변경 불필요).
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_MODEL": "custom-model-og-v2"
},
"description": "TokenHub 生图 MCP"
}
}
}구성 후 바로 대화할 수 있습니다: **「대나무 숲에서 춤추는 작은 고양이 한 마리를 그려줘, 2048x2048」**을 입력해 보세요.
{
"mcpServers": {
"tokenhub": {
"url": "https://你的服务域名/mcp",
"headers": { "x-mcp-auth-token": "部署时设置的 MCP_AUTH_TOKEN" }
}
}
}변수 | 필수 여부 | 기본값 | 설명 |
| 예(설정하지 않으면 호출 시 오류) | - | TokenHub 콘솔에서 발급받은 API 키로, 요청 헤더 |
| 아니요 |
| 사이트 도메인(아래 사이트 설명 참조), 끝에 슬래시 필요 없음 |
| 아니요 |
| 기본 모델명, 단일 호출에서 재정의 가능 |
| 아니요(HTTP 모드 권장) | - | HTTP 모드의 선택형 인증, 설정 후 |
TokenHub는 지역별로 사이트를 분산 배포하므로, 사이트가 다른 고객은 해당 도메인을 입력해야 합니다. 기본값은 국내 거점 · 广州입니다:
| 사이트 | 도메인(예시) |
| ------------------------ | ------------------------------------------------------------ | |
| 국내 거점 · 广州 | https://tokenhub.tencentmaas.com(기본값) |
| 기타 거점(국내 업데이트 모두 / 국제 거점 广州· Singapore·美西 등) | TokenHub 영업/기술 지원에 연락하여 해당 도메인을 받아 TOKENHUB_BASE_URL에 입력하거나 단일 호출 시 base_url로 전달하세요 |
매개변수 | 필수 | 설명 |
| 예 | 텍스트 설명, 최대 32000자 |
| 아니요 | 단일 호출에서 사이트 도메인/모델명 재정의 |
| 아니요 | 생성 크기 |
| 아니요 |
|
| 아니요 | 생성 이미지 수 1-10, 기본 1 |
| 아니요 |
|
| 아니요 |
|
| 아니요 | JPEG 압축 수준 0-100(jpeg 전용) |
| 아니요 |
|
위 표의 대부분 매개변수를 공유하고, 추가로:
매개변수 | 필수 | 설명 |
| 예 | 입력 이미지 1~16장, |
| 아니요 | 부분 리터칭용 마스크, 크기는 입력 이미지와 동일해야 함 |
| 아니요 | 추가로 |
반환 값: 이미지 URL 리스트, request_id(문제 조용), total_tokens(과금용); response_format=b64_json이면 base64 이미지 블록이 포함되어 직접 표시할 수 있습니다.
도구 호출 실패 시 isError: true를 반환하며, 오류 정보에는 status, ・서 오류 code, request_id가 포함됩니다.
권한/요청 빈도 제한/매개변수 오류가 발생하면, request_id를 보존하여 TokenHub 기술 지원에 제출하세요.
TOKENHUB_API_KEY가 설정되지 않으면 도구 호출 시 명확한 안내를 반환합니다(server는 정상적으로 시작할 수 있습니다).
# 本地启动（默认 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 冒烟测试（共 20 个用例）
npm pack --dry-run # 查看发布内容npmjs에 배포합니다(현재 registry가腾讯 미러인 경우 명시적으로 지정해야 합니다):
npm run build
npm version patch
npm publish --access public --registry=https://registry.npmjs.org
git tag v0.1.0 && git push --tags고급(White List): custom-model-og-v2는 테스트 모델이며, TokenHub 제품/기술 인력에게 UIN과 Appid를 제출하여 허가를 받아야 사용할 수 있습니다. 허가를 받지 않고 호출하면 오류가 반환됩니다.
API Key: TokenHub Console에서 해당 모델 전용 Key를 만들어 주세요. Key는 생성 시 한 번만 표시되므로 안전하게 보관하세요.
과금: TokenHub는 Token 단위로 과금하며(약 10원/백만 Token), 시간 단위로 결제됩니다. n>1 설정 또는 입력 이미지가 여러 장이면 Token Token 소모가 크게 증가하므로 사업 담당자는 고객을 위해 할인을 미리 신청하세요.
과금 공식(인민폐): 입력 텍스트 token×3.35 + 캐시된 텍스트 입력×0.8375 + image 입력×5.36 + 캐시 이미지 입력×1.34 + 출력 이미지×20.1 = 단일 태스크 token 소모(환산 계수는 환율에 따라 다르며, 현재 계수 6.7).
调用 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.
