TokenHub AIGC Model — MCP Server

An MCP Server that calls TokenHub's large-model image generation capabilities via MCP (Model Context Protocol). After configuring the TokenHub API Key in any MCP-compatible client (WorkBuddy / Claude Desktop / Cursor / various AI IDEs), customers can directly invoke text-to-image and image-to-image/image-editing interfaces using natural language.

Built-in sample model: custom-model-og-v2 (GPT-series image generation model, returns synchronously).

Features

• Two tools

  • tokenhub_generate_image: text-to-image (POST /v1/images/generations, synchronous return)

  • tokenhub_edit_image: image-to-image / image editing (POST /v1/images/edits, synchronous return, supports 1-16 input images and mask inpainting)

• Two transports

  • stdio (default): direct integration with local clients, zero deployment

  • streamable-http: deploy as a remote endpoint for external customers/teams to access remotely

• Flexible configuration: API Key, site domain, and model name can all be configured via environment variables; a single call can override the domain/model (switching sites or models requires no configuration changes)

Related MCP server: MCP OpenAI Image Generation Server

Quick Start

Method 1: stdio (local integration, recommended first)

Add a command-type MCP Server to your MCP client configuration:

{
  "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"
    }
  }
}

After configuration, you can start chatting: "Draw me a kitten dancing in the bamboo forest, 2048x2048".

Method 2: Streamable HTTP (remote deployment)

{
  "mcpServers": {
    "tokenhub": {
      "url": "https://你的服务域名/mcp",
      "headers": { "x-mcp-auth-token": "部署时设置的 MCP_AUTH_TOKEN" }
    }
  }
}

Environment Variables

Site domain

TokenHub is deployed across regional sites, and customers on different sites need to specify their corresponding domain. The default is the domestic Guangzhou site:

Tool Parameters

Token Generator

tokenhub_edit_image (image-to-image / edit)

Shares all of the parameters above. Additional parameters:

Returns: a list of image URLs, request_id (for troubleshooting), total_tokens (for billing); if response_format=b64_json, the optional side effect also includes base64 image blocks for direct display.

错误处理

• A failed tool call returns isError: true and the error message contains status, the upstream error code, and request_id.

• On permission / rate-limit / parameter errors, please keep the request_id to submit to TokenHub technical support for troubleshooting.

• If TOKENHUB_API_KEY is not configured, tool calls include multiple useful error message (the server can still start normally).

HTTP Mode Deployment (Remote)

# 本地启动（默认 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

Endpoints:

• POST /mcp、GET /mcp: MCP protocol entry

• GET /health: health check

When deploying to the public internet, make sure to:

1. Set the MCP_AUTH_TOKEN, or optionally perform authentication at the front-end gateway. reverse proxy (such as EdgeOne, CLB, Nginx);

2. Use HTTPS;

3. base_url supports per-call overrides; it is only recommended to open it in trusted environments.

開發與發佈

npm install        # 安装依赖
npm run build      # TypeScript 构建到 dist/
npm test           # 单元测试 + stdio/HTTP 冒烟测试（共 20 个用例）
npm pack --dry-run # 查看发布内容

publish to npmjs (if the current registry is a Tencent mirror, specify the registry explicitly):

npm run build
npm version patch
npm publish --access public --registry=https://registry.npmjs.org
git tag v0.1.0 && git push --tags

⚠️ 重要注意事項

1. 白名單申請：custom-model-og-v2 為測試模型，請先聯繫 TokenHub 產品/後台人員提交 UIN 和 Appid 取得白名單權限後，方可使用；沒有白名單的調用會返回權限錯誤。

2. API Key: please go to TokenHub console Create a dedicated Key for your model; the Key is shown only once at creation, so save it safely.

3. 計費: TokenHub 按 Token 計費（約 10 元 / 百萬 tokens），每小時結算。n>1 或多張輸入圖片會显著增加消耗，請商務人員盡早為客戶申請折扣。

4. 費用公式（人民幣）：文本輸入 token×3.35 + 文本緩存輸入×0.8375 + 圖輸入圖×5.36 + 圖像緩存輸入×1.34 + 輸出圖片×20.1 = 單次任務 token 消耗（換算係數與匯率相關，當前係數為 6.7）。

License

Apache-2.0