Imagine MCP

프로덕션 지향 원격 MCP 서비스로, xAI 이미지 생성, 이미지 편집, 비디오 생성, 텍스트 음성 변환(TTS)을 제공합니다. MCP TypeScript SDK의 Streamable HTTP 핸들러를 사용하여 api/mcp.ts에 하나의 Vercel Function을 노출합니다.

모든 과금 대상 결과물은 xAI에서 변경 불가능한(immutable) Vercel Blob 객체로 복사됩니다. 클라이언트는 임시 xAI URL이 아닌 영구적인 공개 Blob URL을 받습니다. 테스트는 모의(mocked) HTTP와 인메모리 저장소만 사용하며 외부 호출이나 과금 호출을 하지 않습니다.

이 서비스는 overnight 크루의 렌더 경계(render boundary)로 설계되었습니다. 해당 크루의 Render 봇만 이 MCP 연결을 받아야 합니다.

도구

이미지 모델: grok-imagine-image-2.0, grok-imagine-image, grok-imagine-image-quality. 비디어 모델: grok-imagine-video-1.5, grok-imagine-video.

기본값은 grok-imagine-image-2.0, grok-imagine-video-1.5, 음성 eve, 언어 auto입니다. 도구 스키마는 위 계약에 문서화된 모델 ID만 허용하므로, 새로 도입된 더 높은 가격의 모델이 예약 테이블을 우회할 수 없습니다. API가 보고한 사용량이 있으면 추정치를 대체합니다.

Related MCP server: Sisif AI MCP Server

아키텍처

flowchart LR
    B["Grok Bot<br/>Render only"] -->|x-mcp-secret| M["MCP endpoint<br/>auth + spend reserve"]
    M --> X["xAI API<br/>image / video / TTS"]
    X --> P[("Public Blob store<br/>persistent media")]
    X --> L[("Private Blob store<br/>append-only ledger")]
    P --> B

• api/mcp.ts — Vercel fetch 진입점.

• src/server.ts — 인증, Origin 정책, MCP 등록, 런타임 연결.

• src/xai.ts — xAI REST 클라이언트, 응답 검증, 비디오 폴링 및 제한된 재시도.

• src/tools/ — MCP 도구별 모듈 하나씩.

• src/media.ts — 제한된 미디어 다운로드 및 변경 불가능한 영속화.

• src/store.ts — Vercel Blob 및 인메모리 어댑터. 프로덕션에서는 공개 미디어 저장소 하나와 비공개 원장 저장소 하나를 연결.

• src/ledger.ts — 추가 전용(append-only) 일일 예약/조정 이벤트.

• src/pricing.ts — 공개된 폴백 요금과 사용량 틱 변환.

• src/config.ts — fail-closed 환경 검증.

MCP 핸들러는 요청별 최신 MCP 트래픽과 SDK의 무상태(stateless) 레거시 Streamable HTTP 폴백을 지원합니다. 함수 인스턴스에는 세션 상태가 저장되지 않습니다.

환경

.env.example를 시크릿 매니저나 Vercel 프로젝트 설정에 복사하세요. .env는 커밋하지 마세요.

필수:

• MCP_SHARED_SECRET: 32–4096자. 모든 실제 MCP GET, POST, DELETE 요청은 이를 x-mcp-secret으로 보내야 합니다.

• XAI_API_KEY: 서버 측 xAI 키.

• DAILY_SPEND_LIMIT_USD: 양수 값의 UTC 일일 xAI 생성 상한선.

• 반환 미디어용 공개 Vercel Blob 저장소:

  • MEDIA_BLOB_READ_WRITE_TOKEN, 또는

  • MEDIA_BLOB_STORE_ID와 VERCEL_OIDC_TOKEN.

• 지출 원장 이벤트용 별도의 비공개 Vercel Blob 저장소:

  • LEDGER_BLOB_READ_WRITE_TOKEN, 또는

  • LEDGER_BLOB_STORE_ID와 VERCEL_OIDC_TOKEN.

