SpicyAPI MCP

@spicyapi/mcp

The official local MCP server for SpicyAPI. It lets the AI assistant you already use — Claude Desktop, Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI or any MCP client — 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 the platform. What a request can produce depends on the model you pick, and the catalog marks which models are uncensored.

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

Full, beginner-friendly guide: [docs.spicyapi.ai/docs/mcp](https://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 this server is added to your assistant, you can ask in ordinary language — _"make a five-second video from 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 to host.

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 and reading results are free.
• An MCP client. Creating, retrying and purging tasks additionally require a client that supports MCP form elicitation (the protocol's way of asking the user a question). In a client without it those three tools return an error, usually containing did 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. The read-only tools still work.

Get a key first

1. Create an account at spicyapi.ai/register — if sign-ups are paused, that page shows how to join the waitlist.
2. On the API keys page choose Create key. Name it after the assistant that will use it. Under Advanced you can set a daily cap, monthly budget, lifetime cap, allowed models, IP allowlist and expiry; new keys always get the platform's default daily cap 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 command from:

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 waits silently on stdin, which looks like a hang. And it needs --package=@spicyapi/mcp in front of the binary name, because this package ships two of them; plain npx @spicyapi/mcp fails with could 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 replace YOUR_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 with claude 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 desktop app 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 local config, so run them in a terminal where the key is already exported. If it was not, remove the server (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 Gemini CLI (~/.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, merge mcpServers 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 it in 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, then use 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 both change 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 proves the 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 cinematic

night 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 your confirmation 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 on each."_ — catalog plus quotes, free.
• _"Turn /Users/me/Desktop/portrait.jpg into a 5-second video with a slow push-in."_ — upload, then a confirmed task.
• _"Show my SpicyAPI tasks from the last three days that failed, and why."_ — task history, free; a retry afterwards asks for confirmation.
• _"Save the result of my last task to my SpicyAPI asset library as 'Hero portrait', then use it as the 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 in SpicyAPI documentation means an exact ID selected from that catalog, not a literal value.

Tools

The server also registers two resources — `s