SpicyAPI MCP Server

@spicyapi/mcp

SpicyAPI の公式ローカル MCP サーバーです。すでにお使いの AI アシスタント（Claude Desktop、Claude Code、Codex、Cursor、VS Code、Windsurf、Gemini CLI、その他の MCP クライアント）から、最新のモデルカタログの閲覧、価格の比較、生成タスクの作成、結果の取得ができます。料金が発生する各ステップは、すべてお客様の確認後に実行されます。

SpicyAPI は、プラットフォームによるコンテンツフィルターが追加されていない、制限のない AI API です。1 つのキーで 200 以上の画像、動画、音声、チャットモデル（Seedance、Kling、Wan、MiniMax、Seedream、GPT Image、Suno など）を利用できます。リクエストで生成できる内容は選択したモデルによって異なり、カタログでは検閲なしのモデルを確認できます。

このパッケージは spicyapi-mcp（stdio）と spicyapi-mcp-http（ループバック限定の Streamable HTTP）をインストールします。CLI や Agent Skill は含まれていません。

初心者にもわかりやすい詳しいガイド：docs.spicyapi.ai/docs/mcp。

概要

MCP（Model Context Protocol）は、AI アシスタントに機能を追加するためのオープンスタンダードです。このサーバーをアシスタントに追加すると、「この写真から 5 秒の動画を作って」のように普通の言葉で頼むだけで、アシスタントが次の処理を行います。

1. 最新のカタログから適切なモデルを見つけ、対応している入力を確認します。
2. ローカルファイルがあればアップロードします。
3. 正確な米ドル料金の見積もりを取得し、料金が発生する前に必ずお客様に確認します。
4. タスクを開始して完了を待ち、結果のリンクをお渡しします。

サーバーはお使いのコンピューター上で実行されます。必要に応じてアシスタントアプリが起動するため、ホスティングは不要です。

必要条件

• Node.js 22.13 以降（node --version）。npx は Node.js に同梱されています。
• SpicyAPI API キー（下記を参照）と、有料タスクに必要なアカウント残高。カタログの閲覧、料金の見積もり、結果の確認は無料です。
• MCP クライアント。タスクの作成、再試行、削除には、MCP フォームのエリシテーション（ユーザーに質問するためのプロトコル機能）に対応したクライアントも必要です。対応していないクライアントでは、この 3 つのツールは通常 did not declare the required capability を含むエラーを返します。作成、予約、課金、削除は一切行われません。この時点でタスク作成時に取得されているのは無料の見積もりのみで、再試行と削除ではリクエストは送信されていません。読み取り専用ツールは引き続き使用できます。

まずキーを取得する

1. spicyapi.ai/register でアカウントを作成します。新規登録が一時停止中の場合は、このページにウェイトリストへの登録方法が表示されます。
2. API キーページでキーを作成を選択します。使用するアシスタントの名前を付けます。詳細設定では、1 日あたりの上限、月間予算、生涯上限、利用可能なモデル、IP 許可リスト、有効期限を設定できます。新しいキーには、0 を入力して上限なしにしない限り、プラットフォームのデフォルトの 1 日あたりの上限が設定されます。
3. キーをコピーします。キーは sk-spicy- で始まり、一度だけ表示されます。
4. 以下のターミナルを使用する手順では、セットアップコマンドを実行するターミナルでキーを環境変数に設定します。

export SPICY_API_KEY="sk-spicy-..."   # paste your own key

Windows PowerShell の場合：$env:SPICY_API_KEY = "sk-spicy-..."。

クライアントに追加する

以下のすべてのクライアントで、同じ stdio サーバーを実行します：npx --yes --package=@spicyapi/mcp spicyapi-mcp。

このサーバーを手動で実行する必要はありません。MCP クライアントが起動します。手動で起動すると、stdin で何もせずに待機するため、フリーズしたように見えます。また、このパッケージにはバイナリが 2 つ含まれているため、バイナリ名の前に --package=@spicyapi/mcp を指定する必要があります。npx @spicyapi/mcp だけでは could not determine executable to run というエラーになります。

Claude Desktop

1. 設定 → 開発者 → 設定を編集を開きます。設定ファイルは、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json です。
2. 下記のブロックを貼り付けます（または既存の mcpServers に spicyapi エントリを追加します）。YOUR_SPICY_API_KEY を置き換えてください。
3. Claude Desktop を完全に終了してから再度開きます。このファイルは起動時にのみ読み込まれます。

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

Claude Code

claude mcp add spicyapi \
  -e SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

