Skip to main content

MCP & agents

Let your AI assistant make images and video

The official MCP server gives Claude, Cursor, Codex, VS Code and other assistants the live model catalog, exact quotes and task creation. You ask in plain words, it stops for your confirmation before anything is charged.

Create an API keyFull guide in the docs

What is an MCP server?

MCP (Model Context Protocol) is a standard way to give an AI assistant new tools. Add the SpicyAPI server and your assistant can browse models, check prices and create images or video for you.

  1. You and your assistantClaude, Cursor, Codex, VS Code…
  2. SpicyAPI MCP serverRuns on your computer through npx
  3. Image and video modelsLive catalog, exact prices
The assistant decides which tool to call. Anything that costs money stops and waits for your yes.

Good for

  • Assets while you codeAsk for a hero image or product clip without leaving the editor.
  • Exploring modelsAsk which model fits a job and what it will cost.
  • Hands-free batchesLet the agent create, wait for and collect several tasks.

What happens when you ask

  1. Step 1Finds a suitable model in the live catalog and reads what it accepts
  2. Step 2Uploads your local file, if there is one
  3. Step 3Gets an exact quote in US dollars and asks you before anything is charged
  4. Step 4Starts the task, waits for it and hands you the result link
Example session

  1. You: Turn beach.jpg into a six-second clip of waves at sunset.

  2. spicyapi_models_listspicyapi_model_get
    Assistant: Found a video model that accepts a start image
  3. spicyapi_upload_file
    Uploaded beach.jpg
  4. spicyapi_task_quote

    Here is the exact price in US dollars. Create the task?

  5. spicyapi_task_createspicyapi_task_wait
    Done. Here is your download link.
Illustration of a typical session. Nothing is charged until you approve.

Add it to your assistant

Every client runs the same local server through npx. Pick yours for the exact command or config block.

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

One stdio server for every MCP client. Put the block in that client’s own config file.

Third-party clients change their config formats between versions. If a snippet here stops matching, the client's own documentation wins.

Using Claude? Generate images and video from Claude →

Tools it exposes

Read-only tools are free. The two tools that spend money, and the one that deletes content, always ask you first.

FreeFree and read-only12

  • spicyapi_service_statusPublic health check, no key needed
  • spicyapi_docs_searchSearch the bundled documentation
  • spicyapi_models_listEnabled models and your prices
  • spicyapi_model_getOne model and its input schema
  • spicyapi_balance_getAvailable, held and total balance
  • spicyapi_usage_getWhat the current key has spent
  • spicyapi_tasks_listRecent tasks for the current key
  • spicyapi_task_getOne task, with ready result links
  • spicyapi_task_waitWait up to 5 minutes for a task to finish
  • spicyapi_task_quotePrice an exact request without creating it
  • spicyapi_upload_fileUpload a local file to use as input
  • spicyapi_download_url_createA fresh download link for a result

Asks before chargingAsks before it runs3

  • spicyapi_task_createStart a generation task
  • spicyapi_task_retryRun a failed or expired task again
  • spicyapi_task_purgePermanently delete a finished task's content
Open packageView source

Add the Agent Skill for the call order

The MCP server gives the agent abilities; the Agent Skill tells it how to use them: read the schema, confirm the quote, reuse one idempotency key per attempt. Claude Code and Codex support both.

Open packageView source
npx skills add spicyapi-ai/spicy-skill \
  --agent claude-code

Files your agent can read

These files help assistants and integration tools find the product description, model catalogue, and canonical documentation.

agent.md

Compact agent integration contract and safety boundaries.

/agent.md →

llms.txt

Curated site and model index for AI retrieval.

/llms.txt →

llms-full.txt

Extended product, workflow, endpoint, and discovery context.

/llms-full.txt →

Agent manifest

Structured JSON discovery for tools and autonomous clients.

/api/agent →

Fix common errors

Most first-time problems are one of these three. Each card shows what you see and the one thing to change.

  • tools

    Tools don't show up

    Restart the assistant after editing its config, and check that the JSON is valid.

  • key

    Missing API key

    Put SPICY_API_KEY in the env block of the server's config. Desktop apps don't see a key you exported in your shell.

  • ask

    Can't create tasks

    Your client can't show confirmation prompts. Free tools still work; use a client that supports MCP elicitation to create tasks.

Questions people ask