imageat

@imageat/mcp

ImageAT 用の Model Context Protocol（MCP）サーバーです。MCP クライアント（Claude Desktop、Cursor など）で画像生成、動画生成、ImageAT の画像編集機能を利用するツールを提供します。料金は ImageAT アカウントに請求されます。

料金について。 有効なサブスクリプションをお持ちの場合、MCP リクエストでは、imageat.com で利用する場合と 同じ料金でウェブサイトのクレジットが消費されます。同じ生成であれば、どちらの方法でも費用は同じです。クレジットが なくなった場合（またはサブスクリプションをお持ちでない場合）、リクエスト料金はプリペイド API 残高から API 料金表に基づいて請求されます。クライアントの接続には、いずれか一方が必要です。

ツール

ツール	機能
imageat_generate_image	テキストから画像／画像から画像を生成します。CDN の画像 URL を返します。
imageat_generate_video	テキストから動画／画像から動画を生成します。CDN の mp4 URL を返します。
imageat_generate_video_task	tasks/get と tasks/result を使う、実験的な MCP Tasks 版です。
imageat_check_video_status	非同期の動画生成が完了するまで状態を確認します。
imageat_ask_gemini_argon	Google の Gemini 4 Argon に質問します（画像 URL は任意、Google 検索／マップによるグラウンディングに対応）。テキスト形式の回答を返します。
imageat_check_credits	現在のプリペイド API 残高（USD）を確認します。
imageat_game_guide	ブラウザーでプレイ可能なゲームを作る際の最初のステップです。ワークフロー、実行時のルール、キット API（Phaser 2D／three.js 3D）を説明します。無料です。
imageat_search_game_models	ゲームに使える 2,700 以上の 3D ライブラリモデルを検索します。アニメーション付きの library_key を返します。無料です。
imageat_generate_game_asset	スプライト、背景、テクスチャ、ロゴ、または AI 生成の 3D hero_model など、ゲーム用アセットを 1 つ生成します。asset_id を返します。
imageat_publish_game	ゲームコードを確認し、エンジンとアセットをまとめて、共有可能なプレイリンクを返します。
imageat_update_game	ゲームのコードを新しいバージョンとして公開します（リンクは同じです）。無料です。
imageat_edit_<feature>	編集機能ごとに 1 つのツールを起動時に動的に取得します。例：imageat_edit_remove-background、imageat_edit_object-eraser、imageat_edit_relight、imageat_edit_virtual-try-on、imageat_edit_city-teleport、imageat_edit_ai-edit-pro。新しい機能は自動的に表示されます。

起動時に機能カタログにアクセスできない場合は、汎用の imageat_edit_image ツールが 1 つ代わりに登録されます （feature ID パラメーターを指定）。その場合もサーバーは引き続き動作します。

ツールの結果には、読みやすいテキストと型付きの structuredContent の両方が含まれます。ツールのスキーマ、安全性 アノテーション、出力スキーマにより、エージェントクライアントは呼び出しを検証し、読み取り専用ツールを区別できます。

リソースとプロンプト

• imageat://account/credits — 現在のプリペイド API 残高（USD）。
• imageat://edit/features — 編集機能の最新カタログ。
• imageat://models/images と imageat://models/videos — メディアモデルのカタログ。
• imageat://generations/recent — アカウントで最近生成した 10 件。
• create-product-visual — 再利用可能な商品画像ワークフローのプロンプト。
• animate-image — 再利用可能な画像から動画へのワークフローのプロンプト。
• create-social-campaign、generate-and-upscale、create-creative-variants — キャンペーン用ワークフロー。

セットアップ

1. ImageAT の Projects ページで API キーを作成します（iat_live_ で始まります）。
2. MCP クライアントの設定にサーバーを追加します。

{
  "mcpServers": {
    "imageat": {
      "command": "npx",
      "args": ["-y", "@imageat/mcp"],
      "env": {
        "IMAGEAT_API_KEY": "iat_live_xxxxxxxxxxxx"
      }
    }
  }
}

3. クライアントを再起動します。imageat_* ツールが利用可能になります。

環境変数

変数	必須	デフォルト	備考
IMAGEAT_API_KEY	はい	—	お使いの iat_live_ キーです。
IMAGEAT_BASE_URL	いいえ	https://imageat.com	/api/v1/* 生成エンドポイントを提供するウェブアプリです。ローカル開発では http://localhost:3000 を指定します。

リモートサーバー（claude.ai、ChatGPT、その他のウェブクライアント）

上記の npx によるセットアップは stdio です。これはローカルプロセスを起動するデスクトップアプリ（Claude Desktop、Cursor、Claude Code）で動作します。 一方、claude.ai や chatgpt.com などのブラウザクライアントは、Streamable HTTP 経由でリモート MCP エンドポイントに接続します。

同じツールは dist/http.js によって HTTP 経由で提供されます。各 MCP セッションでは、ユーザー自身の API キーが Authorization: Bearer iat_live_... ヘッダーを介して渡されるため（複数ユーザー対応）、これをホスト型コネクターの接続先に指定します。

# Run the remote server locally against a local ImageAT instance:
IMAGEAT_BASE_URL=http://localhost:3000 PORT=8787 npm run start:http
# MCP endpoint: http://localhost:8787/mcp   ·   health: /health

付属の Dockerfile を使って（たとえば Dokploy 上で mcp.imageat.com として）デプロイし、カスタムコネクターとして追加します。