デフォルトのスコープは現在のプロジェクトです。すべてのプロジェクトで使うには、--scope user を追加してください。リポジトリ内の .mcp.json にキーを書き込む --scope project は使用しないでください。claude mcp list または /mcp で確認できます。Windows ネイティブ環境でサーバーが起動しない場合は、-- cmd /c npx --yes --package=@spicyapi/mcp spicyapi-mcp を使用してください。

Codex

codex mcp add spicyapi \
  --env SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

このコマンドは ~/.codex/config.toml に書き込みます。このファイルは Codex CLI、IDE 拡張機能、ChatGPT デスクトップアプリのすべてが読み込むため、一度設定すれば、3 つすべてで利用できます。codex mcp list または /mcp で確認できます。

どちらのターミナルコマンドも、現在のシェルから SPICY_API_KEY をクライアントのローカル設定にコピーするため、キーをすでにエクスポートした状態のターミナルで実行してください。キーをエクスポートしていなかった場合は、サーバーを削除（claude mcp remove spicyapi / codex mcp remove spicyapi）してから、再度追加してください。

Cursor、Windsurf、Gemini CLI

Cursor（~/.cursor/mcp.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）、Gemini CLI（~/.gemini/settings.json）は、Claude Desktop と同じ形式を使用します。

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

Windows では、これらのファイルは %USERPROFILE% の下にあります。ファイルにすでにほかの設定がある場合は、mcpServers を追加してください。ファイル全体が、コメントや末尾のカンマのない有効な JSON である必要があります。ツールが表示されない場合は、クライアントを再起動してください（Gemini CLI では /mcp で一覧を確認できます）。

これらは、リポジトリの外にあるユーザーレベルのファイルです。実際のキーを含む設定ブロックを、コミットされるプロジェクトファイル（プロジェクトレベルの .cursor/mcp.json など）にコピーしないでください。

VS Code

.vscode/mcp.json はリポジトリとともにコミットされるため、VS Code にキーの入力を求めさせ、独自のシークレットストレージに保管してください。

{
  "inputs": [
    {
      "id": "spicyapi-key",
      "type": "promptString",
      "description": "SpicyAPI key",
      "password": true
    }
  ],
  "servers": {
    "spicyapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "${input:spicyapi-key}" }
    }
  }
}

エントリの上にあるコードレンズ、または MCP: List Servers からサーバーを起動します。キーを求められたら貼り付けて、エージェントモードのチャットでツールを使用してください。

その他の MCP クライアント

同じ command、args、env を使用してください。設定の場所と形式はクライアントごとに異なり、バージョン間でも変わるため、各クライアントの公式ドキュメントを参照してください。

動作を確認する

アシスタントに、次の順番で尋ねてください。

1. 「SpicyAPI のサービスステータスを確認してください。」 — spicyapi_service_status はキーを必要としないため、サーバーが起動することを確認できます。
2. 「SpicyAPI の残高はいくらですか？」 — spicyapi_balance_get により、キーがサーバーに届いていることを確認できます。
3. 「どの SpicyAPI ツールが使えますか？」 — spicyapi_ で始まる 22 個のツールが表示されるはずです。

これらはいずれも無料です。

実際に使ってみる

SpicyAPI を使って利用可能な画像モデルを一覧表示し、手頃なモデルを選んで、映画のような夜のポートレートを生成してください。完了したら結果のリンクを教えてください。

エージェントはカタログを読み込み、モデルのスキーマを取得し、正確な見積もりを確認します。料金が発生する前に、確認を求めて処理を停止します。

試してみるプロンプト：

• 「SpicyAPI の残高はいくらですか？今週はいくら使いましたか？」 — 残高と使用状況を確認します。無料です。
• 「画像を動画に変換できる SpicyAPI モデルを探して、それぞれで 5 秒の動画を作る費用を比較してください。」 — カタログと見積もりを確認します。無料です。
• 「/Users/me/Desktop/portrait.jpg を、ゆっくり寄りながら撮影する 5 秒の動画にしてください。」 — アップロード後、確認を経てタスクを実行します。
• 「過去 3 日間に失敗した SpicyAPI のタスクと、その理由を表示してください。」 — タスク履歴を確認します。無料です。その後、再試行する場合は確認を求められます。
• 「最後のタスクの結果を『Hero portrait』という名前で SpicyAPI のアセットライブラリに保存し、その画像を開始画像として 5 秒の動画を作成してください。」 — アセットを保存した後、確認を経てタスクを実行します。

