MCP 서버

@spicyapi/mcp를 쓰면 이미 쓰고 있는 AI 어시스턴트(Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI 등)가 나를 대신해 SpicyAPI를 다룰 수 있습니다. 설정을 마치면 "이 사진으로 5초짜리 영상을 만들어 줘"라고 입력하기만 해도, 어시스턴트가 알맞은 모델을 찾고, 가격을 알려 주고, 내 승인을 기다렸다가, 작업을 시작하고, 결과 링크를 건네줍니다.

코드를 작성할 필요는 없습니다. Node.js, API 키, 그리고 10분 정도의 시간만 있으면 됩니다.

MCP란, 쉽게 말하면

MCP(Model Context Protocol)는 AI 어시스턴트에 능력을 추가하는 공개 표준입니다. 플러그를 꽂는 콘센트라고 생각하면 됩니다. MCP를 지원하는 어시스턴트는 "서버"를 불러올 수 있고, 서버마다 어시스턴트가 나와 대화하면서 쓸 수 있는 도구 묶음을 하나씩 추가합니다.

@spicyapi/mcp는 그런 서버 중 하나로, SpicyAPI 도구 15개를 추가합니다. 무언가를 요청하면 다음과 같은 일이 일어납니다.

1. 평소처럼 메시지를 씁니다. 예: "새벽녘 등대 이미지를 만들어 줘."
2. 어시스턴트가 어떤 SpicyAPI 도구가 필요한지 정하고 호출합니다.
3. 서버가 내 API 키로 그 요청을 SpicyAPI에 보냅니다. 서버는 내 컴퓨터에서 실행되는 작은 프로그램으로, 어시스턴트 앱이 자동으로 시작합니다.
4. 비용이 드는 일은 먼저 멈춥니다. 앱이 가격을 보여 주고 확인을 요청합니다. 어시스턴트는 이 질문에 대신 답할 수 없습니다.
5. 결과가 대화로 돌아오고, 어시스턴트가 그 내용을 설명해 줍니다.

따로 호스팅하거나 계속 켜 둘 것은 없습니다. 어시스턴트 앱이 필요할 때 서버를 시작하고, 앱을 종료하면 서버도 멈춥니다.

이런 분께 잘 맞습니다. 이미 AI 어시스턴트를 쓰고 있고, 프로그램을 짜지 않고도 모델을 써 보거나, 가격을 비교하거나, 이미지와 영상을 만들고 싶은 경우입니다. 개발자도 연동을 만들기 전에 에디터 안에서 카탈로그를 살펴볼 때 이 서버를 씁니다.

이런 용도에는 맞지 않습니다. 프로덕션 앱이나 백엔드(SDK나 HTTP API를 쓰세요), 사람이 지켜보지 않는 대량 일괄 작업(CLI를 쓰세요), 채팅 답변을 토큰 단위로 스트리밍하는 용도입니다. MCP 서버는 작업을 제출하고 추적하는 도구이므로, 채팅은 텍스트와 스트리밍을 보세요.

MCP, CLI, SDK, Skill 중 무엇을 쓸까요

SpicyAPI는 패키지 네 개를 따로 배포합니다. 대부분은 한두 개만 있으면 됩니다.

내 앱이 TypeScript로 작성돼 있지 않다면, SDK 줄에는 선택지가 네 개 더 있습니다. Python, Go, PHP, Java입니다.

어시스턴트가 할 수 있는 일

서버가 추가하는 도구 15개 전체입니다. 도구 이름을 직접 부를 일은 없습니다. 내 말로 요청하면 어시스턴트가 알아서 고릅니다. 다만 어시스턴트가 무엇을 했는지 읽을 때나, 앱이 도구 호출을 승인할지 물을 때는 이름을 알아 두면 도움이 됩니다.

"먼저 확인"은 SpicyAPI 서버가 직접 멈추고 확인을 요청한다는 뜻이며, 어시스턴트는 이 단계를 건너뛸 수 없습니다. 많은 앱이 이와 별도로 어떤 도구든 실행하기 전에 나에게 묻기도 합니다. 그것은 앱 자체의 설정이며, 여기서 말하는 확인과는 다릅니다.

시작하기 전에

node --version

클라이언트 설정하기

아래 앱은 모두 같은 명령 npx --yes --package=@spicyapi/mcp spicyapi-mcp를 실행합니다. 처음 시작할 때 패키지를 내려받으므로 몇 초 걸릴 수 있습니다.

