PicX MCP Server

Un servidor FastMCP 4 que expone la generación de imágenes y vídeos de PicX Studio a cualquier cliente MCP a través de Streamable HTTP sin sesiones.

Endpoint alojado: https://mcp.picxstudio.com/mcp ⚠️ Aún no está desplegado. El servicio se ejecuta localmente hoy; el alojamiento de producción está previsto (ver PLAN-MCP Phase 6).

Por qué FastMCP 4

El tema de FastMCP 4 es "transporte sin estado sin código de aplicación sin estado." La revisión de protocolo a la que apunta — 2026-07-28 — elimina por completo la afinidad de sesión. Cualquier réplica detrás de un balanceador de carga ordinario puede atender cualquier solicitud. Sin sticky sessions, sin reenvío de cookies, sin estado compartido en memoria entre solicitudes.

Esto no es opcional para nosotros: los clientes MCP (Cursor, Claude Code) usan fetch() internamente y no reenvían las cabeceras Set-Cookie, por lo que el balanceo de carga con sticky sessions no puede funcionar independientemente de la configuración del LB. El modo stateless_http=True de FastMCP 4 es la única vía viable para el escalado horizontal.

FastMCP 4 también negocia ambas eras de protocolo (SSE legacy y Streamable HTTP moderno) desde un único despliegue, por lo que los clientes antiguos no quedan abandonados.

Related MCP server: LLM Wiki Streamable HTTP MCP Server

Estado de las herramientas

Limitaciones conocidas

• Modos de vídeo: Solo se exponen los modos text, image y reference. Los modos frames, extend, lipsync y edit requieren campos que el esquema de parámetros no puede serializar de forma segura sin una validación dedicada — exponerlos produciría errores 422 confusos de la API.

• picx_list_generations: Implementada y lista para activarse, pero bloqueada a la espera de que el backend publique GET /v1/generations.

• Límites por nivel: Es posible que el límite de tasa por nivel y el tope diario no estén disponibles hasta que el endpoint de cuenta los exponga.

• OAuth: Aún no integrado (Fase 5). La autenticación con clave de API funciona hoy.

Inicio rápido

# 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

El servidor arranca en http://localhost:8000. El endpoint de MCP está en /mcp, y el de salud en /health.

Configuración del cliente

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

Reemplace localhost:8000 por mcp.picxstudio.com cuando el servicio alojado esté operativo.

Autenticación

Dos planos de autenticación, un único punto de aplicación:

Ambos caminos convergen en el mismo punto de aplicación /v1: scopes, límites de tasa, tope de crédito diario, registro de solicitudes. No existe un segundo camino más débil.

El servidor MCP nunca posee una credencial. Reenvía la clave de API del llamante (o la clave de sesión resuelta) a /v1. Una clave que nunca almacena es una clave que no puede filtrar.

Arquitectura

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

Este servidor es una capa de traducción. Convierte las llamadas a herramientas MCP en llamadas a la API /v1 y traduce los resultados a enlaces de recursos. Intencionadamente, NO:

• Llamar directamente a cualquier proveedor de modelos. /v1 es el propietario de la integración con el proveedor.

• Tocar el dinero. /v1 es el responsable de la deducción de créditos, los precios, los descuentos, la idempotencia y el reembolso en caso de fallo del proveedor.

• Almacenar multimedia. Los resultados son URLs CDN permanentes; nada se guarda en caché ni se sirve a través de un proxy.

• Mantener estado de sesión. stateless_http=True significa que cada solicitud es autocontenida.

¿Por qué no llamar a los proveedores directamente? /v1 ya realiza: autenticación → límite de tasa → tope diario → verificación de alcance → precio desde configuración → aplicar descuento → comprobación de idempotencia → deducir créditos → llamar al proveedor → reembolsar en caso de fallo → escribir el registro de solicitudes. Reimplementar cualquiera de eso aquí acabaría divergiendo, y una divergencia en la lógica del dinero es un bug de facturación — silencioso y que erosiona la confianza de forma permanente.

Pruebas con múltiples réplicas

La tesis principal de elegir FastMCP 4 es que no se requiere afinidad de sesión. Para demostrarlo localmente:

docker compose up --scale app=2

Esto inicia dos réplicas del servidor detrás de un proxy round-robin y una instancia de Valkey. La prueba que valida la arquitectura:

1. Inicie una llamada de herramienta interactiva en la réplica A (dispara InputRequiredResult)

2. Reanude la interacción — la solicitud llega a la réplica B

3. Tiene éxito, porque REQUEST_STATE_KEY es compartida

Si REQUEST_STATE_KEY no está definida (o difiere entre réplicas), las rondas interactivas fallarán con un error de validación de estado. Esto es intencional — hace que una configuración incorrecta sea evidente en lugar de fallar de forma sutil.

Variables de entorno

Límites honestos

• Cada generación cuesta créditos. Este servidor no elude los precios — ese es el punto.

• El tope por sesión (por defecto 2000 créditos) acota el drenaje de créditos inducido por inyección de prompt. Esto es independiente del tope de 13 000/día de la cuenta.

• Solicitud de confirmación por encima del umbral (por defecto 200 créditos) antes de gastar.

• No hay generación local ni sin conexión. Toda generación se realiza mediante la API de PicX a través de la red.

• El vídeo es asíncrono. Incluso con task=True ocultando el polling, la generación tarda minutos — un agente debe esperar.

• Los límites de tasa son de la API, no de este servidor: 60 req/min, 10K req/día por defecto. El servidor MCP no añade ningún límite adicional.

• El servidor está en beta. FastMCP 4 es 4.0.0b3. Espere asperezas.

Licencia

MIT