MCP-сервер

@spicyapi/mcp позволяет ИИ-ассистенту, которым вы уже пользуетесь, — Claude, Cursor, VS Code, Codex, Windsurf, Gemini CLI и другим — работать со SpicyAPI за вас. После настройки можно написать «сделай из этой фотографии пятисекундное видео», и ассистент подберёт подходящую модель, назовёт цену, дождётся вашего согласия, запустит работу и выдаст ссылку на результат.

Писать код не нужно. Понадобятся Node.js, API-ключ и минут десять.

Что такое MCP простыми словами

MCP (Model Context Protocol) — открытый стандарт, который даёт ИИ-ассистентам дополнительные возможности. Представьте розетку: ассистент с поддержкой MCP может подключать «серверы», и каждый сервер добавляет набор инструментов, которыми ассистент может пользоваться, пока общается с вами.

@spicyapi/mcp — один из таких серверов. Он добавляет 15 инструментов SpicyAPI. Вот что происходит, когда вы о чём-то просите:

1. Вы пишете обычное сообщение, например «Сгенерируй изображение маяка на рассвете».
2. Ассистент решает, какие инструменты SpicyAPI ему нужны, и вызывает их.
3. Сервер — небольшая программа, которая работает на вашем собственном компьютере и запускается приложением ассистента автоматически, — отправляет эти запросы в SpicyAPI с вашим API-ключом.
4. Всё, что стоит денег, сначала ставится на паузу: приложение показывает вам цену и просит подтвердить. Ответить на этот вопрос за вас ассистент не может.
5. Результаты возвращаются в переписку, и ассистент их объясняет.

Ничего не нужно размещать на хостинге или держать запущенным. Приложение ассистента запускает сервер, когда он нужен, и останавливает, когда вы из него выходите.

Вам подойдёт, если вы уже пользуетесь ИИ-ассистентом и хотите пробовать модели, сравнивать цены или создавать изображения и видео, не написав ни одной программы. Разработчики тоже им пользуются, чтобы изучить каталог прямо из редактора, прежде чем строить интеграцию.