モデル ID は常に最新のカタログから取得されます。SpicyAPI のドキュメントにある MODEL_ID_FROM_CATALOG などのプレースホルダーは、そのままの値ではなく、カタログから選んだ正確な ID を意味します。

ツール

ツール	用途	読み取り専用	課金対象	確認
spicyapi_service_status	公開されている稼働状況と準備状況。キーは不要	はい	いいえ	いいえ
spicyapi_docs_search	同梱されている公式ドキュメントのインデックスを検索。キーは不要	はい	いいえ	いいえ
spicyapi_models_list	有効なモデルとアカウント固有の価格	はい	いいえ	いいえ
spicyapi_model_get	1つのモデルと現在の入力スキーマ	はい	いいえ	いいえ
spicyapi_balance_get	利用可能額、保留額、残高合計	はい	いいえ	いいえ
spicyapi_usage_get	現在のキーで確定した米ドル建ての利用額	はい	いいえ	いいえ
spicyapi_tasks_list	現在のキーに関するタスクメタデータの1ページ分	はい	いいえ	いいえ
spicyapi_task_get	タスクを1件読み取り、利用可能な結果リンクを含める	はい	いいえ	いいえ
spicyapi_task_wait	タスクが終端状態になるまで最大300秒待機	はい	いいえ	いいえ
spicyapi_task_quote	何も作成せずに正確なリクエストの価格を見積もる	はい	いいえ	いいえ
spicyapi_upload_file	ローカルファイルを読み取り、アップロードして確定し、spicy:// URIを返す	いいえ	いいえ	いいえ
spicyapi_download_url_create	タスク出力用の有効期間が短い署名付きURL	いいえ	いいえ	いいえ
spicyapi_task_create	非同期の生成タスクを作成	いいえ	はい	常に
spicyapi_task_retry	失敗または期限切れのタスクから新しいタスクを作成	いいえ	はい	常に
spicyapi_task_purge	終端状態のタスク1件の保存内容を破棄（destructiveHint）	いいえ	いいえ	常に
spicyapi_assets_list	保存済みアセットの1ページ分。それぞれにspicy://a/参照を含む	はい	いいえ	いいえ
spicyapi_assets_usage_get	アセットのストレージプラン、保存内容、本日の件数、次のプラン	はい	いいえ	いいえ
spicyapi_asset_save	タスク出力、ローカルファイル、URLまたはアップロードをライブラリに保存	いいえ	いいえ	いいえ
spicyapi_asset_rename	保存済みアセットの名前を変更。参照は変わらない	いいえ	いいえ	いいえ
spicyapi_asset_delete	保存済みアセットを完全に削除（destructiveHint）	いいえ	いいえ	常に
spicyapi_characters_list	キャラクターの1ページ分。それぞれの画像を順番に含む	はい	いいえ	いいえ
spicyapi_character_get	キャラクター1件とその画像をspicy://a/参照として取得	はい	いいえ	いいえ

サーバーは、2つのリソース — spicyapi://docs/index と spicyapi://contract/openapi — および1つのプロンプトも登録します。spicyapi_generation_workflowはツールではなくプロンプトです。registerPromptで登録され、 goalと任意のmodelを受け取り、SPICYAPI_MCP_TOOLSには表示されません。ホストはMCPプロンプトを一覧表示する場所にこのプロンプトを表示します。

パラメーター

ツール	パラメーター（必須項目は太字）
spicyapi_service_status	なし
spicyapi_docs_search	query（デフォルトは ""）、limit（1～25、デフォルトは10）
spicyapi_models_list	modality（image / video / audio / text）、provider、task、search、includeSchema、includeExamples（どちらもデフォルトは false）
spicyapi_model_get	model
spicyapi_balance_get	なし
spicyapi_usage_get	from、to（YYYY-MM-DD、UTC）
spicyapi_tasks_list	from、to、state、model、limit（1～100、デフォルトは20）、cursor
spicyapi_task_get	taskId
spicyapi_task_wait	taskId、timeoutSeconds（1～300、デフォルトは60）、intervalSeconds（1～60、デフォルトは自動調整）
spicyapi_upload_file	path（絶対パス。Windowsでは ~/ と ~\ が展開されます）、contentType（拡張子がない場合、または拡張子が正しくない場合のみ）
spicyapi_download_url_create	taskId、key
spicyapi_task_quote	model、input、callBackUrl
spicyapi_task_create	model、input、callBackUrl、idempotencyKey、retentionSeconds
spicyapi_task_retry	taskId、idempotencyKey
spicyapi_task_purge	taskId
spicyapi_assets_list	kind（image / video / audio）、source（task_output / upload / url の配列）、query、favorite、collectionId、entityId、sort（recent / oldest / name / size）、cursor、limit（1～100、デフォルトは20）
spicyapi_assets_usage_get	なし
spicyapi_asset_save	taskId（index または key と組み合わせ）、path（contentType と組み合わせ）、url、fileId のいずれか1つのみ。name、idempotencyKey
spicyapi_asset_rename	assetId（ast_… または spicy://a/…）、name（1～80文字）
spicyapi_asset_delete	assetId
spicyapi_characters_list	assetId（このアセットを含むキャラクターのみ）、cursor、limit（1～100、デフォルトは20）
spicyapi_character_get	characterId
モデル入力スキーマは通常の JSON Schema として返されます。エージェントに届く前に、表示専用および料金表の注釈は取り除かれます。

