PicX MCP Server

A FastMCP 4 サーバーであり、PicX Studio の画像・動画生成を、セッションレス Streamable HTTP を介してあらゆる MCP クライアントに公開します。

ホステッドエンドポイント: https://mcp.picxstudio.com/mcp ⚠️ まだデプロイされていません。 現在、このサービスはローカルで動作しており、本番ホスティングは予定されています（PLAN-MCP Phase 6 を参照）。

FastMCP 4 を選ぶ理由

FastMCP 4 のテーマは 「ステートレスなアプリケーションコードを伴わないステートレストランスポート」 です。それが対象とするプロトコルリビジョン 2026-07-28 は、セッションアフィニティを完全に廃止します。通常のロードバランサーの背後にあるどのレプリカでも、任意のリクエストを処理できます。スティッキーセッションも、クッキー転送も、リクエスト間の共有インメモリ状態もありません。

これは私たちにとって任意の選択肢ではありません。MCP クライアント（Cursor、Claude Code）は内部で fetch() を使用し、Set-Cookie ヘッダーを転送しないため、LB の設定に関係なくスティッキーセッションのロードバランシングは機能しません。FastMCP 4 の stateless_http=True モードだけが、水平スケーリングへの実行可能な道です。

FastMCP 4 はまた、単一のデプロイから両方のプロトコル世代（レガシー SSE と最新の Streamable HTTP）をネゴシエーションできるため、古いクライアントも取り残されません。

Related MCP server: LLM Wiki Streamable HTTP MCP Server

ツールステータス

既知の制限事項

• 動画モード: text、image、reference モードのみが公開されています。frames、extend、lipsync、edit モードには、専用のバリデーションなしではパラメータスキーマが安全にシリアライズできないフィールドが必要です。これらを公開すると、API から紛らわしい 422 エラーが返ることになります。

• picx_list_generations: 実装済みで有効化できる状態ですが、バックエンドが GET /v1/generations を提供するまでブロックされています。

• ティア制限: アカウントエンドポイントが公開するまで、ティアごとのレート制限と日次上限の表示が利用できない場合があります。

• OAuth: まだ接続されていません（Phase 5）。現在は API キー認証が機能します。

クイックスタート

# Clone and install
git clone https://github.com/Type-Think-AI/picx-mcp.git
cd picx-mcp
uv sync

# Configure
cp .env.example .env
# Edit .env — set PICX_API_KEY to your key from https://ai.picxstudio.com/api

# Run
python -m picx_mcp

サーバーは http://localhost:8000 で起動します。MCP エンドポイントは /mcp、ヘルスチェックは /health です。

クライアント設定

Claude Desktop

{
  "mcpServers": {
    "picx": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer pxsk_your_api_key_here"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "picx": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${PICX_API_KEY}"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "picx": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${PICX_API_KEY}"
      }
    }
  }
}

VS Code (Copilot)

{
  "mcp": {
    "servers": {
      "picx": {
        "type": "http",
        "url": "http://localhost:8000/mcp",
        "headers": {
          "Authorization": "Bearer ${PICX_API_KEY}"
        }
      }
    }
  }
}

ホステッドサービスが稼働したら、localhost:8000 を mcp.picxstudio.com に置き換えてください。

認証

2 つの認証プレーン、1 つの適用ポイント:

どちらの経路も同じ /v1 の適用処理に収束します: スコープ、レート制限、日次クレジット上限、リクエストログ記録です。弱い第二の経路は存在しません。

MCP サーバーは資格情報を一切保持しません。 呼び出し元の API キー（または解決済みセッションキー）を /v1 に転送するだけです。保存しないキーは漏洩しようがありません。

アーキテクチャ

MCP Client ──▶ PicX MCP Server ──▶ api.picxstudio.com/v1 ──▶ Provider + Storage
                 (this repo)         (owns everything below)

このサーバーは変換層です。MCP ツール呼び出しを /v1 API 呼び出しに変換し、結果をリソースリンクとして変換し直します。意図的に以下は行いません:

• モデルプロバイダーを直接呼び出しません。 プロバイダー統合は /v1 が担います。

• 金銭に関与しません。 クレジット差し引き、価格設定、割引、冪等性、プロバイダー障害時の返金は /v1 が担います。

• メディアを保存しません。 結果は恒久的な CDN URL であり、キャッシュもプロキシも行われません。

• セッション状態を保持しません。 stateless_http=True は各リクエストが自己完結することを意味します。

なぜプロバイダーを直接呼ばないのか？ /v1 はすでに次の処理を実行しています: 認証 → レート制限 → 日次上限 → スコープ確認 → 設定からの価格取得 → 割引適用 → 冪等性チェック → クレジット差し引き → プロバイダー呼び出し → 失敗時の返金 → リクエストログ記録。これらのいずれかをここで再実装すれば、いずれ乖離が生じます。そして金銭ロジックの乖離は課金バグです — 静かに進行し、恒久的に信頼を損ないます。

マルチレプリカテスト

FastMCP 4 を選んだ根幹となる主張は、セッションアフィニティが不要であることです。それをローカルで証明するには:

docker compose up --scale app=2

これにより、ラウンドロビンプロキシの背後に 2 つのサーバーレプリカと Valkey インスタンスを起動します。このアーキテクチャを検証するテスト:

1. レプリカ A で対話型ツール呼び出しを開始する（InputRequiredResult がトリガーされる）

2. 対話を再開する — リクエストはレプリカ B に到達する

3. REQUEST_STATE_KEY が共有されているため、成功する

REQUEST_STATE_KEY が設定されていない場合（またはレプリカ間で異なる場合）、対話ラウンドは状態検証エラーで失敗します。これは意図的です — 誤設定を静かに誤動作させるのではなく、明確に検出可能にするためです。

環境変数

正直な制限

• すべての生成はクレジットを消費します。 このサーバーは価格設定を迂回しません。それが意図です。

• セッションごとの上限（デフォルト 2000 クレジット） が、プロンプトインジェクションによるクレジット流出を抑止します。これはアカウントの 13,000/日 の上限とは別です。

• しきい値（デフォルト 200 クレジット）を超えると確認プロンプト が消費前に表示されます。

• オフライン/ローカル生成はありません。 すべての生成はネットワーク経由で PicX API に送信されます。

• 動画は非同期です。 task=True がポーリングを隠蔽しても、生成には数分かかります。エージェントは待つ必要があります。

• レート制限は API 側のものです。 このサーバーのものではありません: デフォルトで 60 req/min、10K req/day。MCP サーバーは追加の制限を設けません。

• サーバーはベータ版です。 FastMCP 4 は 4.0.0b3 です。未完成な部分があることを想定してください。

ライセンス

MIT