PicX MCP Server

一个基于 FastMCP 4 的服务器，通过无会话 Streamable HTTP 向任何 MCP 客户端提供 PicX Studio 的图像和视频生成能力。

托管端点： https://mcp.picxstudio.com/mcp ⚠️ 尚未部署。 该服务目前仅在本地运行；生产托管已在计划中（参见 PLAN-MCP Phase 6）。

为什么选择 FastMCP 4

FastMCP 4 的主题是*“无状态传输，但应用代码不必无状态”*。它所针对的协议修订版本——2026-07-28——完全移除了会话亲和性。普通负载均衡器后面的任何副本都可以处理任何请求。无需粘性会话，无需转发 cookie，请求之间不共享内存状态。

这对我们来说不是可选项：MCP 客户端（Cursor、Claude Code）在内部使用 fetch()，并且不转发 Set-Cookie 头，因此无论负载均衡器如何配置，粘性会话负载均衡都无法工作。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。

认证

两条认证通道，一个执行点：

两条路径汇聚到同一个 /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

这会启动一个轮询代理后面的两个服务器副本，外加一个 Valkey 实例。验证该架构的测试如下：

1. 在副本 A 上发起一个交互式工具调用（触发 InputRequiredResult）

2. 继续该交互——请求落在副本 B 上

3. 调用成功，因为 REQUEST_STATE_KEY 是共享的

如果未设置 REQUEST_STATE_KEY（或各副本之间不一致），交互轮次将因状态验证错误而失败。这是有意为之——它让配置错误以明显的方式暴露，而不是悄然出错。

环境变量

坦诚的限制

• 每次生成都消耗积分。 该服务器不会绕过定价——这正是重点所在。

• 每会话上限（默认 2000 积分） 限制了提示注入导致的积分流失。这与账户每日 13,000 积分上限相互独立。

• 确认提示：在消耗积分之前，若超过阈值（默认 200 积分），会要求确认。

• 不支持离线/本地生成。 所有生成都通过网络调用 PicX API。

• 视频是异步的。 即使 task=True 隐藏了轮询，生成仍需要数分钟——代理必须等待。

• 速率限制属于 API，而非该服务器：默认 60 次/分钟、10K 次/天。MCP 服务器不会增加额外限制。

• 该服务器处于测试阶段。 FastMCP 4 为 4.0.0b3。请对不完善之处有所预期。

许可证

MIT