SpicyAPI MCP Server

@spicyapi/mcp

SpicyAPI 的官方本地 MCP 服务，适用于 SpicyAPI。它让你已经在使用的 AI 助手——Claude Desktop、Claude Code、Codex、Cursor、VS Code、Windsurf、Gemini CLI 或任何 MCP 客户端——浏览实时模型目录、比较价格、创建生成任务并收集结果，每个计费步骤都会先由你确认。

SpicyAPI 是不受限制的 AI API：一个密钥即可使用 200+ 图像、视频、音频和聊天模型（Seedance、Kling、Wan、MiniMax、Seedream、GPT Image、Suno 等），平台不会添加内容过滤器。请求能生成什么取决于你选择的模型，目录会标明哪些模型不受内容限制。

此软件包会安装 spicyapi-mcp（stdio）和 spicyapi-mcp-http（仅限 loopback 的 Streamable HTTP）。它不包含 CLI 或 Agent Skill。

完整的新手友好指南：docs.spicyapi.ai/docs/mcp。

通俗地说，它能做什么

MCP（Model Context Protocol）是一种用于为 AI 助手扩展能力的开放标准。将此服务添加到你的助手后，你就可以用日常语言提出请求——“用这张照片制作一段五秒的视频”——助手会：

1. 在实时目录中找到合适的模型，并读取它接受的输入；
2. 如果有本地文件，则上传该文件；
3. 获取精确的美元报价，并在扣费前停下来征求你的确认；
4. 启动任务、等待完成，并提供结果链接。

此服务在你自己的电脑上运行。需要时由助手应用启动，无需托管。

要求

• Node.js 22.13 或更高版本（node --version）。npx 随 Node.js 一起提供。
• SpicyAPI API 密钥（见下文），以及用于支付任务费用的账户余额。浏览、报价和读取结果均免费。
• MCP 客户端。创建、重试和清除任务还需要支持 MCP 表单征询（elicitation）的客户端（这是协议中向用户提问的方式）。不支持该功能的客户端会让这三个工具返回错误，错误通常包含 did not declare the required capability。不会创建、预留、扣费或销毁任何内容：创建任务此时只获取了免费报价，重试和清除操作则尚未发送任何请求。只读工具仍可使用。

先获取密钥

1. 在 spicyapi.ai/register 创建账户——如果暂停注册，该页面会说明如何加入候补名单。
2. 在 API keys page 选择 Create key。将密钥命名为使用它的助手名称。在 Advanced 下，你可以设置每日上限、每月预算、终身上限、允许使用的模型、IP 允许列表和有效期；新密钥始终采用平台默认的每日上限，除非你输入 0 表示不设上限。
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 上静默等待，看起来像是卡住了。此外，二进制名称前必须加上 --package=@spicyapi/mcp，因为此软件包提供两个二进制文件；直接运行 npx @spicyapi/mcp 会因 could not determine executable to run 而失败。

Claude Desktop

1. 打开 Settings → Developer → Edit Config。在 macOS 上，文件路径为 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上，路径为 %APPDATA%\Claude\claude_desktop_config.json。
2. 粘贴下方代码块（或将 spicyapi 条目添加到现有的 mcpServers 中），并替换 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。不要使用 --scope project，因为它会将密钥写入仓库中的 .mcp.json。使用 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 桌面应用都会读取此文件——配置一次，三者都会使用。使用 codex mcp list 或 /mcp 检查。

这两条终端命令都会将当前 shell 中的 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 启动；按提示粘贴密钥，然后在 Agent 模式的 Chat 中使用这些工具。

其他 MCP 客户端

使用相同的 command、args 和 env。每个客户端都有自己的配置位置和格式，且二者会随版本变化——应以客户端自身的文档为准。

检查是否正常工作

按顺序向助手提问：

1. “检查 SpicyAPI 服务状态。”——spicyapi_service_status 无需密钥，因此可以验证服务是否启动。
2. “我的 SpicyAPI 余额是多少？”——spicyapi_balance_get 可以验证密钥是否已传递到服务。
3. “你有哪些 SpicyAPI 工具？”——应显示 22 个以 spicyapi_ 为前缀的工具。

这些操作都不会产生费用。

接下来试试实际任务

使用 SpicyAPI 列出我可以调用的图像模型，选择一个价格低廉的模型，生成一张电影感的夜间人像，并在完成后提供结果链接。

Agent 会读取目录、获取模型的架构、取得精确报价，并在产生任何费用前暂停等待你确认。

还可以试试这些提示词：

• “我的 SpicyAPI 余额是多少？本周花了多少？”——查询余额和用量，免费。
• “找出可以将图像转成视频的 SpicyAPI 模型，并比较使用每个模型生成 5 秒视频片段的费用。”——查询目录和报价，免费。
• “将 /Users/me/Desktop/portrait.jpg 转成一段 5 秒视频，镜头缓慢推进。”——上传文件，然后创建需确认的任务。
• “显示我过去三天失败的 SpicyAPI 任务，并说明失败原因。”——查看任务历史，免费；之后重试需要确认。
• “将我上一个任务的结果保存到我的 SpicyAPI 资源库，命名为 ‘Hero portrait’，然后用它作为生成 5 秒视频的起始图像。”——保存资源，然后创建需确认的任务。