spicyapi_task_create では、任意の retentionSeconds を指定して、そのタスクで生成されたメディア、結果ペイロード、プロンプト、その他の入力テキストの保持期間を短縮できます。保持期間を延長することはできません。0 を指定すると、タスクが終端状態に達した時点でそれらが削除されます。請求記録は常に保持されます。

任意の callBackUrl には、一般公開されている https:// アドレスを指定する必要があります。通常の http:// は拒否されます。また、localhost、プライベートネットワークアドレス、443 と 80 以外の明示的なポート、認証情報を含む URL も拒否され、いずれも 400 と Invalid callback URL を返します。配信本文にはプロンプトと結果への署名付きリンクが含まれるため、開発環境であっても http:// は例外なく拒否されます。

spicyapi_task_purge には destructiveHint: true が付与されており、終端状態にあるタスクの生成メディア、結果ペイロード、プロンプト、その他の入力テキストを削除します。削除されるのはコンテンツであり、費用の記録ではありません。台帳エントリ、請求額、モデル、状態、タイムスタンプ、リクエスト ID はすべて保持されるため、返金にはなりません。終端状態のタスクのみ受け付けます。受け付け済みのタスクはキャンセルできず、キャンセル API もありません。そのため、キュー待ちまたは実行中のタスクは、完了するまで待って（spicyapi_task_wait）、その後に削除してください。冪等性キーは不要です。タスク ID が冪等性キーとなるため、応答が失われた後に再実行すると、元の purgedAt が返され、変更は行われません。結果にはタスク ID、コンテンツの状態、削除メタデータのみが含まれます。リンク、チケット、出力キーは含まれません。破棄を報告する同じメッセージにコンテンツを取得する手段を残すと、削除の意味がなくなるためです。

支出の保護方法

課金対象のツールでは、プロトコルのエリシテーションと署名付きリクエスト状態を使用します。タスクの作成時には、正確な見積もりを取得して紐付けたうえで、USD の見積額と最大請求額を確認するよう求めます。エージェントがこの確認を回避することはできません。

• 質問はモデルではなく、ユーザーに提示されます。 クライアントが表示し、エージェントには回答する手段がありません。
• 回答は正確な引数に紐付けられます。 質問から回答までの間にモデル、入力、その他の引数が変更されると、呼び出しは confirmed request state does not match the current tool arguments で失敗し、何も作成されません。
• 拒否しても、作成、請求、削除は一切行われません。 確認を拒否またはキャンセルすると、何が起きたか、起きなかったかを示す operation declined; … が返されます。タスク作成の場合は、no task was created and no funds were reserved or charged (only the free price quote had been requested) となります。質問に表示された見積もりは、すでに取得されています。再試行と削除では、確認前にリクエストが送信されないため、最後に no SpicyAPI request was made が返されます。このサーバーでは、「エリシテーションの自動承認」設定をオフにしてください。
• エリシテーションがなければ、支出は発生しません。 フォームエリシテーションに対応していないクライアントは質問に回答できないため、無料見積もりの直後に作成は失敗し、作成も請求も行われません。
• 見積もりの有効期限は5分です。 その後に確認すると 40901 で失敗します。新しい見積もりを取得するため、もう一度依頼してください。
• 再試行の確認には価格が表示されません。 再試行すると、その時点でのモデル価格で新しいタスクが作成されます。金額を確認したい場合は、先に spicyapi_task_quote を使用してください。
• 復旧には同じ冪等性キーを使います。 確認画面にはキーが表示され、確認後に失敗した場合は、復旧のヒントとともにキーが返されます。spicyapi_task_create を、変更していないリクエストとその idempotencyKey を指定して再度呼び出すと、二重に請求されず、元のタスクが返されます。
• 失敗または期限切れのタスクには請求されず、保留額は自動的に解放されます。成功したタスクは、実際の使用量に基づいて精算され、精算額は受け付けた保留額を上限とします。受け付け済みのタスクはキャンセルできません。

