@spicyapi/mcp

@spicyapi/mcp

The official local MCP server for SpicyAPI. It lets the AI assistant youalready use — Claude Desktop, Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI or any MCPclient — browse the live model catalog, compare prices, create generation tasks and collect results,with every billable step confirmed by you.

SpicyAPI is an unrestricted AI API: one key for 200+ image, video, audio and chat models (Seedance,Kling, Wan, MiniMax, Seedream, GPT Image, Suno and more), with no content filter added by theplatform. What a request can produce depends on the model you pick, and the catalog marks whichmodels are uncensored.

This package installs spicyapi-mcp (stdio) and spicyapi-mcp-http (loopback-only StreamableHTTP). It does not contain the CLI or the Agent Skill.

Full, beginner-friendly guide: docs.spicyapi.ai/docs/mcp.

What it does, in plain words

MCP (Model Context Protocol) is an open standard for giving AI assistants extra abilities. Once thisserver is added to your assistant, you can ask in ordinary language — "make a five-second videofrom this photo" — and the assistant:

1. finds a suitable model in the live catalog and reads what it accepts;
2. uploads your local file if there is one;
3. gets an exact USD quote and stops to ask you before anything is charged;
4. starts the task, waits for it and gives you the result link.

The server runs on your own computer. Your assistant app starts it when needed; there is nothing tohost.

Requirements

• Node.js 22.13 or later (node --version). npx ships with Node.js.
• A SpicyAPI API key (below), and funds on the account for paid tasks. Browsing, quoting andreading results are free.
• An MCP client. Creating, retrying and purging tasks additionally require a client thatsupports MCP form elicitation (the protocol's way of asking the user a question). In a clientwithout it those three tools return an error, usually containingdid not declare the required capability. Nothing is created, reserved, charged or destroyed:creation has fetched only its free quote by then, and retry and purge have sent no request. Theread-only tools still work.

Get a key first

1. Create an account at spicyapi.ai/register — if sign-ups arepaused, that page shows how to join the waitlist.
2. On the API keys page choose Create key. Name it after theassistant that will use it. Under Advanced you can set a daily cap, monthly budget, lifetimecap, allowed models, IP allowlist and expiry; new keys always get the platform's default dailycap unless you enter 0 for no cap.
3. Copy the key. It starts with sk-spicy- and is shown once.
4. For the terminal-based setups below, export it in the terminal you will run the setup commandfrom:

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

In Windows PowerShell: $env:SPICY_API_KEY = "sk-spicy-...".

Add it to your client

Every client below runs the same stdio server: npx --yes --package=@spicyapi/mcp spicyapi-mcp.

You never run this server yourself — your MCP client starts it. Launched by hand it just waitssilently on stdin, which looks like a hang. And it needs --package=@spicyapi/mcp in front of thebinary name, because this package ships two of them; plain npx @spicyapi/mcp fails withcould not determine executable to run.

Claude Desktop

1. Open Settings → Developer → Edit Config. The file is~/Library/Application Support/Claude/claude_desktop_config.json on macOS and%APPDATA%\Claude\claude_desktop_config.json on Windows.
2. Paste the block below (or add the spicyapi entry to an existing mcpServers) and replaceYOUR_SPICY_API_KEY.
3. Quit Claude Desktop completely and reopen it — it reads this file only at launch.

{
  "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

The default scope is the current project; add --scope user for every project. Do not use--scope project, which writes the key into a .mcp.json inside the repository. Check withclaude mcp list or /mcp. On native Windows, if the server fails to start, use-- 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

That writes ~/.codex/config.toml, which the Codex CLI, the IDE extension and the ChatGPT desktopapp all read — configure it once and all three pick it up. Check with codex mcp list or /mcp.

Both terminal commands copy SPICY_API_KEY out of your current shell into that client's localconfig, so run them in a terminal where the key is already exported. If it was not, remove theserver (claude mcp remove spicyapi / codex mcp remove spicyapi) and add it again.

Cursor, Windsurf and Gemini CLI

Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and GeminiCLI (~/.gemini/settings.json) share the same shape as Claude Desktop:

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

On Windows these live under %USERPROFILE%. If a file already has other settings, mergemcpServers into it — the whole file must stay valid JSON, with no comments or trailing commas.Restart the client if the tools do not appear (Gemini CLI: /mcp lists them).

Those are user-level files outside your repository. Never copy that block, with a real key in it,into a project file that gets committed — such as a project-level .cursor/mcp.json.

VS Code

.vscode/mcp.json is committed with your repository, so let VS Code prompt for the key and keep itin its own secret storage:

{
  "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}" }
    }
  }
}

