PicX MCP Server

A FastMCP 4 server exposing PicX Studio image and video generation to any MCP client over sessionless Streamable HTTP.

Hosted endpoint: https://mcp.picxstudio.com/mcp ⚠️ Not deployed yet. The service runs locally today; production hosting is planned (see PLAN-MCP Phase 6).

Why FastMCP 4

FastMCP 4's theme is "stateless transport without stateless application code." The protocol revision it targets — 2026-07-28 — removes session affinity entirely. Any replica behind an ordinary load balancer can serve any request. No sticky sessions, no cookie forwarding, no shared in-memory state between requests.

This is not optional for us: MCP clients (Cursor, Claude Code) use fetch() internally and do not forward Set-Cookie headers, so sticky-session load balancing cannot work regardless of LB configuration. FastMCP 4's stateless_http=True mode is the only viable path to horizontal scaling.

FastMCP 4 also negotiates both protocol eras (legacy SSE and modern Streamable HTTP) from a single deployment, so older clients are not stranded.

Related MCP server: LLM Wiki Streamable HTTP MCP Server

Tool Status

Known limitations

• Video modes: Only text, image, and reference modes are exposed. The frames, extend, lipsync, and edit modes require fields the parameter schema cannot safely serialize without dedicated validation — exposing them would surface confusing 422 errors from the API.

• picx_list_generations: Implemented and ready to activate, but blocked on the backend shipping GET /v1/generations.

• Tier limits: Per-tier rate limit and daily cap visibility may be unavailable until the account endpoint exposes them.

• OAuth: Not yet wired (Phase 5). API-key auth works today.

Quickstart

# 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

The server starts on http://localhost:8000. The MCP endpoint is at /mcp, health at /health.

Client Configuration

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

Replace localhost:8000 with mcp.picxstudio.com once the hosted service is live.

Authentication

Two auth planes, one enforcement point:

Both paths converge on the same /v1 enforcement: scopes, rate limits, daily credit cap, request logging. There is no weaker second path.

The MCP server never holds a credential. It forwards the caller's API key (or resolved session key) to /v1. A key it never stores is a key it cannot leak.

Architecture

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

This server is a translation layer. It converts MCP tool calls into /v1 API calls and translates results back as resource links. It intentionally does NOT:

• Call any model provider directly. /v1 owns the provider integration.

• Touch money. /v1 owns credit deduction, pricing, discounts, idempotency, and refund-on-provider-failure.

• Store media. Results are permanent CDN URLs; nothing is cached or proxied.

• Maintain session state. stateless_http=True means each request is self-contained.

Why not call providers directly? /v1 already performs: auth → rate limit → daily cap → scope check → price from config → apply discount → idempotency check → deduct credits → call provider → refund on failure → write request log. Reimplementing any of that here would eventually diverge, and a divergence in money logic is a billing bug — silent, and permanently trust-eroding.

Multi-Replica Testing

The whole thesis of choosing FastMCP 4 is that no session affinity is required. To prove it locally:

docker compose up --scale app=2

This starts two server replicas behind a round-robin proxy plus a Valkey instance. The test that validates the architecture:

1. Start an interactive tool call on replica A (triggers InputRequiredResult)

2. Resume the interaction — the request lands on replica B

3. It succeeds, because REQUEST_STATE_KEY is shared

If REQUEST_STATE_KEY is not set (or differs between replicas), interactive rounds will fail with a state validation error. This is intentional — it makes misconfiguration loud rather than subtly wrong.

Environment Variables

Honest Limits

• Every generation costs credits. This server does not bypass pricing — that is the point.

• Per-session ceiling (default 2000 credits) bounds a prompt-injected credit drain. This is separate from the account's 13,000/day cap.

• Confirmation prompt above the threshold (default 200 credits) before spending.

• No offline/local generation. All generation hits the PicX API over the network.

• Video is async. Even with task=True hiding the polling, generation takes minutes — an agent must wait.

• Rate limits are the API's, not this server's: 60 req/min, 10K req/day by default. The MCP server adds no additional limit.

• The server is in beta. FastMCP 4 is 4.0.0b3. Expect rough edges.

License

MIT