PicX MCP Server

Сервер на базе FastMCP 4, предоставляющий генерацию изображений и видео PicX Studio любому MCP-клиенту через Streamable HTTP без сессий.

Размещённый endpoint: https://mcp.picxstudio.com/mcp ⚠️ Ещё не развёрнут. Сейчас сервис работает локально; продакшен-хостинг запланирован (см. PLAN-MCP Phase 6).

Почему FastMCP 4

Тема FastMCP 4 — «stateless-транспорт без stateless-кода приложения». Целевая ревизия протокола — 2026-07-28 — полностью устраняет привязку к сессии. Любая реплика за обычным балансировщиком нагрузки может обслужить любой запрос. Никаких sticky-сессий, пересылки cookie или общего состояния в памяти между запросами.

Для нас это не опционально: MCP-клиенты (Cursor, Claude Code) внутри используют fetch() и не пересылают заголовки Set-Cookie, поэтому балансировка со sticky-сессиями не заработает независимо от конфигурации LB. Режим stateless_http=True в FastMCP 4 — единственный жизнеспособный путь к горизонтальному масштабированию.

FastMCP 4 также согласует обе эпохи протокола (устаревший SSE и современный Streamable HTTP) из одного развёртывания, так что старые клиенты не остаются за бортом.

Related MCP server: LLM Wiki Streamable HTTP MCP Server

Статус инструментов

Известные ограничения

• Режимы видео: Доступны только режимы text, image и reference. Режимы frames, extend, lipsync и edit требуют полей, которые схема параметров не может безопасно сериализовать без отдельной валидации — их открытие вызывало бы непонятные ошибки 422 от API.

• picx_list_generations: Реализован и готов к активации, но заблокирован до выхода GET /v1/generations на бэкенде.

• Лимиты тарифов: Видимость rate limit и дневного лимита для каждого тарифа может быть недоступна, пока их не начнёт отдавать endpoint аккаунта.

• 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 endpoint находится на /mcp, health — на /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, как только размещённый сервис заработает.

Аутентификация

Два механизма аутентификации, одна точка применения политик:

Оба пути сходятся в одной точке применения политик /v1: скоупы, rate limits, дневной лимит кредитов, логирование запросов. Второго, более слабого пути не существует.

MCP-сервер никогда не хранит учётные данные. Он пересылает API-ключ вызывающей стороны (или полученный ключ сессии) в /v1. Ключ, который он никогда не хранит, невозможно утечь.

Архитектура

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

Этот сервер — трансляционный слой. Он преобразует вызовы инструментов MCP в API-вызовы /v1 и переводит результаты обратно в ссылки на ресурсы. Он намеренно НЕ:

• Обращается к провайдерам моделей напрямую. Интеграция с провайдерами — зона ответственности /v1.

• Касается денег. /v1 отвечает за списание кредитов, ценообразование, скидки, идемпотентность и возврат при сбое провайдера.

• Хранит медиа. Результаты — это постоянные CDN-URL; ничего не кэшируется и не проксируется.

• Поддерживает состояние сессии. stateless_http=True означает, что каждый запрос самодостаточен.

Почему не обращаться к провайдерам напрямую? /v1 уже выполняет: аутентификацию → rate limit → дневной лимит → проверку скоупов → цену из конфигурации → применение скидки → проверку идемпотентности → списание кредитов → вызов провайдера → возврат при сбое → запись в журнал запросов. Повторная реализация любого из этих шагов здесь со временем разойдётся, а расхождение в денежной логике — это баг биллинга: тихий, навсегда подрывающий доверие.

Тестирование с несколькими репликами

Вся суть выбора FastMCP 4 в том, что привязка к сессии не требуется. Чтобы доказать это локально:

docker compose up --scale app=2

Это запускает две реплики сервера за round-robin прокси, а также экземпляр Valkey. Тест, подтверждающий архитектуру:

1. Запустите интерактивный вызов инструмента на реплике A (вызывает InputRequiredResult)

2. Возобновите взаимодействие — запрос попадает на реплику B

3. Запрос успешен, потому что REQUEST_STATE_KEY общий

Если REQUEST_STATE_KEY не задан (или различается между репликами), интерактивные раунды будут завершаться ошибкой валидации состояния. Это намеренно — неверная конфигурация становится явной, а не тихо неверной.

Переменные окружения

Честные лимиты

• Каждая генерация стоит кредитов. Этот сервер не обходит тарификацию — в этом суть.

• Потолок на сессию (по умолчанию 2000 кредитов) ограничивает слив кредитов через prompt-инъекции. Это отдельно от дневного лимита аккаунта (13 000/день).

• Подтверждающий запрос выше порога (по умолчанию 200 кредитов) перед тратой.

• Нет офлайн/локальной генерации. Вся генерация обращается к PicX API по сети.

• Видео асинхронно. Даже если task=True скрывает опрос, генерация занимает минуты — агенту придётся ждать.

• Rate limits принадлежат API, а не этому серверу: 60 запросов/мин, 10K запросов/день по умолчанию. MCP-сервер не добавляет дополнительных лимитов.

• Сервер находится в бете. FastMCP 4 — это 4.0.0b3. Возможны шероховатости.

Лицензия

MIT