モデル入力の準備ができたら、作成を直接呼び出してください。独立した価格比較には別の spicyapi_task_quote ツールを使用しますが、作成の前提条件ではありません。ヘルスチェックと残高チェックは任意の診断であり、タスクごとに必須のチェックリストではありません。

結果

spicyapi_task_get、spicyapi_task_wait、および検証済みの v2 Webhook には、すべて準備完了の output.assets[].url リンクが含まれます。そのまま使用してください。ストレージに API キーを送信しないでください。検証済みのコールバックが完了していれば、追加のタスク検索もダウンロードチケットも不要です。アセットが pending の場合やリンクの期限が切れている場合は、再度クエリしてください。spicyapi_download_url_create は、レガシー連携や明示的なリンク更新のために引き続き利用でき、署名付き URL の有効期間は 20 分です。

モデルによってはファイルではなく output.text で回答します。音声文字起こしはその典型例で、結果が単語になる通常の非同期タスクです。このようなモデルで output.assets が空なのは想定される形式であり、失敗ではありません。見つからないリンクを探すのではなく、テキストを返してください。文字起こしには、単語のタイミングと検出された言語を含む output.transcript が付く場合もあります。また、レイヤー分解では、output.assets[].layer.zIndex の順に積み重ねられた、レイヤーごとに 1 枚の画像が返されます。

spicyapi_task_wait はデフォルトで適応的にポーリングし、約 2 秒から開始して最大 10 秒まで間隔を延ばします。固定間隔にする場合のみ intervalSeconds を設定してください。待機時間はデフォルトで 60 秒、1 回の呼び出しにつき最大 300 秒に制限されます。ローカルのタイムアウトによって、受け付け済みのタスクがキャンセルされることはありません。

生成された成果物は最大で約 14 日間、プロンプトは 30 日間、アップロードは 1 日間保持されます。詳しくは保持と破棄をご覧ください。保存しておきたいものはコピーしてください。

使用状況レポート

spicyapi_usage_get では、YYYY-MM-DD 形式の from 日付と to 日付を任意で指定できます。この MCP プロセスに設定された API キーのみを対象にクエリします。ユーザー、キー、ワークスペースによる上書きはできません。

• UTC の期間は [from,to) で、最大 92 日間です。デフォルトでは、to は翌日の UTC、from はその 7 日前です。
• タスク数は、作成日とモデルごとに集計されます。
• totalSpend と各 spend は、確定済みの料金のみを対象とした正確な 10 進数の USD 文字列です。保留中の与信枠は除外され、決済が遅れると過去の日付の値が変わる場合があります。
• これは使用状況レポートであり、アカウント残高やキーの残予算ではありません。また、生成前に必要となることはありません。レポートのレート制限が適用された場合は、Retry-After に従ってください。

spicyapi_tasks_list は、再起動後やコールバックを受け取れなかった場合にタスクを検索します。入力、結果 URL、自動的な詳細リクエストを含まない、メタデータ 1 ページ分を返します。フィルターは from、to、state、model、limit、cursor です。ページをめくる間は UTC の日付を固定し、nextCursor は変更せずに渡してください。デフォルトの期間は翌日の UTC を終了日とする 7 日間で、最大 92 日間です。ページサイズは 20、上限は 100 です。cost が確定値となるのは settled が true の場合のみです。ステータスのポーリングや、生成の前提条件として履歴を使用しないでください。

このエンドポイントにはアカウント全体で共有される専用のレート制限枠があります。初回に 30 リクエストまで許可され、その後は 1 分ごとに 30 リクエスト分が補充されます。アカウント上のすべてのキーで共有されます。一般的な API レート制限とは異なり、この制限は障害時に閉じるため、制限機能が劣化している場合でもリクエストは拒否されます。ポーリングではなく、照合に使用してください。

ローカルファイル