Start it from the code lens above the entry or MCP: List Servers, paste the key when asked, thenuse the tools from Chat in Agent mode.

Any other MCP client

Use the same command, args and env. Each client owns its config location and format, and bothchange between versions — their own documentation is authoritative.

Check that it works

Ask your assistant, in order:

1. "Check the SpicyAPI service status." — spicyapi_service_status needs no key, so this provesthe server starts.
2. "What is my SpicyAPI balance?" — spicyapi_balance_get proves the key reaches the server.
3. "Which SpicyAPI tools do you have?" — expect 22 tools prefixed spicyapi_.

None of these costs anything.

Then ask for something real

Use SpicyAPI to list the image models I can call, pick an inexpensive one, generate a cinematicnight portrait, and give me the result link when it finishes.

The agent reads the catalog, fetches the model's schema, obtains an exact quote and stops for yourconfirmation before anything is charged.

More prompts to try:

• "How much SpicyAPI balance do I have, and what did I spend this week?" — balance and usage,free.
• "Find SpicyAPI models that turn an image into a video and compare what a 5-second clip costs oneach." — catalog plus quotes, free.
• "Turn /Users/me/Desktop/portrait.jpg into a 5-second video with a slow push-in." — upload, thena confirmed task.
• "Show my SpicyAPI tasks from the last three days that failed, and why." — task history, free; aretry afterwards asks for confirmation.
• "Save the result of my last task to my SpicyAPI asset library as 'Hero portrait', then use it asthe starting image for a 5-second video." — a saved asset, then a confirmed task.

Model IDs always come from the live catalog. Any placeholder such as MODEL_ID_FROM_CATALOG inSpicyAPI documentation means an exact ID selected from that catalog, not a literal value.

Tools

The server also registers two resources — spicyapi://docs/index and spicyapi://contract/openapi— and one prompt. spicyapi_generation_workflow is a prompt, not a tool — it is registered withregisterPrompt, takes goal and an optional model, and does not appear in SPICYAPI_MCP_TOOLS.Hosts surface it wherever they list MCP prompts.

Parameters

Model input schemas are returned as plain JSON Schema: display-only and rate-card annotations arestripped before they reach the agent.

spicyapi_task_create accepts an optional retentionSeconds that shortens how long that one task'sgenerated media, result payload, prompt and other input text are kept; it can never extend them, 0removes them once the task reaches a terminal state, and billing records are always kept.

Its optional callBackUrl must be a public https:// address. Plain http:// is refused, and soare localhost, private network addresses, explicit ports other than 443 and 80, and URLs carryingcredentials; each returns 400 with Invalid callback URL. http:// has no development exceptionbecause the delivery body carries the prompt and signed links to the result.

spicyapi_task_purge is annotated destructiveHint: true and removes a terminal task's generatedmedia, result payload, prompt and other input text. It destroys content, not the record of what itcost — the ledger entry, charged amount, model, state, timestamps and request ID all survive — so itis never a refund. Only terminal tasks are accepted. An accepted task cannot be canceled and thereis no cancellation API, so for a queued or running task, wait until it finishes(spicyapi_task_wait), then purge it. It takes no idempotency key, because the task ID is theidempotency key: a repeat after a dropped response returns the original purgedAt and changesnothing. Its result carries only the task ID, content state and removal metadata: no links, ticketsor output keys, because leaving a way to fetch the content in the same message that reports itsdestruction would defeat the point.