模型 ID 始终取自实时目录。SpicyAPI 文档中的任何占位符，例如 MODEL_ID_FROM_CATALOG，都表示从该目录中选择的确切 ID，而不是字面值。

工具

工具	用途	只读	计费	确认
spicyapi_service_status	公开的健康状态和就绪状态；无需密钥	是	否	否
spicyapi_docs_search	搜索内置的第一方文档索引；无需密钥	是	否	否
spicyapi_models_list	已启用的模型和账户专属价格	是	否	否
spicyapi_model_get	单个模型及其当前输入架构	是	否	否
spicyapi_balance_get	可用、冻结和总余额	是	否	否
spicyapi_usage_get	当前密钥已结算的 USD 用量	是	否	否
spicyapi_tasks_list	当前密钥的一页任务元数据	是	否	否
spicyapi_task_get	读取一个任务，包括可用结果链接	是	否	否
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	销毁一个终止任务中存储的内容（destructiveHint）	否	否	始终
spicyapi_assets_list	一页已保存资源，每项均带有其 spicy://a/ 引用	是	否	否
spicyapi_assets_usage_get	资源存储方案、存储内容、今日计数和下一方案	是	否	否
spicyapi_asset_save	将任务输出、本地文件、URL 或上传内容保存到资源库	否	否	否
spicyapi_asset_rename	重命名已保存的资源；其引用保持不变	否	否	否
spicyapi_asset_delete	永久删除已保存的资源（destructiveHint）	否	否	始终
spicyapi_characters_list	一页角色，每个角色的图像均按顺序排列	是	否	否
spicyapi_character_get	单个角色及其图像，以 spicy://a/ 引用表示	是	否	否

该服务还注册了两个资源——spicyapi://docs/index 和 spicyapi://contract/openapi——以及一个提示词。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，默认值为 adaptive）
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 中恰好选择一项；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 的形式返回：在到达 Agent 之前，会剥离仅用于展示和费率卡的注释。

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、内容状态和删除元数据：不包含链接、票据或输出键，因为在报告内容已销毁的同一条消息中，若还留下获取内容的途径，就违背了清除的目的。

如何保护支出

计费工具使用协议引导和签名请求状态。创建任务时会获取并绑定准确报价，然后要求你确认其美元估算金额和最高扣款额。Agent 无法绕过这项确认。

• 问题会发送给用户，而不是模型。 客户端负责呈现问题；Agent 无法回答。
• 答案会绑定到确切的参数。 如果模型、输入或任何其他参数在提问和回答之间发生变化，调用就会失败，并返回 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 结束。请为此服务关闭任何“自动接受引导”的设置。
• 没有引导，就不会产生支出。 不支持表单引导的客户端无法回答问题，因此创建操作会在免费报价之后立即失败，不会创建任务或扣费。
• 报价有效期为五分钟。 超时后确认会失败，并返回 40901；请重新获取报价。
• 重试确认不包含价格。 重试会按模型当前价格创建新任务；如果需要了解金额，请先使用 spicyapi_task_quote。
• 恢复操作会复用幂等键。 确认信息中会显示该键，确认后若发生故障，响应中也会附带该键和恢复提示。再次使用相同的 idempotencyKey 和未更改的请求调用 spicyapi_task_create，会返回原任务，而不会再次扣费。
• 失败和过期的任务绝不会扣费；预留款会自动释放。成功任务按实际用量结算，但金额不超过已接受的预留款。已接受的任务无法取消。

模型输入准备好后，直接调用创建工具。单独的 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 排列。

默认情况下，spicyapi_task_wait 会自适应轮询，间隔从约两秒开始，逐渐延长至最多十秒。只有在需要固定间隔时才设置 intervalSeconds。等待时间默认最多为 60 秒，每次调用最多 300 秒；本地超时不会取消已受理的任务。

生成的成品最多保留约 14 天，提示词保留 30 天，上传内容保留一天——请参阅保留与销毁。请复制需要保留的内容。

使用情况报告

spicyapi_usage_get 可选接受 YYYY-MM-DD 格式的 from 和 to 日期。它只查询为此 MCP 进程配置的 API 密钥，不支持覆盖用户、密钥或工作区。

• UTC 日期范围为 [from,to)，最长 92 天。默认情况下，to 为明天（UTC），from 为其前七天。
• 任务数按创建日期和模型分组。
• totalSpend 和每项 spend 都是精确的 USD 十进制字符串，仅涵盖已结算费用；不包括待处理的预授权款项，延迟结算也可能更改较早日期的数据。
• 这是使用情况报告，不是账户余额或密钥剩余预算，生成内容前也无需查询。报告请求受到速率限制时，请遵循 Retry-After。