Vercel은 저장소 생성 시 공개/비공개 모드를 고정하므로 하나의 저장소가 두 역할을 모두 수행할 수 없습니다. 이미 알려진 동일한 토큰이나 저장소 ID를 재사용하면 구성 검증에 실패합니다. 더 이상 사용되지 않는 BLOB_TOKEN 및 접두사가 없는 BLOB_READ_WRITE_TOKEN 변수는 사용되지 않습니다.

선택 사항:

• MCP_ALLOWED_ORIGINS: 쉼표로 구분된 정확한 HTTP(S) 브라우저 Origin 목록.

• MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, MAX_AUDIO_BYTES: 양수 바이트 제한. 기본값은 25 MiB, 128 MiB, 50 MiB입니다.

값을 출력하거나 네트워크 요청을 하지 않고 구성을 검증합니다:

npm run doctor

설치 및 확인

Node.js 20 이상:

./init.sh
./test.sh

이에 해당하는 npm 명령:

npm ci
npm run typecheck
npm test
npm run build

stop.sh는 의도적으로 아무 작업도 수해하지 않는 no-op입니다. 이 저장소는 백그라운드 데몬을 수해하지 않기 때문입니다. 프로덕션 함수 수명 주기는 Vercel이 관리합니다.

Vercel에 배포

1. 이 저장소에서 Vercel 프로젝트를 생성합니다.

2. Vercel Blob 저장소 두 개를 연결합니다. 미디어용 공개 저장소 하나와 원장 이벤트용 비공개 저장소 하나입니다. 환겨 변수 접두사 MEDIA와 LEDGER를 지적하거나 위의 명시적 변수를 구성합니다.

3. 대상 배포 환겨에 대해 위의 모둔 필수 환겨 변수를 구성합니다.

4. api/mcp.ts를 /api/mcp에 유지합니다. vercel.json은 800초 함수를 요청하며, 이는 Vercel Pro 또는 Enterprise가 필요합니다. 이는 10분 xAI 비디어 폴링 마감 기한과 응답 처리를 포합합니다.

5. 평소의 검토 워크플로를 통해 배포합니다.

이 저장소는 배포 명령을 수해하지 않습니다. Vercel Hobby는 현재 함수를 300초로 제한하므로 이미지/TTS 사용에는 적합하지만 이 동기식 generte_video 계약을 안정적으로 충족할 수 없습니다. Hobby 배포를 비디어 지원 가능 상태로 소개하지 마세요.

Vercel Host 및 Origin 동작

이 서비스는 Host 허용 목록을 하드코딩하지 않습니다. Vercel 배포, 프리, 사용자 지적 도메인 호스트 이름은 독립적으로 변겨되며, Vercel은 함수를 호출하기 전에 라우팅과 TLS를 검증합니다. MCP_ALLOWED_ORIGINS는 Vercel 대상 호스트 이름이 아니라 브라우저의 Origin 헤더를 제어합니다.

브라우저가 아닌 MCP 클라이언트는 일반적으로 Origin을 생략하며 시크릿 인증 후 수락됩니다. Origin을 보내는 요청은 해당 정확한 origin이 구성되지 않은 한 거부됩니다. 이로써 브라우저 접근은 옵트인(opt-in) 방식이 됩니다. 허용된 CORS 사전 요청(preflight)은 MCP나 xAI를 호출하지 않으며, 이후의 MCP 요청에도 여전히 x-mcp-secret이 필요합니다.

연결 및 스모크 테스트

시크릿을 명령 기록에 남기지 않고 엘 변수를 설정합니다:

export MCP_URL='https://your-project.vercel.app/api/mcp'
read -s MCP_SHARED_SECRET
export MCP_SHARED_SECRET

Streamable HTTP 초기화 스모크 요청:

curl --fail-with-body --no-buffer \
  -X POST "$MCP_URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "x-mcp-secret: $MCP_SHARED_SECRET" \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-06-18",
      "capabilities":{},
      "clientInfo":{"name":"curl-smoke","version":"1.0.0"}
    }
  }'

인증되지 않은 검사는 도구를 호출하지 않고 401을 반환해야 합니다:

curl -i -X POST "$MCP_URL" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"ping"}'

MCP Inspector의 경우:

npx @modelcontextprotocol/inspector

Inspector에서 Streamable HTTP를 선택하고 $MCP_URL을 입력한 다음 사용자 지정 헤더 x-mcp-secret을 추가합니다. Inspector가 브라우저 UI에서 직접 요청을 보내는 경우 해당 UI의 정확한 origin을 MCP_ALLOWED_ORIGINS에 추가하세요. 로컬 프록시를 사용하는 경우 일반적으로 브라우저 Origin이 서비스에 도달하지 않습니다. 도구를 호출하기 전에 먼저 도구 목록을 조회하세요. 실제 xAI 키로 구성된 경우 도구 호출은 과금됩니다.

원격 헤더를 지원하는 MCP 클라이언트는 동일한 URL과 자체 환경 또는 시크릿 저장소에서 가져온 시크릿 헤더로 구성해야 합니다. xAI API 키를 MCP 클라이언트에 붙여넣지 마세요. 클라이언트 구성에는 공유 MCP 시크릿만 있어야 합니다.

보안 참고 사항

• 공유 시크릿 비교는 두 값을 해시하고 crypto.timingSafeEual을 사용합니다. 누락되거나 잘못된 인증은 fail-closed로 처리됩니다. 시크릿, 요청 헤더, 업스트림 본문은 애플리케션 로그에 출력되지 않습니다.

• 이 서비스가 반환하는 미디어는 의도적으로 공개됩니다. 민감한 콘텐츠를 생성하지 마세요. 별도의 비공개 원장 저장소의 예약 이벤트는 제출된 프롬프트/텍스트를 도구, 모델, 추정치, 타임스탬프와 함께 보관하며, 조정 이벤트는 실제 비용을 추가합니다. 프롬프트에 자격 증명을 넣지 마세요.

• 호출자가 제공한 image_url 값은 JSON으로 xAI에 전달되며 이 서비스가 가져오지 않습니다.

• 이 서비스는 성공한 xAI 응답에서 얻은 URL만 가져옵니다. HTTPS를 요구하고, 명백한 로컬/비공개 리터럴 호스트를 거부하며, 리다이렉트를 비활성화하고, 미디어 MIME 유형을 검증하며, 헤더 및 스트리밍 크기 제한을 적요합니다. xAI가 반환한 서명된 URL의 DNS 소유권은 여전히 업스트림 신뢰 경계의 일부입니다.

• DAILY_SPEND_LIMIT_USD는 항상 필수입니다. 예약 동작과 문서화된 서버리스 동시성 한도는 COST.md를 참조하세요.

• Blob 저장소, 이그레스(egress), Vercel 실행 비용은 xAI가 보고하지 않으며 xAI 생성 상한선 밖에 있습니다.

테스트 정책

모든 테스트는 모의(mocked) fetch 구현과 인메모리 객체 저장소를 주입합니다. 인증, 가격 책정 및 사용량 틱, 이미지 요청 형태, 비디오 폴링/재시도/타임아웃, 바이너리 TTS, 미디어 검증, Blob 어댑터 옵션, 지출 상한 동작을 다룹니다. 어떤 테스트도 XAI_API_KEY를 읽지 않고, xAI에 접촉하지 않으며, Vercel Blob에 쓰지 않고, 배포하지 않으며, 비용을 발생시키지 않습니다.

취약점은 공개 이슈가 아니라 SECURITY.md의 비공개 프로세스를 통해 신고하세요.

라이선스

MIT. 생성된 미디어에는 제공업체 약관과 소스 자료에 존해하는 모든 권리가 계속 적요됩니다.