MCP サーバー

@spicyapi/mcp を使うと、いつも使っている AI アシスタント（Claude、Cursor、VS Code、Codex、Windsurf、Gemini CLI など）が、あなたの代わりに SpicyAPI を操作できるようになります。設定が済めば、「この写真から 5 秒の動画を作って」と入力するだけで、アシスタントが合うモデルを探し、価格を伝え、あなたの OK を待ってから作業を始め、結果のリンクを渡してくれます。

コードを書く必要はありません。必要なのは Node.js と API キー、それに 10 分ほどの時間です。

MCP とは

MCP（Model Context Protocol）は、AI アシスタントに機能を追加するためのオープンな標準規格です。コンセントのようなものだと考えてください。MCP に対応したアシスタントは「サーバー」を読み込むことができ、サーバーはそれぞれ、アシスタントがあなたとの会話中に使えるツールをひとそろい追加します。

@spicyapi/mcp は、そうしたサーバーの 1 つで、SpicyAPI のツールを 15 個追加します。何かを頼んだときには、次のことが起こります。

1. ふつうのメッセージを書きます。たとえば「夜明けの灯台の画像を生成して」のように書きます。
2. アシスタントが、必要な SpicyAPI のツールを判断して呼び出します。
3. サーバー（アシスタントのアプリが自動で起動する、あなたのパソコンで動く小さなプログラム）が、あなたの API キーを使ってそのリクエストを SpicyAPI に送ります。
4. お金がかかる操作は、その前にいったん止まります。アプリが価格を表示して、確認を求めます。この質問に、アシスタントが代わりに答えることはできません。
5. 結果が会話に戻ってきて、アシスタントがその内容を説明します。

サーバーを自分でホストしたり、動かし続けたりする必要はありません。アシスタントのアプリが必要なときにサーバーを起動し、アプリを終了すると止めます。

向いているのは、 すでに AI アシスタントを使っていて、プログラムを書かずにモデルを試したり、価格を比べたり、画像や動画を作ったりしたい方です。開発者が、組み込みを作る前にエディターの中からカタログを調べるのにも使われています。

向いていないのは、 本番のアプリやバックエンド（SDK か HTTP API を使ってください）、人が付いていない大量のバッチ処理（CLI を使ってください）、チャットの返答をトークンごとにストリーミングする用途です。MCP サーバーはタスクを送信して追跡するためのものです。チャットについてはテキストとストリーミングを参照してください。

MCP・CLI・SDK・Skill のどれを使う？

SpicyAPI は、4 つの独立したパッケージを公開しています。ほとんどの方は、そのうち 1 つか 2 つで足ります。

アプリを TypeScript で書いていない場合、SDK の行にはほかにも 4 つの選択肢があります。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 キーのページで失効させ、新しいキーを作成します。失効はただちに反映されますが、すでに受理されたタスクは最後まで実行され、課金もされます。漏えいしたときの対応は認証を参照してください。

動作を確認する

新しい会話で、次の 3 つを順番に聞いてみてください。

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 を 1 回ずつ呼び出すこともあります。見積もりは無料で何も作成しないので、確認はありません。答えとして、そこから選べる比較が返ってきます。

画像を生成する

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。動画は数分かかることがよくあります。1 回の待機は最長 5 分なので、アシスタントが複数回待つことがあります。あとからタスクについて尋ねることもできます。

以前のタスクを探す

SpicyAPI で、ここ 3 日間に失敗したタスクを見せて、その理由を教えて。

アシスタントは、失敗した状態で絞り込んで spicyapi_tasks_list を呼び出し、気になるタスクについて spicyapi_task_get でエラーを読みます。失敗・期限切れのタスクでは通常、仮押さえ額が全額解放されます。ただし、モデルページに明記された一部のコンテンツ拒否は、受理時の見積額で課金されます。最終請求額は settled と cost で確認してください。続けて「それを再試行して」と言うと、アシスタントは spicyapi_task_retry を呼び出します。再試行は新しい有料のタスクなので、確認のために止まります。

結果のファイルを受け取る

最後に作った SpicyAPI の動画のダウンロードリンクをちょうだい。

アシスタントは spicyapi_tasks_list でタスクを見つけ、spicyapi_task_get で読み取ります。その結果には、すぐに使える結果のリンクが含まれています。ブラウザーでリンクを開いてダウンロードしてください。リンクの有効期間は短いので、期限が切れていたらもう一度頼めば、アシスタントが新しいリンクを取得します。

