PicX MCP Server

PicX Studio 이미지 및 비디오 생성을 세션리스 Streamable HTTP를 통해 모든 MCP 클라이언트에 노출하는 FastMCP 4 서버입니다.

호스팅 엔드포인트: https://mcp.picxstudio.com/mcp ⚠️ 아직 배포되지 않았습니다. 서비스는 현재 로컬에서 실행되며, 프로덕션 호스팅이 계획되어 있습니다(PLAN-MCP Phase 6 참조).

FastMCP 4를 선택한 이유

FastMCP 4의 주제는 *"스테이트리스 애플리케이션 코드 없는 스테이트리스 전송"*입니다. 이 서버가 대상으로 하는 프로토콜 개정판인 2026-07-28은 세션 선호도(session affinity)를 완전히 제거합니다. 일반 로드 밸런서 뒤에 있는 모든 복제본이 어떤 요청이든 처리할 수 있습니다. 고정 세션(sticky session)도, 쿠키 전달도, 요청 간 공유 인메모리 상태도 없습니다.

이것은 우리에게 선택 사항이 아닙니다. 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으로 바꾸세요.

인증

두 가지 인증 계층, 하나의 시행 지점:

두 경로 모두 동일한 /v1 시행 지점으로 수렴합니다: 범위, 요청률 제한, 일일 크레딧 상한, 요청 로깅. 더 약한 두 번째 경로는 없습니다.

MCP 서버는 절대 자격 증명을 보관하지 않습니다. 호출자의 API 키(또는 확인된 세션 키)를 /v1로 전달합니다. 저장하지 않는 키는 유출할 수 없는 키입니다.

아키텍처

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

이 서버는 **변환 계층(translation layer)**입니다. 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