How spending is protected

Billable tools use protocol elicitation and signed request state. Task creation fetches and bindsthe exact quote, then asks you to confirm its USD estimate and maximum charge. An agent cannotbypass that confirmation.

• The question goes to the user, not the model. The client renders it; the agent has no way toanswer it.
• The answer is bound to the exact arguments. If the model, input or any other argument changesbetween the question and the answer, the call fails withconfirmed request state does not match the current tool arguments and nothing is created.
• Declining creates, charges and destroys nothing. A declined or cancelled confirmation returnsoperation declined; … with what did and did not happen. For task creation that isno task was created and no funds were reserved or charged (only the free price quote had been requested)— the quote shown in the question was already fetched. Retry and purge send no request beforeconfirmation, so theirs ends in no SpicyAPI request was made. Leave any "auto-acceptelicitation" setting off for this server.
• No elicitation, no spending. A client without form elicitation cannot answer the question, socreation fails right after the free quote and nothing is created or charged.
• Quotes last five minutes. Confirming after that fails with 40901; ask again for a freshquote.
• Retry confirmations carry no price. A retry is a new task at the model's current price; usespicyapi_task_quote first if you want the number.
• Recovery reuses the idempotency key. The confirmation shows it, and a failure afterconfirmation returns it with a recovery hint. Calling spicyapi_task_create again with thatidempotencyKey and the unchanged request returns the original task instead of a second charge.
• Failed and expired tasks are never charged; the hold is released automatically. A successful tasksettles on actual usage, capped at the accepted hold. Accepted tasks cannot be cancelled.

Call creation directly once the model input is ready. The separate spicyapi_task_quote tool is forindependent price comparisons, not a prerequisite. Health and balance checks are optionaldiagnostics, not a per-task checklist.

Results

spicyapi_task_get, spicyapi_task_wait and verified v2 webhooks all include readyoutput.assets[].url links. Use them directly — never send the API key to storage. A completeverified callback needs no extra task lookup and no download ticket. Query again for pendingassets or expired links; spicyapi_download_url_create remains available for legacy integrationsand explicit link renewal, and its signed URL lasts 20 minutes.

Some models answer in output.text rather than with a file — audio transcription is the plain case,an ordinary asynchronous task whose result is words. An empty output.assets on such a model is theexpected shape, not a failure, so report the text instead of looking for a missing link. Atranscription may also carry output.transcript with word timings and the detected language, andlayer decomposition returns one image per layer, stacked by output.assets[].layer.zIndex.

spicyapi_task_wait polls adaptively by default, starting at about two seconds and backing off toat most ten. Set intervalSeconds only for a fixed interval. Waiting is bounded to 60 seconds bydefault and 300 at most per call; a local timeout does not cancel the accepted task.

Generated artefacts are kept for about 14 days at most, prompts for 30 days, uploads for one day —see Retention and destruction. Copy anything you want tokeep.

Usage reports

spicyapi_usage_get takes optional from and to dates in YYYY-MM-DD. It queries only the APIkey configured for this MCP process — there is no user, key or workspace override.

• UTC range [from,to), up to 92 days. By default to is tomorrow UTC and from is seven daysearlier.
• Task counts are grouped by creation day and model.
• totalSpend and each spend are exact decimal USD strings covering settled charges only; pendingholds are excluded and late settlement can change earlier days.
• This is a usage report, not account balance or remaining key budget, and is never required beforegenerating. Observe Retry-After when reporting is rate limited.