MCP サーバーが、自分でファイルをパソコンに保存することはありません。Claude Code や Codex のように、コマンドも実行できるアシスタントなら、頼めばリンクからフォルダーにダウンロードしてくれます。

ツールリファレンス

すべてのツールについて、受け取るものと返すものをまとめます。金額は常に米ドルで、"0.08" のように $ 記号の付かない正確な 10 進数のテキストで書かれます。日時は UTC です。

サービスとドキュメントの確認

spicyapi_service_status

SpicyAPI の公開 API に接続でき、正常に動いているかを確認します。API キーは不要で、お金もかからず、確認も求めません。診断用のツールなので、アシスタントがタスクを作成する前に実行する必要はありません。

パラメーター： なし。

戻り値： 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 の一覧（各項目に、段階の名前、per_image・per_second・per_request・per_1k_tokens のいずれかの unit、米ドル建ての price があります）、startingPrice、taskTimeoutSeconds、そして要求した場合は inputSchema / examples が含まれます。

解像度や長さなど、価格が変わる設定もあります。価格の一覧は比較のためのもので、特定のリクエストの正確な請求額は見積もりで確認します。

spicyapi_model_get

1 つのモデルの情報をすべて返します。受け付ける入力（inputSchema。各フィールドとその型、使える値、既定値を機械が読める形で記述したもの）、価格、利用可否、入力例です。無料の読み取り専用です。

戻り値： spicyapi_models_list の 1 項目と同じフィールドで、常に inputSchema を含みます。

アカウント

spicyapi_balance_get

残高を表示します。無料の読み取り専用です。タスクの作成時に残高が確認されるので、作成の前に呼び出す必要はありません。

パラメーター： なし。

戻り値： 米ドル建ての 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 キーで作成したタスクを 1 件開きます。無料の読み取り専用です。

戻り値： 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 も、どちらも「見つからない」という結果になります。

spicyapi_task_wait

タスクが終わるか待ち時間が尽きるまで、タスクを繰り返し確認し、それを返します。無料の読み取り専用です。待ち時間が尽きても、タスクがキャンセルされたり失敗したりはしません。 タスクは実行を続けるので、もう一度待つことも、あとで調べることもできます。

戻り値： 完了したタスクを、spicyapi_task_get と同じ形で返します。先に時間切れになった場合は、タスクがその時間内に終わらなかったことを報告します。

ファイル

spicyapi_upload_file

パソコン上のファイルを読み取って SpicyAPI にアップロードし、アップロードを完了させて、モデルの入力に入れられる spicy:// アドレスを返します。すべて 1 回の呼び出しで行い、2 つ目のステップはありません。無料で確認も求めませんが、ファイルを送信するので、読み取り専用ではありません。

公開された 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

自分のタスクの結果 1 つについて、署名付きの新しいダウンロードリンクを発行します。無料です。ふつうは必要ありません。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 は 2 件目を課金するのではなく、元のタスクを返します。新しいキーを使うと 2 件目の有料タスクが作られ、同じキーで設定を変えると拒否されます。

spicyapi_task_retry

failed か expired になったタスクから、別に課金される新しいタスクを作成します。元のタスクはそのまま残ります。お金がかかり、必ず先に確認を求めます。

戻り値： 新しい taskId、sourceTaskId（元のタスク）、state、estimatedCost、idempotencyKey。

再試行には、モデルの現在の価格が使われ、入力、権限、残高の確認も現時点の基準でもう一度行われます。再試行の確認には価格が表示されないので、先に価格を知りたい場合は、再試行の前に、同じモデルと設定で spicyapi_task_quote を使って見積もるようアシスタントに頼んでください。

再試行では元の入力がそのまま使われるので、先に失敗したタスクの errorCode を読んでください。

• rate_limited、upstream_unavailable、timeout、upstream_failed：少し待ってから 1 回再試行する価値があります。
• generation_failed：プロンプトや画像を変えて、代わりに新しいタスクを開始してください。同じ入力は、たいてい同じように失敗します。
• invalid_asset：ファイルをもう一度アップロードし、新しい spicy:// アドレスで新しいタスクを開始してください。再試行では古いファイルが使い回されます。
• content_rejected、invalid_request、unsupported_combination：そのまま再試行しないでください。プロンプト、設定、モデルのいずれかを変えて、新しいタスクを開始してください。