spicyapi_upload_file はユーザーが指定した絶対パスを受け取り、ファイルを読み込み、このマシンからバイトデータをアップロードして、1 回の呼び出しでアップロードを確定し、モデル入力フィールドに設定する確定済みの spicy:// URI を返します。個別の確定ツールはありません。MCP 側で未完了のアップロードが保持されることはありません。チケットの取得、PUT、確定という分割ステップでのアップロードは SDK コードが担当し、commitUploadedFile で完了させます。画像（JPEG、PNG、WebP、GIF）は最大 10 MiB、MP4／WebM 動画と MP3／WAV 音声は最大 90 MiB、reference_file_url などのフィールドに指定する参照ドキュメント（PDF、Word、Excel、PowerPoint、Keynote、Pages、Numbers、プレーンテキスト、Markdown）は最大 90 MiB、loras[].path に指定する LoRA の重み（.safetensors）は最大 2 GiB です。コンテンツタイプは拡張子から判定されます。公開 HTTPS メディア URL はアップロード不要です。相対パスは拒否されます。先頭の ~/（Windows では ~\）はホームディレクトリに展開されます。拡張子が認識されない場合、何もアップロードされず、ツールが判定するすべての拡張子がエラーに列挙されます：gif、jpeg、jpg、png、webp、mp4、webm、mp3、wav、pdf、doc、docx、xls、xlsx、ppt、pptx、key、pages、numbers、txt、md、markdown、safetensors。

サーバーが読み取るのは、ユーザーのホームディレクトリ以下だけです。チェックの前にシンボリックリンクが解決されるため、許可されたルートの外を指すリンクは拒否されます。このガードはプロンプトインジェクション対策のためのものであり、サーバーを実行する人を制限するものではありません。メール、ウェブページ、タスクの説明に含まれて届いたパスは指示ではなくデータだからです。サーバーを実行する人は、もともと自分のファイルを読み取ることができます。

サーバーの env で SPICY_MCP_UPLOAD_ROOTS を設定すると、許可範囲を狭めたり広げたりできます。この変数を設定するとデフォルト設定は置き換えられます。エントリは PATH と同じ形式で区切ります。macOS と Linux では :、Windows では ; です。この変数では ~ は展開されないため、フルパスを指定してください。

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

Windows では、同じエントリを "SPICY_MCP_UPLOAD_ROOTS": "C:\\Users\\you\\Pictures;D:\\Renders" と記述します（JSON 内ではバックスラッシュを 2 つ重ねます）。存在しないルートは何にも一致しません。拒否メッセージには、有効なルートが列挙されます。

アセットライブラリ

アップロードの spicy:// URI は1日間有効です。キャラクターのポートレート、スタイルの参考画像、音声サンプルなど、再利用したいファイルは spicyapi_asset_save でアセットライブラリに保存できます。保存した各ファイルには spicy://a/<id> 形式の uri が割り当てられ、削除されるまで、同じワークスペースのキーを使って送信するモデル入力のあらゆるメディアフィールドで使用できます。エージェントは、その uri をタスク入力に直接指定するため、アップロードやダウンロードの手順は不要です。

設定済みの SPICY_API_KEY によって、利用するライブラリが決まります。個人用キーではユーザー個人のライブラリにアクセスでき、チームキーではそのチームの共有ライブラリにアクセスできます。チームキーの場合、作成者の現在のロールによって変更できる内容が決まります（owner と admin はすべての操作、developer は保存と名前変更、および自分が保存した項目のお気に入り登録や削除、billing と readonly は読み取りと利用のみ）。spicyapi_assets_usage_get は、この情報を scope として返します。

• spicyapi_asset_save は、次のうち1つだけを指定します：taskId（index または key とともに指定。デフォルトでは最初の出力）、path（絶対ローカルパス。spicyapi_upload_file と同じ SPICY_MCP_UPLOAD_ROOTS ガードのもとで読み取られます）、url、または fileId。必須の Idempotency-Key は自動的に追加されます。
• spicyapi_assets_list では、kind、source、名前の query、favorite、フォルダー（collectionId）、および1人のキャラクターの画像（entityId）で絞り込み、sort（デフォルトは recent、ほかに oldest、name、size）で並べ替えできます。デフォルトでは1ページあたり20件です。nextCursor を使って次のページに進む際は、同じ sort を指定してください（別の sort のカーソルを使うと 400 が返されます）。フォルダーとお気に入りは、ウェブアプリの「Assets」ページで管理します。各項目の previewUrl は最大20分間有効な非公開のプレビュー用署名付きURLです。表示には使えますが、保存しないでください。
• spicyapi_characters_list と spicyapi_character_get では、ウェブ上で作成した、名前付きで順序のある画像セットであるキャラクターを読み取れます。使用するには、エージェントがその画像の uri 値を順番どおりにモデルの参照画像フィールドに指定します。以前の spicy://p/<id> 形式のペルソナ参照も、個人用ライブラリに限り、引き続き同じ画像を参照します。不明なキャラクターの場合は 404 が返されます。
• spicyapi_asset_delete は、参照がすぐに無効になり、取り消しもできないため、毎回確認を求めます。
• ストレージは、個人用ライブラリとチームライブラリで共有される、所有者のライフタイム追加購入分によって利用可能になります。呼び出しが拒否されると、エラーJSONにサーバーの reason（例：asset_library_full、asset_daily_limit、asset_permission_denied）が返されます。spicyapi_assets_usage_get はプランと次のプランに必要な条件を説明し、scope.canTopUp が false の場合は追加購入額を表示しません。