이 명령을 직접 실행할 필요는 없습니다. 앱이 알아서 시작합니다. 손으로 실행해 보면 앱이 말을 걸어 오기를 조용히 기다리는데, 멈춘 것처럼 보여도 정상입니다. 끝내려면 Ctrl+C를 누르세요.

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

설정 파일의 위치와 형식은 앱마다 다르고, 버전이 바뀌면 둘 다 달라질 수 있습니다. 위 단계가 내 앱과 더 이상 맞지 않으면 그 앱의 공식 MCP 문서를 기준으로 삼으세요. MCP를 지원하는 다른 앱에서도 위에 나온 command, args, env를 그대로 쓸 수 있습니다.

키를 안전하게 지키기

내 키를 가진 사람은 누구나 내 잔액을 쓸 수 있습니다. 몇 가지 습관만 지키면 피해가 번지지 않게 막을 수 있습니다.

• 키는 사용자 단위 파일에만 넣으세요. 위에 나온, 홈 폴더에 있는 파일들입니다. 프로젝트나 저장소 안의 파일에는 절대 넣지 마세요. 설정 파일을 공개 "dotfiles" 저장소에 백업한다면 이 파일들은 빼세요.
• 키를 채팅에 붙여 넣지 마세요. 어시스턴트에게는 키가 필요 없습니다. 서버가 설정에서 키를 읽습니다.
• 키에 일 한도를 설정하세요. 실수가 생겨도 피해가 한도를 넘지 않습니다.
• 키가 유출되면 폐기하세요. API 키 페이지에서 폐기하고 새 키를 만드세요. 폐기는 즉시 적용되지만, 이미 접수된 작업은 끝까지 실행되고 과금됩니다. 유출 뒤에 할 일은 인증을 보세요.

작동하는지 확인하기

새 대화에서 다음 세 가지를 순서대로 물어보세요.

1. "SpicyAPI 서비스 상태를 확인해 줘." spicyapi_service_status를 씁니다. 키가 필요 없으므로, 이것이 되면 서버는 제대로 설치된 것입니다.
2. "내 SpicyAPI 잔액이 얼마야?" spicyapi_balance_get을 씁니다. 이것이 되면 키가 서버까지 전달되고 있는 것입니다.
3. "SpicyAPI 도구로 뭐가 있어?" 어시스턴트가 이름이 spicyapi_로 시작하는 도구 15개를 나열해야 합니다.

셋 다 비용이 들지 않습니다. 하나라도 실패하면 문제 해결을 보세요.

직접 해 보기: 대화 예시

아래 예시를 어시스턴트에 복사해 넣어 보세요. 설명에는 어시스턴트가 보통 어떤 도구를 쓰는지(어시스턴트마다 달라서 순서는 바뀔 수 있습니다), 그리고 정확히 어디서 멈추고 나에게 묻는지가 나와 있습니다.

잔액과 지출 확인하기

내 SpicyAPI 잔액이 얼마고, 이번 주에 얼마를 썼어?

어시스턴트는 spicyapi_balance_get과 spicyapi_usage_get을 호출합니다. 둘 다 무료이고 읽기 전용이라 확인 요청이 뜨지 않습니다. 잔액의 held(예약된 금액)는 아직 실행 중인 작업이 잡아 둔 돈입니다.

모델 찾아 비교하기

정지 이미지를 영상으로 바꿀 수 있는 SpicyAPI 모델을 찾아서, 5초짜리 클립이면 각각 얼마인지 비교해 줘.

어시스턴트는 spicyapi_models_list를 호출하고(이미지를 받는 영상 모델로 걸러서), 자세한 정보가 필요하면 spicyapi_model_get을, 내 설정에 맞는 정확한 가격을 알기 위해 후보마다 spicyapi_task_quote를 한 번씩 호출할 수 있습니다. 견적은 무료이고 아무것도 만들지 않으므로 확인 요청은 없습니다. 답으로는 골라 쓸 수 있는 비교 결과가 나옵니다.

이미지 생성하기

SpicyAPI로 비 오는 밤, 네온사인이 켜진 라멘 가게를 정사각형 이미지로 만들어 줘. 저렴한 이미지 모델을 골라서 다 되면 링크를 줘.

1. spicyapi_models_list로 모델을 고르고, 그 모델이 받는 필드를 알아야 하면 spicyapi_model_get을 호출합니다.
2. spicyapi_task_create. 여기서 멈춥니다. 앱이 모델, 예상 청구 금액, 최대 청구 금액, 견적 만료 시각을 담은 확인 창을 보여 줍니다. 확인하기 전에는 아무것도 과금되지 않습니다.
3. 확인하면 작업이 시작되고, spicyapi_task_wait가 작업이 끝날 때까지 기다립니다.
4. 어시스턴트가 끝난 작업의 결과 링크를 건네줍니다.