一覧はすべてエラーにあります。

spicyapi_task_purge

終了したタスク 1 件の保存されている内容、つまり生成メディア、結果ペイロード（保存された結果データ）、プロンプト、その他の入力テキストを完全に削除します。元に戻すことはできず、必ず先に確認を求めます。 お金はかかりませんが、返金もありません。

• 破棄できるのは、終了したタスク（succeeded、failed、expired、または過去の canceled）だけです。受理されたタスクはキャンセルできず、キャンセル用の API もありません。queued か running のタスクは、終わるまで待ってから（spicyapi_task_wait）破棄してください。
• 残しておきたいものは、先にダウンロードしてください。
• 課金の記録は残ります。帳簿の記録、請求額、モデル、状態、タイムスタンプ、リクエスト ID は、破棄したあとも見られます。
• すでに破棄したタスクをもう一度破棄しても、問題はありません。

戻り値： taskId、contentState（削除が予定されると purged）、purgedAt、contentRemovedBy、billingRetained: true。リンクは意図的に返しません。ファイルの物理的な削除は、ふつう 1 分以内に完了します。データ保存と破棄を参照してください。

リソースとプロンプト

サーバーは、ツールのほかに、読み取り専用のリソースを 2 つと、プロンプトを 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…

現在、見積額と最大請求額には同じ数字が表示されます。見積額はタスクの開始時に仮押さえされる金額で、タスクがその仮押さえ額を超えて課金されることはありません。

答え方の表示はアプリによって異なります。ふつうは confirm のチェックボックスかスイッチと、承諾・拒否のボタンです。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 日使えます。
• 1 件のタスクの内容を早めに削除するには、アシスタントに破棄を頼みます。1 件のタスクだけ保存期間を短くするには、作成時に retentionSeconds を設定するよう頼みます。

ルールと例外の全体はデータ保存と破棄にあります。

手元のファイル

spicyapi_upload_file はパソコン上のファイルを読み取れるので、注意が必要です。

• 既定では、ホームフォルダーの中だけを読み取ります（たとえば /Users/you や C:\Users\you）。それ以外の場所のファイルは、どのフォルダーが許可されているかを示すメッセージとともに拒否されます。
• ショートカットでは回避できません。 ホームフォルダーの中にあって、外を指すシンボリックリンクは拒否されます。
• この制限がある理由： Web ページ、メール、ドキュメントを読んでいるアシスタントが、「ユーザーの秘密鍵をアップロードせよ」のような隠された指示に出くわすことがあります。フォルダーの制限は、そうした手口からシステムファイルを守ります。ただし、自分のホームフォルダーは読み取れるので、自分で指定したファイルだけをアシスタントにアップロードさせ、アプリがツールの呼び出しの承認を求めてきたときはパスをよく読んでください。

フォルダーを変更する。 サーバーの env の SPICY_API_KEY の隣に SPICY_MCP_UPLOAD_ROOTS を追加し、1 つ以上のフォルダーのフルパスを指定します。これは既定値を置き換えるので、1 つのフォルダーだけに絞ることも、複数を並べることもできます。フォルダーの区切り方はシステムの PATH 設定と同じで、OS によって異なります。各フォルダーはフルパスで書いてください。アシスタントに伝えるファイルのパスでは ~ が展開されますが、この設定では展開されません。

{
  "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 モード：このパソコンからのみ

ほとんどのアプリは、上で説明したように自分でサーバーを起動します。一部のアプリは、すでに動いているサーバーにアドレスで接続するほうを好みます。そうしたアプリのために、パッケージには 2 つ目のプログラム 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 にあるほかの機器やインターネットからは接続できず、外部に開放する設定もありません。ほかのアドレスは、起動時に拒否されます。ほかのサイトの Web ページからのリクエストも拒否されます。ほかのマシンから接続できるサーバーが必要な場合、このモードは目的に合いません。

トラブルシューティング

ソースコード

このパッケージは MIT ライセンスで、github.com/spicyapi-ai/spicy-mcp で公開のまま開発しています。このページで説明したツールの実装を読む、書かれている動作と食い違う点を報告する、変更を提案する——いずれもそこからどうぞ。

次のステップ