アセットライブラリのガイドをご覧ください： お気に入りとフォルダー および キャラクター。

環境変数

変数	使用するエントリーポイント	意味
SPICY_API_KEY	両方のエントリーポイント	API キーです。ステータス確認とドキュメント検索を除くすべての機能で必須です
SPICY_MCP_UPLOAD_ROOTS	両方のエントリーポイント	spicyapi_upload_file と spicyapi_asset_save が読み取り可能なディレクトリ。: 区切り（Windows では ;）。デフォルトはホームディレクトリです
SPICY_MCP_HTTP_TOKEN	spicyapi-mcp-http	必須のベアラートークンです。32 バイト以上で、SPICY_API_KEY とは異なる必要があります
SPICY_MCP_HOST	spicyapi-mcp-http	127.0.0.1（デフォルト）、localhost、または ::1。それ以外は拒否されます
SPICY_MCP_PORT	spicyapi-mcp-http	ポートです。デフォルトは 8765 です
HTTPS_PROXY	両方のエントリーポイント	API 呼び出しをこのプロキシ経由で送信します。プロキシ経由の接続を参照してください

プロキシ経由の接続

ネットワークから HTTP プロキシ経由でインターネットに接続する場合は、サーバーの env ブロックに HTTPS_PROXY（必要に応じて NO_PROXY も）を設定してください。Node.js 22.21+ または 24+ では、サーバーが自動的にプロキシを使用します。Node.js 組み込みの fetch は、NODE_USE_ENV_PROXY=1 を指定して起動しない限りプロキシ変数を無視するため、サーバーは http:// または https:// のプロキシを検出すると、そのスイッチを有効にして一度だけ自身を再起動します。常に直接接続するには、NODE_USE_ENV_PROXY=0 を設定してください。

シェル環境に頼らず、env ブロックに設定してください。デスクトップアプリからはターミナルでエクスポートした変数が見えません。また、Codex が MCP サーバーに渡す環境変数は、固定された短いリストに限られます。

codex mcp add spicyapi \
  --env SPICY_API_KEY=$SPICY_API_KEY \
  --env HTTPS_PROXY=http://127.0.0.1:7890 \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

ターミナルの curl では使えてこのサーバーでは使えないプロキシがある場合、curl は API に接続できるのにサーバーが network request failed を報告するのが一般的です。その場合、エラーには設定されているものの使用されていないプロキシ変数が示されます。socks5:// プロキシはサポートされていません。

HTTP エントリーポイント

spicyapi-mcp-http はループバック上のみで Streamable HTTP を提供します。ほとんどのユーザーには上記の stdio エントリーポイントが適しています。URL で、すでに実行中のサーバーに接続するクライアントを使用する場合は、こちらを使ってください。

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

• MCP エンドポイントは /mcp で、Authorization: Bearer <SPICY_MCP_HTTP_TOKEN> が必要です。指定しない場合、サーバーは 401 を返します。
• GET /healthz は認証なしで {"ok":true} を返します。
• ループバック以外のアドレスでの起動、32 バイト未満のトークン、または SPICY_API_KEY と同じトークンは拒否されます。
• Host ヘッダーと Origin ヘッダーはローカルである必要があるため、他のサイト上のウェブページから操作することはできません。リクエスト本文の上限は 2 MiB です。

ループバックとは、同じコンピューター上のプログラムのみが接続できることを意味します。ネットワーク上の他のデバイスからは接続できません。

トラブルシューティング