• claude.ai — Settings → Connectors → Add custom connector → URL https://mcp.imageat.com/mcp。
• ChatGPT — Connectors / Developer mode → サーバー URL https://mcp.imageat.com/mcp を追加します。

ブラウザクライアントでは OAuth フローが実行されます。コネクターを追加すると、このサーバーが提供する同意ページが開き、そこで iat_live_ キーを貼り付けます。クライアントには、そのキーに紐付けられた有効期間の短いアクセストークンが渡されます。ブラウザ以外のクライアント（mcp-remote、MCP Inspector、curl）では、引き続き iat_live_ キーを Authorization: Bearer iat_live_... として直接送信できます。

OAuth レイヤー（src/oauth.ts）は、RFC 8414/9728 のディスカバリードキュメント、RFC 7591 の動的クライアント登録、および PKCE による /authorize と /token を提供します。有効期限のあるアクセストークンとリフレッシュトークンは MCP_OAUTH_SECRET を使った AES-256-GCM で暗号化されます。リフレッシュトークンは使用後にローテーションされ、/revoke は発行済みトークンを無効化します。OAuth トークンはクライアント ID と要求されたスコープに紐付けられます。アイドル状態の MCP セッションは自動的に回収されます。

変数	場所	デフォルト	備考
PORT	リモートのみ	8787	HTTP リッスンポート。
IMAGEAT_BASE_URL	両方	https://imageat.com	/api/v1/* を提供する上流のウェブアプリ。
MCP_OAUTH_SECRET	リモートのみ	(起動ごとにランダム)	発行する OAuth トークンを暗号化する、十分に長いランダム文字列。本番環境では必ず設定してください。設定しないと、再起動のたびにトークンが無効になります。
MCP_PUBLIC_URL	リモートのみ	リクエストから導出	公開オリジン。例：https://mcp.imageat.com。プロキシヘッダーが正しくない場合にのみ必要です。
MCP_ALLOWED_ORIGINS	リモートのみ	ChatGPT、Claude、Cursor、VS Code、GitHub、imageat	カンマ区切りのブラウザー Origin 許可リスト。Origin を含まないリクエスト（通常のサーバー間クライアント）には影響しません。
MCP_SESSION_IDLE_MS	リモートのみ	7200000	このミリ秒数にわたってアイドル状態の MCP セッションを回収します。
MCP_MAX_SESSIONS	リモートのみ	500	このプロセスが上限に達した後、新しいセッションを 503／Retry-After で拒否します。
INTERNAL_SERVICE_KEY	リモートのみ	—	ウェブアプリと共有します。「Sign in with imageat」を完了し、ChatGPT プロフィールからの呼び出しに署名して、ウェブサイトのクレジットに課金します。
OPENAI_APPS_CHALLENGE	リモートのみ	—	OpenAI プラグインの申請で取得したドメイン検証トークン。/.well-known/openai-apps-challenge でそのまま提供されます。

ChatGPT アプリのプロファイル（/chatgpt/mcp）

公開済みの ChatGPT アプリは /mcp ではなく、https://mcp.imageat.com/chatgpt/mcp に接続します。OpenAI のディレクトリ規則が他のクライアントとは異なるため、これは独立した厳選プロファイル（src/chatgpt.ts）です。

• ツールリストは固定です。 OpenAI はツールを審査し、新しいツールは承認されるまで保留するため、このプロファイルではライブの編集機能カタログからツールを構築しません。ここにツールを追加すると、審査待ちになります。
• コンテンツフィルターは厳格です。 上流への呼び出しには X-Imageat-Surface: chatgpt が含まれ、ウェブアプリはすべてのリクエストに制限付きアカウント用フィルターを適用します（lib/content-restriction.ts）。
• すべてのアカウントでウェブサイトのクレジットを使用します。 ChatGPT ユーザーはアプリ内で API 残高を購入できないため、X-Imageat-Surface-Auth（INTERNAL_SERVICE_KEY の HMAC）で署名された呼び出しでは、ウェブサイトのクレジットを消費します（lib/api-credit-mode.ts）。
• 購入を促すメッセージはありません。 エラーテキストに料金ページやチャージページへのリンクは含まれません。
• 添付された写真は、openai/fileParams を通じて { download_url, file_id } として届きます。
• 結果はウィジェットに表示されます（src/widget.ts、MCP Apps ui://imageat/media-v1.html）。動画のレンダリング中、ウィジェットは imageat_check_video_status も独自にポーリングします。

アプリの公開後は、OpenAI サポートに問い合わせない限り URL を変更できません。 OAuth は ChatGPT のクライアント ID メタデータドキュメント（https://chatgpt.com/oauth/client.json）を受け付け、認可リダイレクトで iss を返し（RFC 9207）、トークンを要求された resource に紐付けます。

ローカル開発

npm install
npm run build

# Inspect the stdio server with the official MCP Inspector against a local ImageAT instance:
IMAGEAT_API_KEY=iat_live_... IMAGEAT_BASE_URL=http://localhost:3000 \
  npx @modelcontextprotocol/inspector node dist/index.js

セキュリティに関する注意事項

本番環境では、長くランダムな値を使用し、安定した MCP_OAUTH_SECRET を設定してください。ブラウザーの Origin はデフォルトで制限されています。セルフホストのウェブクライアントを使用する場合は、MCP_ALLOWED_ORIGINS に追加してください。サーバー間で直接通信するクライアントは通常、Origin ヘッダーを省略し、iat_live_ ベアラーキーを引き続き使用できます。