내 컴퓨터의 사진을 영상으로 바꾸기

/Users/me/Desktop/portrait.jpg 사진을 카메라가 천천히 다가가는 5초짜리 영상으로 만들어 줘.

Windows에서는 경로를 C:\Users\me\Desktop\portrait.jpg처럼 쓰세요.

1. spicyapi_upload_file이 사진을 업로드하고 그 사진의 spicy:// 주소를 돌려줍니다. 업로드는 무료이고 확인을 묻지 않지만, 파일을 SpicyAPI로 보내기는 합니다. 그러니 뜻한 파일의 정확한 경로를 알려 주세요.
2. spicyapi_models_list / spicyapi_model_get으로 이미지→영상 모델을 고르고 옵션을 확인합니다.
3. spicyapi_task_create. 여기서 멈추고 가격을 보여 주며 확인을 요청합니다.
4. spicyapi_task_wait. 영상은 몇 분씩 걸리는 경우가 많고 한 번의 대기는 최대 5분이므로, 어시스턴트가 여러 번 기다릴 수도 있습니다. 나중에 작업에 대해 다시 물어봐도 됩니다.

이전 작업 찾기

최근 3일 동안 실패한 내 SpicyAPI 작업을 보여 주고, 왜 실패했는지 알려 줘.

어시스턴트는 실패 상태로 걸러서 spicyapi_tasks_list를 호출한 다음, 관심 있는 작업마다 spicyapi_task_get을 호출해 오류를 읽습니다. 실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요. 이어서 "그거 다시 시도해 줘"라고 하면 spicyapi_task_retry를 호출하는데, 재시도는 새로운 유료 작업이므로 확인을 받기 위해 멈춥니다.

결과 파일 받기

내 마지막 SpicyAPI 영상의 다운로드 링크를 줘.

어시스턴트는 spicyapi_tasks_list로 작업을 찾은 다음, spicyapi_task_get으로 작업을 읽습니다. 여기에는 바로 쓸 수 있는 결과 링크가 들어 있습니다. 링크를 브라우저에서 열면 내려받을 수 있습니다. 링크는 유효 시간이 짧습니다. 만료되었다면 다시 요청하세요. 어시스턴트가 새 링크를 받아 옵니다.

MCP 서버는 스스로 파일을 내 컴퓨터에 저장하지 않습니다. Claude Code나 Codex처럼 명령도 실행할 수 있는 어시스턴트라면, 부탁하면 링크의 파일을 폴더에 내려받아 줄 수 있습니다.

도구 레퍼런스

모든 도구가 무엇을 받고 무엇을 돌려주는지 정리했습니다. 금액은 항상 미국 달러이며, $ 기호 없이 정확한 십진수 텍스트로 씁니다. 예: "0.08". 날짜는 UTC입니다.

서비스와 문서 확인

spicyapi_service_status

SpicyAPI 공개 API에 연결할 수 있고 정상인지 확인합니다. API 키가 필요 없고, 비용이 들지 않으며, 확인을 묻지 않습니다. 진단용 도구이므로 어시스턴트가 작업을 만들기 전에 실행할 필요는 없습니다.

매개변수: 없음.

반환값: operational(true 또는 false), HTTP 상태가 함께 담긴 개별 health 및 readiness 검사 결과, checkedAt.

spicyapi_docs_search

서버 안에 함께 들어 있는 SpicyAPI 문서 페이지 색인을 검색해, 일치하는 제목, 요약, 링크를 돌려줍니다. 키가 필요 없고 네트워크 요청도 보내지 않습니다.

반환값: 항목 목록이며, 항목마다 slug, title, summary, keywords, url이 있습니다. 링크는 이 문서 사이트를 가리키며 https://docs.spicyapi.ai/docs/retention 같은 형태입니다. 일치하는 것이 없으면 빈 목록을 돌려줍니다.

모델 둘러보기

spicyapi_models_list

내 API 키로 호출할 수 있는 모델을 나열합니다. 가격에는 내 계정에 적용되는 할인이 이미 반영되어 있습니다. 무료이며 읽기 전용입니다.

반환값: total과 items. 항목마다 model(사용할 정확한 ID), displayName, provider, modality, tasks, enabled와 available, availability, pricing 목록(각 항목에 가격 구간 이름, per_image·per_second·per_request·per_1k_tokens 중 하나인 unit, USD 기준 price가 들어 있습니다), startingPrice, taskTimeoutSeconds가 있고, 요청한 경우 inputSchema / examples도 들어 있습니다.