spicyapi_tasks_list finds tasks after a restart or a missed callback. It returns one page ofmetadata with no inputs, no result URLs and no automatic detail requests. Filters: from, to,state, model, limit, cursor. Keep the UTC dates fixed while paging and pass nextCursorunchanged. Default window seven days ending tomorrow UTC, 92 days maximum; page size 20, cappedat 100. cost is final only when settled is true. Do not use history for status polling or as aprerequisite to generation.

This endpoint has its own account-wide bucket: a burst of 30 requests, refilling 30 per minute,shared by every key on the account. Unlike the general API limit it fails closed, so it stillrejects when the limiter is degraded. Use it for reconciliation, not polling.

Local files

spicyapi_upload_file takes the absolute path the user gave, reads the file, uploads the bytes fromthis machine and commits the upload in one call, then returns the committed spicy:// URI to put ina model input field. There is no separate commit tool: nothing on the MCP side ever holds ahalf-finished upload. Split-step uploads (ticket, PUT, commit) belong to SDK code, which finishesthem with commitUploadedFile. Images (JPEG, PNG, WebP, GIF) up to 10 MiB; MP4 / WebM video and MP3/ WAV audio up to 90 MiB; reference documents up to 90 MiB — PDF, Word, Excel, PowerPoint, Keynote,Pages, Numbers, plain text and Markdown — for fields such as reference_file_url; LoRA weights(.safetensors, up to 2 GiB) for loras[].path. Content type is inferred from the extension.Public HTTPS media URLs need no upload. Relative paths are refused; a leading ~/ (and ~\ onWindows) is expanded to the home directory. If the extension is not recognised, nothing is uploadedand the error lists every extension the tool infers: gif, jpeg, jpg, png, webp, mp4,webm, mp3, wav, pdf, doc, docx, xls, xlsx, ppt, pptx, key, pages, numbers,txt, md, markdown, safetensors.

The server reads only under the user's home directory. Symlinks are resolved before the check, so alink pointing out of an allowed root is refused. The guard exists for prompt injection — a path thatarrives inside an email, a web page or a task description is data, not an instruction — not torestrict the person running the server, who can already read their own files.

Set SPICY_MCP_UPLOAD_ROOTS in the server's env to narrow or widen that; it replaces the default.Entries are separated like PATH: : on macOS and Linux, ; on Windows. ~ is not expandedin this variable, so write full paths.

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

On Windows the same entry reads "SPICY_MCP_UPLOAD_ROOTS": "C:\\Users\\you\\Pictures;D:\\Renders"(backslashes doubled inside JSON). A root that does not exist matches nothing; the refusal messagelists the roots in effect.

Asset library

An upload's spicy:// URI lasts one day. Files the user wants to reuse — a character portrait, astyle reference, a voice sample — can be saved to the asset library with spicyapi_asset_save; eachsaved file gets a uri of the form spicy://a/<id> that works in any media field of model inputssent with keys of the same workspace, until it is deleted. The agent puts that uri straight intothe task input, with no upload or download step.

The configured SPICY_API_KEY decides the library: a personal key reaches the user's personallibrary, a team key that team's shared library. With a team key, the creator's current role decideswhat may change (owner and admin anything; developer saves and renames, favorites or deletes onlywhat they saved; billing and readonly only read and use); spicyapi_assets_usage_get returns thisas scope.

