MCP Tools Reference

Every tool the MCP server exposes. Tool names reach the model prefixed by client convention — in Claude Code, generate_image appears as mcp__modelstack__generate_image.

Chat#

list_models#

No parameters. Returns every chat model ID available to your key.

{ "models": ["claude-opus-5", "claude-haiku-4-5", "gpt-5.4", "…"] }

llm_chat#

Sends a chat completion and returns the reply as plain text. Useful for handing bulk or low-stakes work to a cheaper model than the calling agent runs on.

{
  "model": "claude-haiku-4-5",
  "text": "…",
  "finish_reason": "stop",
  "usage": { "prompt_tokens": 26, "completion_tokens": 3, "total_tokens": 29 }
}

Media generation#

list_generation_models#

Returns each model with its variants, the parameters that variant accepts, and its floor price:

{
  "models": [
    {
      "model": "google/nano-banana-2",
      "display_name": "Nano Banana 2",
      "family": "google",
      "variants": [
        {
          "generation_type": "TEXT_TO_IMAGE",
          "supported_params": ["prompt", "aspect_ratio", "resolution", "output_format"],
          "min_price_usd": 0.08
        }
      ]
    }
  ]
}

generate_image / generate_video / generate_audio#

All three take the same shape and return a job_id immediately.

{
  "job_id": "58eae738-17e8-4d3a-9f57-a2e735f83925",
  "status": "pending",
  "model": "google/nano-banana-2-lite",
  "generation_type": "IMAGE_TO_IMAGE"
}

get_generation#

{
  "job_id": "58eae738…",
  "status": "completed",
  "output_urls": ["https://…"],
  "output_keys": ["media/{userId}/{generationId}/0.jpg"],
  "error": null,
  "cost_usd": 0.04,
  "created_at": "2026-08-11T03:26:08.900Z",
  "completed_at": "2026-08-11T03:27:42.841Z"
}

status is one of pending, processing, completed, or failed. On failed, error explains why and the cost is refunded.

output_urls are signed and valid for roughly an hour; output_keys are the permanent storage keys. If signing fails, output_urls comes back empty while output_keys stays populated, so a completed job is never lost.

upload_media#

Stores reference media and returns its key. Fetches the source server-side, so file bytes never pass through the conversation.

{
  "key": "generations/inputs/{userId}/{uuid}-ref.png",
  "media_type": "image",
  "size_bytes": 1106817
}

Only image/*, video/*, and audio/* content types are accepted, up to 50 MB.

Uploading a local file

upload_media needs a URL, so a file on disk goes to the upload endpoint directly:

curl -X POST https://api.modelstack.cc/v1/media/upload \
  -H "Authorization: Bearer YOUR_MODELSTACK_API_KEY" \
  -F file=@reference.png

{ "key": "generations/inputs/{userId}/{uuid}-reference.png", "mediaType": "image" }

Workflows#

Text to image#

list_generation_models(category: "image")
generate_image(model: "google/nano-banana-2", prompt: "…",
               settings: { aspect_ratio: "16:9", resolution: "2K" })
get_generation(job_id)   ← repeat until completed

Image to image with a reference#

upload_media(source_url: "https://cdn.example/seed.png")
  → { key: "generations/inputs/…" }

generate_image(model: "google/nano-banana-2-lite",
               prompt: "make the background deep navy",
               generation_type: "IMAGE_TO_IMAGE",
               input_media: [{ type: "image", key: "generations/inputs/…" }])
get_generation(job_id)

Delegating to a cheaper model#

llm_chat(model: "claude-haiku-4-5",
         system: "Reply with one sentence.",
         prompt: "Summarize this changelog: …")

Errors#

Tool-level failures come back as a normal result with isError: true and a plain-text explanation, rather than a protocol error — this lets the calling model read the message and correct itself. Common cases:

Next steps#