해상도나 길이 같은 일부 설정은 가격을 바꿉니다. 가격 목록은 비교용이며, 특정 요청에 실제로 청구될 정확한 금액은 견적으로 확인합니다.

spicyapi_model_get

모델 하나의 전체 정보를 돌려줍니다. 받는 입력(inputSchema: 필드마다 타입, 허용 값, 기본값을 기계가 읽을 수 있게 적은 설명), 가격, 사용 가능 여부, 예시입니다. 무료이며 읽기 전용입니다.

반환값: spicyapi_models_list의 항목 하나와 같은 필드이며, inputSchema가 항상 들어 있습니다.

내 계정

spicyapi_balance_get

잔액을 보여 줍니다. 무료이며 읽기 전용입니다. 작업을 만들기 전에 꼭 호출할 필요는 없습니다. 작업을 만들 때 잔액을 직접 확인하기 때문입니다.

매개변수: 없음.

반환값: USD 기준 available, held(아직 실행 중인 작업을 위해 예약된 금액), total. 선불 충전금, 프로모션 지원금, 승인된 후불 한도로 나눈 funding 내역이 함께 올 수도 있습니다. 과금을 보세요.

spicyapi_usage_get

이 API 키가 한 일을 알려 줍니다. 작업 수, 성공과 실패 수, 정산된 지출을 날짜별·모델별로 묶어 보여 줍니다. 무료이며 읽기 전용입니다. 계정 전체가 아니라 설정에 넣은 키 하나만 다루며, 잔액과는 다른 정보입니다.

반환값: from, to, currency, totalCalls, totalSpend, 그리고 calls, succeeded, failed, spend가 들어 있는 days와 models 목록. 정산된 청구만 집계합니다. 실행 중인 작업이 아직 예약해 둔 금액은 들어가지 않으며, 정산이 늦게 이뤄지면 이전 날짜의 값이 바뀔 수 있습니다.

작업

spicyapi_tasks_list

이 API 키로 만든 작업을 최신순으로 나열합니다. 채팅을 닫은 뒤 작업을 다시 찾을 때 유용합니다. 메타데이터만 보여 주며 프롬프트, 입력, 결과 링크는 없습니다. 무료이며 읽기 전용입니다.

반환값: items(항목마다 taskId, model, state, cost, settled, createdAt, deadlineAt, 끝난 작업이면 completedAt), hasMore, nextCursor. cost는 settled가 true일 때만 최종 금액입니다.

spicyapi_task_get

이 API 키로 만든 작업 하나를 엽니다. 무료이며 읽기 전용입니다.

반환값: taskId, model, state, cost, settled, createdAt, completedAt, 그리고 작업에 따라 다음 항목이 들어 있습니다.

• output.assets: 결과물입니다. 준비된 에셋마다 바로 열 수 있는 url과 함께 expiresAt, mime 형식, 크기나 길이가 있습니다. pending으로 표시된 에셋은 아직 저장 중이니 몇 초 뒤에 다시 물어보세요. unavailable로 표시된 에셋은 영구히 사라진 것입니다.
• errorCode와 errorMessage: 작업이 실패했을 때 들어 있습니다. 코드 목록은 오류에 있습니다.
• input: 보낸 내용입니다. 프롬프트 보관 기간이 끝날 때까지 남아 있습니다.
• contentState(present, expired, purged)와 retention: 결과물과 프롬프트가 언제 지워지는지 알려 줍니다.
• sourceTaskId: 이 작업이 재시도로 만들어진 경우에 들어 있습니다.

존재하지 않는 작업 ID와 다른 사람의 작업 ID는 둘 다 "찾을 수 없음"(not found)을 돌려줍니다.

spicyapi_task_wait

작업이 끝나거나 대기 시간이 다 될 때까지 작업을 반복해서 확인한 다음, 작업을 돌려줍니다. 무료이며 읽기 전용입니다. 대기 시간이 다 돼도 작업이 취소되거나 실패하지는 않습니다. 작업은 계속 실행되므로, 다시 기다리거나 나중에 조회하면 됩니다.

반환값: 끝난 작업이며, spicyapi_task_get과 같은 형태입니다. 시간이 먼저 다 되면, 그 시간 안에 작업이 끝나지 않았다고 알려 줍니다.

파일

spicyapi_upload_file