• spicyapi_asset_save takes exactly one source: taskId (with index or key; the first outputby default), path (an absolute local path, read under the same SPICY_MCP_UPLOAD_ROOTS guard asspicyapi_upload_file), url, or fileId. The required Idempotency-Key is added for you.
• spicyapi_assets_list filters by kind, source, a name query, favorite, a folder(collectionId) and one character's images (entityId), and orders by sort (recent bydefault, oldest, name, size), 20 per page by default; follow nextCursor with the samesort (a cursor from another sort gets 400). Folders and favorites are managed on the Assetspage of the web app. Each item's previewUrl is a private preview signed for at most 20 minutes —fine to show, never to store.
• spicyapi_characters_list and spicyapi_character_get read characters: named, ordered sets ofimages created on the web. To use one, the agent puts its images' uri values, in order, into themodel's reference image field. Older spicy://p/<id> persona references still resolve to the sameimages, in the personal library only. An unknown character is a 404.
• spicyapi_asset_delete asks for confirmation every time, because the reference stops working atonce and there is no undo.
• Storage unlocks with the owner's lifetime top-ups, shared by their personal and team libraries. Arefused call returns the server's reason (for example asset_library_full, asset_daily_limitor asset_permission_denied) in the error JSON; spicyapi_assets_usage_get explains the plan andwhat the next one takes, and leaves out the top-up amounts when scope.canTopUp is false.

See the asset library guide:favorites and folders andcharacters.

Environment variables

Behind a proxy

If your network reaches the internet through an HTTP proxy, put HTTPS_PROXY (and NO_PROXY, ifyou need it) in the server's env block. The server uses it on its own on Node.js 22.21+ or 24+.Node.js's built-in fetch ignores proxy variables unless it was started withNODE_USE_ENV_PROXY=1, so when the server finds an http:// or https:// proxy it restarts itselfonce with that switch on. Set NODE_USE_ENV_PROXY=0 to always connect directly.

Put it in the env block rather than relying on your shell. Desktop apps do not see the variablesyou export in a terminal, and Codex passes only a short fixed list of them to MCP servers:

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

A proxy that curl in your terminal uses and this server does not is the usual reason curlreaches the API while the server reports network request failed. Errors then say so: they name theproxy variable that was set and not used. socks5:// proxies are not supported.

HTTP entrypoint

spicyapi-mcp-http serves Streamable HTTP on loopback only. Most users want the stdio entrypointabove instead; use this for a client that connects to an already-running server by 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

• The MCP endpoint is /mcp and requires Authorization: Bearer <SPICY_MCP_HTTP_TOKEN>; without itthe server answers 401.
• GET /healthz returns {"ok":true} without authentication.
• It refuses to start on a non-loopback address, with a token shorter than 32 bytes, or with a tokenequal to SPICY_API_KEY.
• Host and Origin headers must be local, so web pages on other sites cannot drive it; request bodiesare capped at 2 MiB.

Loopback means only programs on the same computer can connect — not other devices on the network.

Troubleshooting

Errors from the API carry status, code and requestId; keep the request ID for support. SeeErrors for every code.

A failed task is different from a failed call: it comes back with state: "failed", an errorCodefrom a closed set, and an errorMessage. Relay errorMessage to the user — when the model servicegave a specific reason it is passed through in English, untranslated, with service names, hosts,URLs, request and task IDs and account details removed — but branch only on errorCode, which doesnot change with the wording or the language.

What this server does not do

It submits and tracks native asynchronous tasks; it does not stream chat tokens, and it has no chattool to add. The catalogue's text models are served by the compatible layers instead —POST /v1/chat/completions and POST /v1/responses (OpenAI), POST /v1/messages (Anthropic) andPOST /v1beta/models/{model}:generateContent (Google Gemini), all under https://api.spicyapi.ai —so a client that already speaks one of those protocols only needs its base URL pointed at SpicyAPI.Use native jobs/stream when you need quote confirmation and the platform event envelope — see thechat streaming guide.

Text models that read images, video or audio take them as message parts, and the spicy://f/… URIfrom spicyapi_upload_file is what goes in an image_url, video_url or audio_url part (videoand audio parts are carried by Chat Completions and jobs/stream) — seesending media to a text model.

It cannot cancel an accepted task — no public API can — and it never answers a billing confirmationon your behalf.

More

• MCP guide: setup, every tool, costs and troubleshooting
• Client setup on the developer hub
• Agents and automation guide
• Want the agent to also know the correct workflow? Add@spicyapi/skill.