본문으로 건너뛰기

MCP·에이전트

AI 어시스턴트가 이미지와 영상을 만들게 하세요

공식 MCP 서버를 연결하면 Claude, Cursor, Codex, VS Code 등의 어시스턴트가 실시간 모델 카탈로그, 정확한 견적, 작업 생성을 쓸 수 있습니다. 평소 말투로 요청하면 되고, 과금 전에는 반드시 확인을 거칩니다.

MCP 서버란?

MCP(Model Context Protocol)는 AI 어시스턴트에 새 도구를 붙이는 표준 방식입니다. SpicyAPI 서버를 추가하면 어시스턴트가 모델을 둘러보고, 가격을 확인하고, 이미지나 영상을 대신 만들어 줍니다.

  1. 나와 어시스턴트Claude, Cursor, Codex, VS Code…
  2. SpicyAPI MCP 서버npx로 내 컴퓨터에서 실행
  3. 이미지·영상 모델실시간 카탈로그, 정확한 가격
어떤 도구를 호출할지는 어시스턴트가 정합니다. 비용이 드는 작업은 멈추고 내 승인을 기다립니다.

이런 용도에 적합합니다

  • 코딩하면서 에셋 만들기에디터를 떠나지 않고 히어로 이미지나 제품 클립을 요청하세요.
  • 모델 탐색어떤 모델이 맞는지, 비용은 얼마나 드는지 물어보세요.
  • 손 안 대는 일괄 작업에이전트가 작업 여러 개를 만들고, 기다리고, 모아 줍니다.

요청하면 이렇게 진행됩니다

  1. 1단계실시간 카탈로그에서 알맞은 모델을 찾고 허용되는 입력을 확인합니다
  2. 2단계로컬 파일이 있으면 업로드합니다
  3. 3단계미국 달러로 정확한 견적을 확인하고 과금 전에 사용자의 승인을 요청합니다
  4. 4단계작업을 시작하고 완료될 때까지 기다린 뒤 결과 링크를 전달합니다
대화 예시
  1. 나: beach.jpg를 해 질 녘 파도가 치는 6초짜리 클립으로 만들어 줘.

  2. spicyapi_models_listspicyapi_model_get
    어시스턴트: 시작 이미지를 받는 영상 모델을 찾았어요
  3. spicyapi_upload_file
    beach.jpg를 업로드했어요
  4. spicyapi_task_quote

    미국 달러로 계산한 정확한 가격입니다. 작업을 만들까요?

  5. spicyapi_task_createspicyapi_task_wait
    완료했어요. 다운로드 링크입니다.
일반적인 대화 흐름을 보여 주는 예시입니다. 승인하기 전에는 과금되지 않습니다.

내 어시스턴트에 추가하기

모든 클라이언트는 npx로 같은 로컬 서버를 실행합니다. 사용하는 클라이언트를 고르면 알맞은 명령어나 설정 블록이 나옵니다.

{
  "mcpServers": {
    "spicyapi": {
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "YOUR_SERVER_SIDE_KEY" }
    }
  }
}

모든 MCP 클라이언트가 같은 stdio 서버를 씁니다. 해당 클라이언트의 설정 파일에 이 블록을 넣으세요.

서드파티 클라이언트는 버전에 따라 설정 형식이 바뀌기도 합니다. 여기 있는 스니펫이 맞지 않으면 해당 클라이언트의 공식 문서를 따라 주세요.

Claude를 쓰고 계신가요? Claude에서 이미지와 영상 만들기 →

제공하는 도구

읽기 전용 도구는 무료입니다. 비용이 드는 도구 두 개와 콘텐츠를 삭제하는 도구 한 개는 항상 먼저 확인을 받습니다.

무료무료, 읽기 전용12

  • spicyapi_service_status공개 상태 확인 (키 불필요)
  • spicyapi_docs_search내장 문서 검색
  • spicyapi_models_list사용 가능한 모델과 내 가격
  • spicyapi_model_get모델 하나와 입력 스키마
  • spicyapi_balance_get사용 가능, 보류, 전체 잔액
  • spicyapi_usage_get현재 키의 사용 금액
  • spicyapi_tasks_list현재 키의 최근 작업
  • spicyapi_task_get작업 하나와 준비된 결과 링크
  • spicyapi_task_wait작업이 끝날 때까지 최대 5분 대기
  • spicyapi_task_quote작업을 만들지 않고 요청의 정확한 가격 계산
  • spicyapi_upload_file입력으로 쓸 로컬 파일 업로드
  • spicyapi_download_url_create결과의 새 다운로드 링크

과금 전에 먼저 확인합니다실행 전에 확인3

  • spicyapi_task_create생성 작업 시작
  • spicyapi_task_retry실패했거나 만료된 작업 다시 실행
  • spicyapi_task_purge완료된 작업의 콘텐츠를 영구 삭제

호출 순서는 Agent Skill로 알려 주세요

MCP 서버는 에이전트가 사용할 기능을 제공하고, Agent Skill은 사용 순서를 안내합니다. 스키마를 읽고 견적을 확인하며, 각 생성 시도에 지정한 멱등성 키를 재전송 시에도 재사용하는 방식입니다. Claude Code와 Codex는 둘 다 지원합니다.

npx skills add spicyapi-ai/spicy-skill \
  --agent claude-code

자주 만나는 오류 해결

처음 사용할 때 겪는 문제는 대부분 이 세 가지 중 하나입니다. 각 카드에서 증상과 바꿔야 할 항목을 확인하세요.

  • 도구

    도구가 보이지 않음

    설정을 수정한 뒤 어시스턴트를 다시 시작하고, JSON이 올바른지 확인하세요.

  • 키

    API 키 없음

    서버 설정의 env 블록에 SPICY_API_KEY를 넣으세요. 데스크톱 앱은 셸에서 export한 키를 인식하지 못합니다.

  • 확인

    작업을 만들 수 없음

    사용 중인 클라이언트가 확인 창을 띄우지 못합니다. 무료 도구는 그대로 쓸 수 있고, 작업을 만들려면 MCP elicitation을 지원하는 클라이언트를 쓰세요.

자주 묻는 질문