내 컴퓨터의 파일을 읽어 SpicyAPI에 업로드하고, 업로드를 마무리한 뒤, 모델 입력에 넣을 수 있는 spicy:// 주소를 돌려줍니다. 두 번째 단계 없이 호출 한 번으로 끝납니다. 무료이고 확인을 묻지 않지만, 파일을 보내므로 읽기 전용은 아닙니다.

이미 공개 https:// 주소로 온라인에 올라가 있는 파일은 업로드할 필요가 없습니다. 모델이 URL을 받는다면 어시스턴트가 그 주소를 모델에 바로 넘길 수 있습니다.

받는 파일: 최대 10 MiB의 JPEG, PNG, WebP, GIF 이미지, 최대 90 MiB·600초의 MP4와 WebM 영상, MP3와 WAV 오디오. 모델마다 이보다 엄격한 제한을 따로 둘 수 있습니다.

읽을 수 있는 폴더: 기본적으로 홈 폴더 안의 파일만 읽을 수 있습니다. 로컬 파일을 보세요.

반환값: uri(spicy:// 주소), fileId, bytes, contentType, sha256, 알 수 있는 경우 width / height / durationSeconds, 그리고 expiresAt. 주소는 기본적으로 1일 동안 쓸 수 있습니다.

이 도구가 결과를 돌려줄 때는 업로드가 이미 끝난 상태이므로, 따로 실행할 "commit"(확정) 단계가 없습니다. 다른 프로그램이 시작한 업로드를 마무리하는 도구는 서버에 없습니다. 업로드를 여러 단계로 나눠 처리하는 코드라면 SDK의 commitUploadedFile로 마무리합니다.

spicyapi_download_url_create

내 작업의 결과 하나에 대해 서명된 새 다운로드 링크를 발급합니다. 무료입니다. 대개는 필요 없습니다. spicyapi_task_get과 spicyapi_task_wait에 이미 바로 쓸 수 있는 링크가 들어 있고, 작업을 다시 조회하면 링크도 새로 발급되기 때문입니다.

반환값: key, url, expiresAt. 링크는 20분 동안 작동하며, 한 번 발급하면 무효화할 수 없으므로 공유하거나 저장하지 마세요. 미디어를 보세요.

가격 확인, 생성, 삭제

spicyapi_task_quote

특정 요청의 정확한 가격을 아무것도 시작하지 않고 금액도 예약하지 않은 채 계산합니다. 무료이며 읽기 전용입니다. 어시스턴트는 선택지를 비교할 때 이 도구를 씁니다. 작업을 만들 때는 따로 견적을 받으므로, 그 전에 이 도구를 호출할 필요는 없습니다.

반환값: quoteId, model, estimatedCost, maxCharge, currency, quantity, unit, expiresAt. 견적은 5분 동안, 정확히 그 요청에 대해서만 유효합니다.

spicyapi_task_create

생성을 시작합니다. 비용이 들며, 항상 먼저 확인을 요청합니다.

진행 순서는 다음과 같습니다.

1. 서버가 요청의 정확한 견적을 받습니다. 견적은 무료이며, 아무것도 만들지 않고 금액도 예약하지 않습니다.
2. 앱이 모델, 예상 청구 금액, 최대 청구 금액, 견적 만료 시각, 멱등 키(같은 요청이 두 번 과금되지 않게 막는 식별값)를 담은 확인 창을 보여 줍니다.
3. 거절하면 작업이 만들어지지 않고, 금액도 예약되거나 청구되지 않습니다. 그때까지 보낸 요청은 1단계의 무료 견적뿐입니다.
4. 확인하면 SpicyAPI가 입력, 가격, 키 권한, 잔액을 확인하고, 예상 금액을 예약한 뒤 작업을 시작합니다.

이 도구를 쓰려면 확인 질문을 띄울 수 있는 앱(MCP elicitation 지원)이 필요합니다. 그럴 수 없는 앱에서는 2단계에서 실패합니다. 무료 견적만 받았을 뿐 그 밖에는 아무 일도 일어나지 않습니다. 시작하기 전에를 보세요.

반환값: taskId, state(보통 queued), estimatedCost, 사용한 idempotencyKey. 이후 작업은 알아서 실행되므로, spicyapi_task_wait나 spicyapi_task_get으로 결과를 받아 오세요.

확인한 뒤에 연결이 끊기면 오류에 멱등 키가 들어 있습니다. 처음부터 새로 시작하지 말고, 같은 키와 바꾸지 않은 모델·설정으로 다시 시도해 달라고 어시스턴트에게 요청하세요. 확인을 다시 요청받을 수는 있지만, SpicyAPI는 두 번째 작업을 과금하지 않고 원래 작업을 돌려줍니다. 새 키를 쓰면 두 번째 유료 작업이 만들어지고, 같은 키로 설정을 바꾸면 거부됩니다.

spicyapi_task_retry

failed 또는 expired 상태인 작업을 바탕으로 별도로 과금되는 새 작업을 만듭니다. 원래 작업은 그대로 남습니다. 비용이 들며, 항상 먼저 확인을 요청합니다.

반환값: 새 taskId, sourceTaskId(원래 작업), state, estimatedCost, idempotencyKey.

재시도에는 모델의 현재 가격이 적용되며, 입력·권한·잔액에 대한 검사도 현재 기준으로 다시 실행됩니다. 재시도의 확인 창에는 가격이 표시되지 않습니다. 가격을 먼저 알고 싶다면, 재시도하기 전에 같은 모델과 설정으로 spicyapi_task_quote 견적을 받아 달라고 어시스턴트에게 요청하세요.

재시도는 원래 입력을 바꾸지 않고 그대로 쓰므로, 먼저 실패한 작업의 errorCode를 확인하세요.

• rate_limited, upstream_unavailable, timeout, upstream_failed: 잠시 기다린 뒤 한 번 재시도해 볼 만합니다.
• generation_failed: 프롬프트나 이미지를 바꿔 새 작업을 시작하세요. 같은 입력은 대개 같은 방식으로 다시 실패합니다.
• invalid_asset: 파일을 다시 업로드하고, 새 spicy:// 주소로 새 작업을 시작하세요. 재시도하면 예전 파일을 그대로 다시 씁니다.
• content_rejected, invalid_request, unsupported_combination: 그대로 재시도하지 마세요. 프롬프트, 설정, 모델을 바꿔 새 작업을 시작하세요.

전체 목록은 오류에 있습니다.

spicyapi_task_purge

끝난 작업 하나에 저장된 내용을 영구히 삭제합니다. 생성된 미디어, 결과 페이로드(저장된 결과 데이터), 프롬프트와 그 밖의 입력 텍스트가 대상입니다. 되돌릴 수 없으며, 항상 먼저 확인을 요청합니다. 비용은 들지 않지만, 환불도 되지 않습니다.

• 끝난 작업(succeeded, failed, expired, 또는 예전 기록에 남은 canceled)만 파기할 수 있습니다. 접수된 작업은 취소할 수 없고 취소 API도 없으므로, queued나 running 상태인 작업은 끝날 때까지 기다린 뒤(spicyapi_task_wait) 파기하세요.
• 남겨 두고 싶은 것은 먼저 내려받으세요.
• 과금 기록은 남습니다. 원장 항목, 청구 금액, 모델, 상태, 타임스탬프, 요청 ID는 파기한 뒤에도 계속 볼 수 있습니다.
• 이미 파기한 작업을 다시 파기해도 아무 문제가 없습니다.

반환값: taskId, contentState(삭제가 예정되는 즉시 purged), purgedAt, contentRemovedBy, billingRetained: true. 링크는 일부러 돌려주지 않습니다. 파일의 물리적 삭제는 보통 1분 안에 끝납니다. 데이터 보관과 파기를 보세요.

리소스와 프롬프트

서버는 도구 말고도 읽기 전용 리소스 두 개와 프롬프트 하나를 제공합니다. 앱마다 보여 주는 위치가 다르며, 많은 사람은 쓸 일이 없습니다.

비용, 확인, 안전

확인 창은 이렇게 생겼습니다

어시스턴트가 작업을 시작하면 앱이 SpicyAPI 서버가 보낸 질문을 보여 줍니다. 문구는 대략 다음과 같습니다(금액은 예시입니다).

Create a billable task using MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.20;
maximum charge: USD 0.20. Quote expires: 2026-09-17T12:05:00Z. Before accepting
the request, SpicyAPI checks the model's current input requirements, price and
availability, your API key permissions, and available funds.
Idempotency-Key: 4f1c…

예상 청구 금액(Estimated charge)과 최대 청구 금액(maximum charge)은 현재 같은 숫자로 표시됩니다. 예상 금액은 작업이 시작될 때 예약되는 금액이고, 작업에는 그 예약 금액보다 많이 청구되는 일이 없기 때문입니다.

답하는 방식은 앱마다 다릅니다. 보통 confirm 체크박스나 스위치가 있고, 그 아래에 수락(Accept)과 거절(Decline) 버튼이 있습니다. confirm에 체크하고 수락하면 진행됩니다. 거절하거나 취소하면 도구 호출이 끝나고, 무엇이 일어났고 무엇이 일어나지 않았는지 메시지로 알려 줍니다.

5분 안에 답하세요. 견적은 5분 동안 유효합니다. 확인하는 시점에 견적이 이미 만료되었다면 생성은 오류 40901로 실패하고 아무것도 과금되지 않습니다. 어시스턴트에게 다시 시도해 새 견적을 받아 달라고 하세요.

재시도도 비슷한 질문을 보여 주지만 가격은 표시되지 않습니다. 파기할 때는 삭제를 되돌릴 수 없고 과금 기록은 남는다고 알려 줍니다.

어시스턴트가 건너뛸 수 없는 이유

• 질문은 AI가 아니라 나에게 옵니다. 서버는 MCP의 elicitation 기능으로 질문을 앱에 보내고, 앱이 그 질문을 나에게 보여 줍니다. 어시스턴트에게는 이 질문에 답할 방법이 없습니다.
• 내 답은 바로 그 요청에 묶입니다. 확인은 화면에 표시된 모델과 설정에 묶여 있습니다. 질문과 내 답 사이에 어시스턴트가 무엇이든 바꾸면, 서버는 "confirmed request state does not match the current tool arguments" 오류로 거부하고 아무것도 만들지 않습니다.
• 이 상태를 그대로 유지하세요. 앱에 MCP 서버의 질문을 자동으로 수락하는 설정이 있다면 SpicyAPI에 대해서는 꺼 두세요. 나 대신 확인해 버리는 어시스턴트나 설정은, 이 경로에서 지출을 막는 유일한 확인 절차를 없애 버립니다.
• 확인을 지원하지 않는 앱에서는 돈을 쓸 수 없습니다. 그런 앱에서는 작업 시작, 재시도, 파기가 그냥 오류를 돌려줍니다. 작업 시작의 경우 그 시점까지 무료 견적만 받은 상태입니다. 시작하기 전에를 보세요.

내가 내는 비용

• 가격은 미국 달러입니다. 예상 금액, 청구 금액, 잔액은 모두 정확한 달러 금액으로 표시됩니다.
• 확인한 최대 금액보다 많이 청구되는 일은 없습니다. 작업이 시작되면 예상 금액이 예약됩니다(held로 표시). 작업이 성공하면 실제 사용량만큼 지불하되 예약 금액을 넘지 않으며, 쓰지 않은 금액은 해제됩니다.
• 실패하거나 만료된 작업은 보통 예약 금액이 전액 해제됩니다. 다만 모델 페이지에 명시된 일부 콘텐츠 거부는 접수 시 견적 금액으로 과금됩니다. 최종 청구액은 settled와 cost로 확인하세요.
• 조회는 무료입니다. 모델 둘러보기, 견적, 잔액, 사용량, 작업 조회, 대기, 업로드, 다운로드 링크가 모두 여기에 해당합니다.
• 시작된 작업은 취소할 수 없습니다. 채팅을 닫거나, 앱을 종료하거나, 대기 시간이 다 되거나, 키를 폐기해도 이미 접수된 작업은 멈추지 않습니다. 작업 확정과 재시도를 보세요.
• 키의 한도가 적용됩니다. 일·월·누적 한도에 도달하면 기간이 바뀔 때까지 새 작업이 40202로 거부됩니다. 지출 한도는 과금을 보세요.

결과 보관 기간

• 생성된 파일은 최대 약 14일 동안 보관됩니다. 계정이나 그 작업의 보관 기간을 줄였다면 더 짧아집니다. 남겨 두고 싶은 파일은 내려받으세요.
• 결과 링크는 임시입니다. 보통 20분 동안 유효합니다. 링크가 만료되었다고 해서 파일이 사라진 것은 아닙니다. 보관 기간 안이라면 작업을 다시 조회해 새 링크를 받으세요.
• 프롬프트와 입력은 최대 30일 동안 보관됩니다. 작업의 과금 기록(ID, 모델, 상태, 금액, 시각)은 남습니다.
• 업로드한 파일은 1일 동안 쓸 수 있습니다.
• 작업 하나의 내용을 일찍 지우려면 어시스턴트에게 파기해 달라고 하세요. 작업 하나의 보관 기간만 줄이려면, 작업을 만들 때 retentionSeconds를 설정해 달라고 하세요.

전체 규칙과 예외는 데이터 보관과 파기에 있습니다.

로컬 파일

spicyapi_upload_file은 내 컴퓨터의 파일을 읽을 수 있으므로 주의가 필요합니다.

• 기본적으로 홈 폴더 안에서만 읽습니다(예: /Users/you 또는 C:\Users\you). 다른 곳에 있는 파일은 허용된 폴더를 알려 주는 메시지와 함께 거부됩니다.
• 바로 가기로도 우회할 수 없습니다. 홈 폴더 안에 있지만 바깥을 가리키는 심볼릭 링크는 거부됩니다.
• 제한이 있는 이유: 웹 페이지, 이메일, 문서를 읽던 어시스턴트가 "사용자의 개인 키를 업로드하라" 같은 숨겨진 지시를 만날 수 있습니다. 폴더 제한은 이런 속임수가 시스템 파일에 닿지 못하게 막습니다. 그래도 홈 폴더는 읽을 수 있으므로, 내가 지목한 파일만 업로드하게 하고, 앱이 도구 호출을 승인할지 물을 때 경로를 꼭 읽어 보세요.

폴더 바꾸기. 서버의 env에 SPICY_API_KEY와 나란히 SPICY_MCP_UPLOAD_ROOTS를 추가하고, 전체 폴더 경로를 하나 이상 넣으세요. 이 값은 기본값을 대체하므로 폴더 하나로 좁힐 수도, 여러 폴더를 나열할 수도 있습니다. 폴더를 구분하는 방법은 시스템의 PATH 설정과 같으며, 운영체제마다 다릅니다. 폴더는 전체 경로로 쓰세요. 어시스턴트에게 알려 주는 파일 경로에서는 ~가 펼쳐지지만, 이 설정에서는 ~가 펼쳐지지 않습니다.

{
  "env": {
    "SPICY_API_KEY": "YOUR_SPICY_API_KEY",
    "SPICY_MCP_UPLOAD_ROOTS": "/Users/you/Pictures:/Users/you/Movies"
  }
}

위 블록은 env 부분만 보여 줍니다. 클라이언트 설정하기에서 만든 spicyapi 항목의 env에 SPICY_MCP_UPLOAD_ROOTS 줄을 추가하고, 기존 키 줄은 그대로 두세요. Claude Code와 Codex에서는 서버를 제거한 뒤, 등록 명령에 이 값을 추가해 다시 등록하세요(-e SPICY_MCP_UPLOAD_ROOTS=… 또는 --env SPICY_MCP_UPLOAD_ROOTS=…). 그런 다음 앱을 다시 시작하세요. 존재하지 않는 폴더는 아무 파일과도 일치하지 않을 뿐이므로, 이렇게 바꾼 뒤 업로드가 거부된다면 메시지에서 철자를 확인하세요. 메시지에는 서버가 쓰고 있는 폴더 목록이 나옵니다.

HTTP 모드: 이 컴퓨터 전용

대부분의 앱은 위에서처럼 서버를 직접 시작합니다. 몇몇 앱은 이미 실행 중인 서버에 주소로 연결하는 방식을 선호합니다. 그런 앱을 위해 패키지에는 두 번째 프로그램인 spicyapi-mcp-http가 들어 있습니다.

export SPICY_API_KEY="sk-spicy-..."
export SPICY_MCP_HTTP_TOKEN="$(node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))")"
npx --yes --package=@spicyapi/mcp spicyapi-mcp-http