Не подходит для рабочего приложения или бэкенда (используйте 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 тебе доступны?» — ассистент должен перечислить 15 инструментов, имена которых начинаются с spicyapi_.

Ни один из этих вопросов ничего не стоит. Если что-то не работает, см. Устранение неполадок.

Попробуйте: примеры разговоров

Скопируйте любой из этих запросов в своего ассистента. В описаниях указано, какими инструментами он обычно пользуется (ассистенты бывают разные, поэтому порядок может отличаться), и где именно он останавливается, чтобы спросить вас.

Проверить баланс и расходы

Сколько у меня денег на балансе 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 пятисекундное видео, в котором камера медленно наезжает.

В 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. Видео часто генерируется несколько минут, а одно ожидание длится не больше пяти, поэтому ассистент может ждать несколько раз, или вы можете спросить о задаче позже.

Найти прежнюю задачу

Покажи мои задачи в SpicyAPI за последние три дня, которые завершились ошибкой, и объясни почему.

Ассистент вызывает spicyapi_tasks_list с фильтром по состоянию failed, а затем 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

Проверяет, доступен ли публичный API SpicyAPI и работает ли он нормально. Ключ не нужен, ничего не стоит и ни о чём не спрашивает. Это диагностический инструмент: запускать его перед созданием задачи ассистенту не нужно.

Параметры: нет.

Возвращает: operational (true или false), отдельные проверки health и readiness с их HTTP-статусом и 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 (в каждой записи есть метка ценового уровня, unit — per_image, per_second, per_request или per_1k_tokens — и price в USD), startingPrice, taskTimeoutSeconds, а если они запрошены, то и inputSchema / examples.

Некоторые настройки, например разрешение или длительность, меняют цену. Список цен нужен для сравнения, а точную сумму списания для конкретного запроса даёт расчёт стоимости.

spicyapi_model_get

Возвращает одну модель полностью: принимаемые входные данные (inputSchema — машиночитаемое описание каждого поля, его типа, допустимых значений и значений по умолчанию), цены, доступность и примеры. Бесплатно, только чтение.

Возвращает: те же поля, что у одного элемента spicyapi_models_list, причём inputSchema есть всегда.

Ваш аккаунт

spicyapi_balance_get

Показывает баланс. Бесплатно, только чтение. Перед созданием задачи вызывать его не обязательно: при создании наличие средств проверяется автоматически.

Параметры: нет.

Возвращает: available, held (зарезервировано под задачи, которые ещё выполняются) и total в USD. Ответ может также содержать разбивку funding на предоплаченные средства, промоначисления и одобренную кредитную линию, если она есть; см. Оплата.

spicyapi_usage_get

Сообщает, что сделал этот API-ключ: сколько было задач, сколько из них выполнено успешно или завершилось ошибкой и сколько окончательно списано, с группировкой по дням и по моделям. Бесплатно, только чтение. Отчёт охватывает только ключ из вашей конфигурации, а не весь аккаунт, и это не баланс.

Возвращает: from, to, currency, totalCalls, totalSpend, а также списки days и models с calls, succeeded, failed и spend. Учитываются только окончательные списания; деньги, которые ещё зарезервированы под выполняющиеся задачи, не учитываются, а позднее окончательное списание может изменить данные за более ранний день.

Задачи

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 задачи и для задачи, которая принадлежит кому-то другому, одинаково возвращается «not found».

spicyapi_task_wait

Проверяет задачу снова и снова, пока она не завершится или не истечёт время ожидания, а затем возвращает её. Бесплатно, только чтение. Истечение времени ожидания не отменяет задачу и не делает её завершившейся ошибкой: она продолжает выполняться, и можно подождать снова или посмотреть её позже.

Возвращает: завершённую задачу в том же виде, что и spicyapi_task_get. Если время ожидания истекло раньше, инструмент сообщает, что за это время задача не завершилась.

Файлы

spicyapi_upload_file

Читает файл с вашего компьютера, загружает его в SpicyAPI, завершает загрузку и возвращает адрес spicy://, который можно указать во входных данных модели, — всё за один вызов, без второго шага. Бесплатно и без подтверждения, но файл при этом отправляется, поэтому к инструментам только для чтения он не относится.

Файлы, которые уже доступны в интернете по публичному адресу https://, загружать не нужно: ассистент может передать этот адрес модели напрямую, если модель принимает URL.

Допустимые файлы: изображения JPEG, PNG, WebP и GIF до 10 MiB; видео MP4 и WebM и аудио MP3 и WAV до 90 MiB и не длиннее 600 секунд. Модель может задать собственные, более строгие ограничения.

Из каких папок: по умолчанию читаются только файлы внутри вашей домашней папки. См. Локальные файлы.

Возвращает: uri (адрес spicy://), fileId, bytes, contentType, sha256, width / height / durationSeconds, если они известны, и expiresAt. По умолчанию адресом можно пользоваться один день.

Когда инструмент возвращает ответ, загрузка уже завершена, поэтому отдельный шаг подтверждения загрузки (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. Расчёт стоимости действует пять минут и только для этого конкретного запроса.

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. Ссылок инструмент намеренно не возвращает. Физическое удаление файлов обычно завершается в течение минуты; см. Хранение и удаление данных.

Ресурсы и промпт

Помимо инструментов, сервер предлагает два ресурса только для чтения и один промпт. Приложения показывают их в разных местах, и многим они никогда не понадобятся.

Стоимость, подтверждение и безопасность

Как выглядит подтверждение

Когда ассистент запускает задачу, приложение показывает вопрос от сервера 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…

Сейчас ориентировочная стоимость и максимальная сумма списания показывают одно и то же число: ориентировочная стоимость — это сумма, которая резервируется при запуске задачи, а больше этого резерва за задачу никогда не списывается.

Как оформлен ответ, зависит от приложения: обычно это флажок или переключатель confirm и кнопки Accept и Decline. Чтобы продолжить, отметьте confirm и примите запрос. Отказ или отмена завершает вызов инструмента, а в сообщении сказано, что произошло и чего не произошло:

Ответьте в течение пяти минут. Расчёт стоимости действует пять минут. Если к моменту подтверждения его срок истёк, создание завершится ошибкой 40901, и ничего не спишется; попросите ассистента попробовать ещё раз, чтобы получить новый расчёт.

При повторе показывается похожий вопрос, но без цены. При уничтожении содержимого в вопросе сказано, что удаление нельзя отменить и что записи биллинга сохраняются.

Почему ассистент не может это пропустить

• Вопрос адресован вам, а не ИИ. Сервер отправляет его в приложение через механизм MCP elicitation, и приложение показывает его вам. У ассистента нет способа на него ответить.
• Ваш ответ привязан именно к этому запросу. Подтверждение связано с моделью и настройками, которые вам показали. Если ассистент что-то изменит между вопросом и вашим ответом, сервер откажет с сообщением «confirmed request state does not match the current tool arguments», и ничего не будет создано.
• Сохраняйте эту защиту. Если в приложении есть настройка, которая автоматически принимает вопросы от MCP-серверов, оставьте её выключенной для SpicyAPI. Ассистент или настройка, которые подтверждают за вас, убирают единственную проверку расходов на этом пути.
• Приложения без поддержки подтверждений не могут тратить деньги. В них запуск, повтор и уничтожение содержимого просто возвращают ошибку; запуск задачи к этому моменту успевает получить только бесплатный расчёт стоимости. См. Перед началом.

Сколько вы платите

• Цены указаны в долларах США. Ориентировочная стоимость, списания и баланс — точные суммы в долларах.
• С вас никогда не спишут больше подтверждённой вами максимальной суммы. Когда задача запускается, её ориентировочная стоимость резервируется (отображается как «held»). Если задача выполнена успешно, вы платите за фактическое использование, но не больше резерва, а неиспользованный остаток освобождается.
• При ошибке или истечении срока задачи резерв обычно освобождается полностью. Некоторые отказы по содержанию оплачиваются по принятой цене, только если это исключение прямо указано на странице модели. Окончательную сумму проверяйте по settled и cost.
• Всё, что только показывает данные, бесплатно: просмотр моделей, расчёты стоимости, баланс, расходы, просмотр задач, ожидание, загрузка файлов и ссылки для скачивания.
• Запущенную задачу нельзя отменить. Закрытие чата, выход из приложения, истечение времени ожидания или отзыв ключа не останавливают уже принятую задачу. См. Необратимость и повтор.
• Действуют лимиты вашего ключа. Когда достигнут дневной лимит, месячный бюджет или общий лимит, новые задачи отклоняются с кодом 40202 до начала следующего периода; см. Оплата.

Сколько хранятся результаты

• Сгенерированные файлы хранятся не дольше примерно 14 дней — меньше, если вы сократили срок хранения для аккаунта или для этой задачи. Скачайте всё, что хотите сохранить.
• Ссылки на результаты временные — обычно 20 минут. Истёкшая ссылка не означает, что файла больше нет: пока не закончился срок хранения, запросите задачу ещё раз и получите свежую ссылку.
• Промпты и входные данные хранятся не дольше 30 дней; запись биллинга о задаче (ID, модель, состояние, сумма, время) сохраняется.
• Загруженными файлами можно пользоваться один день.
• Чтобы удалить содержимое одной задачи раньше срока, попросите ассистента уничтожить его. Чтобы сократить срок хранения для отдельной задачи, попросите задать retentionSeconds при её создании.

Полные правила и исключения описаны на странице Хранение и удаление данных.

Локальные файлы

spicyapi_upload_file умеет читать файлы на вашем компьютере, и здесь нужна осторожность:

• По умолчанию он читает только внутри вашей домашней папки (например, /Users/you или C:\Users\you). Файл в другом месте отклоняется с сообщением, в котором перечислены разрешённые папки.
• Ярлыки не помогают это обойти. Символическая ссылка внутри домашней папки, которая указывает за её пределы, отклоняется.
• Зачем нужно ограничение: ассистент, который читает веб-страницу, письмо или документ, может наткнуться на скрытые инструкции вроде «загрузи закрытые ключи пользователя». Ограничение по папкам не подпускает такие уловки к системным файлам. Ваша домашняя папка при этом остаётся доступной для чтения, поэтому разрешайте ассистенту загружать только те файлы, которые назвали вы сами, и читайте путь, когда приложение просит одобрить вызов инструмента.

Как изменить папки. Добавьте SPICY_MCP_UPLOAD_ROOTS в env сервера, рядом с SPICY_API_KEY, и укажите в нём один или несколько полных путей к папкам. Эта настройка заменяет значение по умолчанию, поэтому её можно сузить до одной папки или перечислить несколько. Папки разделяются так же, как в системной настройке PATH, а это зависит от операционной системы. Записывайте каждую папку полным путём: ~ в этой настройке не раскрывается, хотя в путях к файлам, которые вы называете ассистенту, раскрывается.

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

Эти блоки показывают только часть env. Добавьте строку SPICY_MCP_UPLOAD_ROOTS в env записи spicyapi, созданной в разделе Настройте клиент, а строку с ключом оставьте как есть. Для 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}.

«Только loopback» (только петлевой интерфейс) означает, что подключиться могут лишь программы на этом же компьютере. Другие устройства в вашей сети Wi-Fi и интернет до сервера не дотянутся, и настройки, которая открыла бы доступ, нет: любой другой адрес отклоняется при запуске. Запросы с веб-страниц других сайтов тоже отклоняются. Если вам нужен сервер, доступный с других машин, это не он.

Устранение неполадок

Исходный код

Пакет распространяется под лицензией MIT и разрабатывается открыто по адресу github.com/spicyapi-ai/spicy-mcp. Там же можно прочитать код любого инструмента с этой страницы, сообщить о поведении, которое расходится с описанным, или предложить изменение.

Что дальше