TokenHub AIGC Model — MCP Server

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: MCP OpenAI Image Generation Server

빠른 시작

방법 1: stdio(로컬 연결, 우선 권장)

MCP 클라이언트 구성에 명령 형식 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」**을 입력해 보세요.

방법 2: Streamable HTTP(원격 배포)

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

환경 변수

사이트 도메인

TokenHub는 지역별로 사이트를 분산 배포하므로, 사이트가 다른 고객은 해당 도메인을 입력해야 합니다. 기본값은 국내 거점 · 广州입니다:

| 사이트 | 도메인(예시) | | ------------------------ | ------------------------------------------------------------ | | | 국내 거점 · 广州 | https://tokenhub.tencentmaas.com(기본값) | | 기타 거점(국내 업데이트 모두 / 국제 거점 广州· Singapore·美西 등) | TokenHub 영업/기술 지원에 연락하여 해당 도메인을 받아 TOKENHUB_BASE_URL에 입력하거나 단일 호출 시 base_url로 전달하세요 |

도구 매개변수 설명

tokenhub_generate_image(텍스트-이미지 생성)

tokenhub_edit_image(이미지-이미지 생성/편집)

위 표의 대부분 매개변수를 공유하고, 추가로:

반환 값: 이미지 URL 리스트, request_id(문제 조용), total_tokens(과금용); response_format=b64_json이면 base64 이미지 블록이 포함되어 직접 표시할 수 있습니다.

오류 처리

• 도구 호출 실패 시 isError: true를 반환하며, 오류 정보에는 status, ・서 오류 code, request_id가 포함됩니다.

• 권한/요청 빈도 제한/매개변수 오류가 발생하면, request_id를 보존하여 TokenHub 기술 지원에 제출하세요.

• TOKENHUB_API_KEY가 설정되지 않으면 도구 호출 시 명확한 안내를 반환합니다(server는 정상적으로 시작할 수 있습니다).

HTTP 모드 배포(원격)

# 本地启动（默认 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: 상태 체크

공용 망에 배포할 때 반드시 다음을 준수하세요:

1. MCP_AUTH_TOKEN을 설정하거나, 전방 게이트웨이/리버스 프록시(예: EdgeOne, CLB, Nginx)에서 인증을 수행하세요.

2. HTTPS를 사용하세요.

3. 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

⚠️ 중요 안내

1. 고급(White List): custom-model-og-v2는 테스트 모델이며, TokenHub 제품/기술 인력에게 UIN과 Appid를 제출하여 허가를 받아야 사용할 수 있습니다. 허가를 받지 않고 호출하면 오류가 반환됩니다.

2. API Key: TokenHub Console에서 해당 모델 전용 Key를 만들어 주세요. Key는 생성 시 한 번만 표시되므로 안전하게 보관하세요.

3. 과금: TokenHub는 Token 단위로 과금하며(약 10원/백만 Token), 시간 단위로 결제됩니다. n>1 설정 또는 입력 이미지가 여러 장이면 Token Token 소모가 크게 증가하므로 사업 담당자는 고객을 위해 할인을 미리 신청하세요.

4. 과금 공식(인민폐): 입력 텍스트 token×3.35 + 캐시된 텍스트 입력×0.8375 + image 입력×5.36 + 캐시 이미지 입력×1.34 + 출력 이미지×20.1 = 단일 태스크 token 소모(환산 계수는 환율에 따라 다르며, 현재 계수 6.7).

License

Anonymous-2.0