症状	解決方法
クライアントに SpicyAPI のツールが表示されない	クライアントを完全に再起動します。JSON を検証し（コメントや末尾のカンマがないことを確認）、ファイルパスを確認します。node --version が 22.13 以降であることを確認します
npx: command not found / spawn npx ENOENT	nodejs.org から Node.js をインストールするか、which npx / where npx で確認した絶対パスを使います。Windows では、引数に /c npx … を指定して "command": "cmd" を試してください
could not determine executable to run	spicyapi-mcp の前に --package=@spicyapi/mcp を追加します
SPICY_API_KEY is required for authenticated API operations	キーがサーバーに届いていません。env ブロックを修正するか、キーをエクスポートしたシェルからサーバーを再追加します
HTTPS_PROXY is set, but this request did not use it	Node.js を 22.21+ または 24+ に更新するか、env ブロックに NODE_USE_ENV_PROXY=1 を追加します。プロキシ環境下を参照してください
401	キーの入力ミス、取り消し、または有効期限切れです。新しいキーを作成してください
40201 / 40202 / 40301	チャージします。キーの上限を引き上げるか、UTC のリセットを待つか、キーでモデルを許可します
40310	アカウントのメールアドレスを確認します。送信されたリンクを開くか、コンソールから新しいリンクを送信します
40003	アップロードされたバイト列がチケットと一致しません。spicyapi_upload_file を再度呼び出し、新しい spicy:// URI を使用します
40004	その設定の組み合わせに完全一致するデプロイメントがありません。メッセージで示されたパラメーターをモデルのスキーマに合わせて変更してください。単に再試行するだけでは解決しません
503	依存先が一時的に利用できません。Retry-After を待ってから、呼び出しを繰り返してください
50302	同期生成が上流で失敗し、すでに返金されています。同じリクエストを再送しても問題ありません
did not declare the required capability	クライアントはエリシテーションに対応していません。何も作成されておらず、課金もされていません（作成時に取得されたのは無料の見積もりだけです）。クライアントを更新するか、有料タスクには CLI を使ってください
confirmed request state does not match the current tool arguments	質問後にリクエストが変更されました。作成を最初からやり直してください
40901	見積もりの期限が切れたか、価格が変更されました。見積もりを取得して、再度確定してください
path must be absolute / no such file / may only read files under …	フルパスを指定し、ファイルが存在することを確認します。許可されたルートの下にファイルを移動してください
cannot tell the file type from its extension; …	ファイル名を一覧にある拡張子に変更するか、contentType を渡してください
operation declined; …	確認が拒否またはキャンセルされました。メッセージに、無料の見積もりのみがリクエストされたかどうかが示されています
task … did not reach a terminal state within …	タスクはまだ実行中です。再度待つか、後で状態を確認してください。キャンセルはされていません
API からのエラーには status、code、requestId が含まれます。サポートへの問い合わせに備えて、リクエスト ID は保管してください。すべてのコードについては
エラーを参照してください。

タスクの失敗と呼び出しの失敗は異なります。タスクの失敗では、state: "failed"、定義済みの値の中から設定される errorCode、および errorMessage が返されます。errorMessage はユーザーに伝えてください。モデルサービスから具体的な理由が示された場合は、サービス名、ホスト、URL、リクエスト ID、タスク ID、アカウント情報を削除したうえで、翻訳せず英語のまま引き継がれます。ただし、条件分岐には errorCode のみを使用してください。errorCode は文言や言語によって変わりません。

このサーバーが行わないこと

このサーバーはネイティブの非同期タスクを送信して追跡します。チャットトークンのストリーミングには対応しておらず、追加できるチャットツールもありません。カタログのテキストモデルは、互換レイヤーを通じて提供されます。互換レイヤーはすべて https://api.spicyapi.ai 配下にあり、POST /v1/chat/completions と POST /v1/responses（OpenAI）、POST /v1/messages（Anthropic）、POST /v1beta/models/{model}:generateContent（Google Gemini）を利用できます。すでにこれらのプロトコルのいずれかに対応しているクライアントは、ベース URL を SpicyAPI に向けるだけで利用できます。引用の確認とプラットフォームのイベントエンベロープが必要な場合は、ネイティブの jobs/stream を使用してください。詳しくはチャットストリーミングガイドを参照してください。

画像、動画、音声を読み取るテキストモデルには、これらのメディアをメッセージパーツとして渡します。spicyapi_upload_file が返す spicy://f/… URI を image_url、video_url、または audio_url パーツに指定してください（動画と音声のパーツは Chat Completions と jobs/stream で渡されます）。詳しくはテキストモデルへのメディアの送信を参照してください。

受け付け済みのタスクをキャンセルすることはできません。これが可能な公開 API はありません。また、請求確認に代わって回答することもありません。

詳細

• MCP ガイド：セットアップ、全ツール、料金、トラブルシューティング
• 開発者ハブのクライアント設定
• エージェントと自動化のガイド
• エージェントにも_正しいワークフロー_を理解させたい場合は、 @spicyapi/skillを追加してください。