실행하면 SpicyAPI MCP HTTP listening at http://127.0.0.1:8765/mcp가 출력됩니다. 앱이 이 주소에 연결하도록 하고, Authorization: Bearer 뒤에 SPICY_MCP_HTTP_TOKEN 값을 붙인 헤더를 보내도록 설정하세요. 서버가 실행 중이면 http://127.0.0.1:8765/healthz가 {"ok":true}로 응답합니다.

"루프백 전용"은 같은 컴퓨터에 있는 프로그램만 연결할 수 있다는 뜻입니다. 같은 Wi-Fi에 연결된 다른 기기나 인터넷에서는 접근할 수 없고, 외부에 열어 주는 설정도 없습니다. 다른 주소를 지정하면 시작할 때 거부됩니다. 다른 사이트의 웹 페이지에서 온 요청도 거부됩니다. 다른 컴퓨터에서 접근할 수 있는 서버가 필요하다면 이 기능은 맞지 않습니다.

문제 해결

소스

이 패키지는 MIT 라이선스이고 **github.com/spicyapi-ai/spicy-mcp**에서 공개적으로 개발됩니다. 이 페이지에서 설명한 도구의 구현을 읽거나, 문서와 다르게 동작하는 부분을 알리거나, 변경을 제안하는 일 모두 저장소에서 하면 됩니다.

다음 단계