spicyapi_tasks_list 可在重启或漏收回调后查找任务。它每次返回一页元数据，不含输入和结果 URL，也不会自动请求任务详情。筛选项：from、to、state、model、limit、cursor。翻页期间请保持 UTC 日期不变，并原样传递 nextCursor。默认时间范围为截至明天（UTC）的前七天，最长 92 天；每页默认 20 条，最多 100 条。只有当 settled 为 true 时，cost 才是最终值。请勿使用历史记录轮询状态，也不要将其作为生成的前置条件。

此端点有独立的账户级限流桶：可突发请求 30 次，每分钟补充 30 次，账户中的所有密钥共享该限额。与通用 API 限制不同，该限流器故障时会拒绝请求。请将其用于核对，而非轮询。

本地文件

spicyapi_upload_file 会获取用户提供的绝对路径，读取文件，将字节从本机上传，并在一次调用中提交上传，然后返回已提交的 spicy:// URI，以便填入模型输入字段。没有单独的提交工具：MCP 端不会保留任何未完成的上传。分步上传（票据、PUT、提交）由 SDK 代码负责，并通过 commitUploadedFile 完成。最多 10 MiB 的图片（JPEG、PNG、WebP、GIF）；最多 90 MiB 的 MP4 / WebM 视频和 MP3 / WAV 音频；最多 90 MiB 的参考文档——PDF、Word、Excel、PowerPoint、Keynote、Pages、Numbers、纯文本和 Markdown——可用于 reference_file_url 等字段；LoRA 权重（.safetensors，最多 2 GiB）可用于 loras[].path。内容类型根据扩展名推断。公共 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 中的反斜杠需加倍）。不存在的根目录不会匹配任何内容；拒绝消息会列出当前生效的根目录。

素材库

上传内容的 spicy:// URI 有效期为一天。用户想重复使用的文件——角色肖像、风格参考图、语音样本——可以通过 spicyapi_asset_save 保存到素材库；每个已保存的文件都会获得一个格式为 spicy://a/<id> 的 uri，只要未删除，在使用同一工作区密钥发送的模型输入中的任何媒体字段里都可以使用。Agent 可将该 uri 直接放入任务输入，无需上传或下载。

已配置的 SPICY_API_KEY 决定使用哪个素材库：个人密钥访问用户的个人素材库，团队密钥访问该团队的共享素材库。使用团队密钥时，创建者的当前角色决定可以进行哪些更改（所有者和管理员可以进行任何操作；开发者可以保存和重命名，但只能收藏或删除自己保存的内容；计费和只读角色只能读取和使用）；spicyapi_assets_usage_get 会通过 scope 返回此信息。

• spicyapi_asset_save 只能接收一个来源：taskId（以及 index 或 key；默认使用第一个输出）、path（绝对本地路径，读取时受与 spicyapi_upload_file 相同的 SPICY_MCP_UPLOAD_ROOTS 防护机制限制）、url 或 fileId。系统会自动添加必需的 Idempotency-Key。
• spicyapi_assets_list 支持按 kind、source、名称 query、favorite、文件夹（collectionId）和某个角色的图片（entityId）筛选，并按 sort 排序（默认 recent，也可选 oldest、name、size），默认每页 20 条；使用相同的 sort 继续传入 nextCursor（使用其他排序方式的游标会返回 400）。文件夹和收藏项可在 Web 应用的素材页面管理。每项的 previewUrl 是有效期最长为 20 分钟的私有预览签名，可用于展示，但绝不要存储。
• spicyapi_characters_list 和 spicyapi_character_get 可读取角色：这些角色是在 Web 上创建的、带名称且按顺序排列的图片集。要使用某个角色，Agent 需按顺序将其图片的 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	必需的 Bearer 令牌，至少 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 代理连接互联网，请将 HTTPS_PROXY（以及需要时的 NO_PROXY）放入服务的 env 块中。在 Node.js 22.21+ 或 24+ 上，服务会自动使用这些变量。除非使用 NODE_USE_ENV_PROXY=1 启动，否则 Node.js 内置的 fetch 会忽略代理变量，因此当服务发现 http:// 或 https:// 代理时，会自动重启一次并启用该开关。设置 NODE_USE_ENV_PROXY=0 可始终直接连接。

请将变量放入 env 块，而不要依赖 Shell 环境。桌面应用无法读取你在终端中导出的变量，而且 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 块，或在已导出密钥的 shell 中重新添加服务
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	客户端不支持 elicitation；未创建任何内容，也未扣费（创建操作只获取了免费报价）。请更新客户端，或使用 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 进行分支处理，因为它不会随措辞或语言而变化。

此服务不提供的功能

它会提交并跟踪原生异步任务；它不会流式传输聊天 Token，也没有可添加的聊天工具。目录中的文本模型由兼容层提供服务，具体接口为 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 指南：设置、所有工具、费用和故障排除
• 开发者中心的客户端设置
• Agent 与自动化指南
• 想让 Agent 也了解_正确的工作流_？请添加 @spicyapi/skill。