Available Tools

The MCP server exposes 14 model-visible tools across three categories. Three additional app-only tools—gallery_load, media_selector_load, and poll_run_status—support embedded widgets and are intentionally hidden from the model tool list.

Account
Generation Guidance
Direct Generation

Check credits and estimate cost before starting expensive generations.

get_balance

Check the user’s current Magica credit balance. Returns the raw microcredit value plus a human-readable string.

get_pricing

Get model or utility pricing; tool_pricing_catalog lists billing categories. Inspect research, shared compute and token costs as well as generation. Read billing defaults and exclusions: variable usage can change the final charge. Execution charges remain server-controlled.

Generate images, video, audio, speech, lipsync, transcriptions, and utility outputs.

search_tools

Browse the model catalog by category or use case and get model IDs.

get_model_schema

Get a model’s input schema, including types, defaults, conditional fields, and ranges.

execute_tool

Start one generation, a parallel batch, or a supported media utility operation.

get_run_status

Long-poll a direct model run by ID until it completes, fails, or is canceled.

upload_file

Upload media or other supported files to permanent Magica storage and receive a stable URL. See local upload steps and confirmation recovery.

get_generations

Browse recent generated and uploaded media with pagination.

Typical sequence: search_tools → get_model_schema → get_pricing → execute_tool → get_run_status when polling is needed. Media utilities use the same sequence as AI models.

Media utilities

Use tool_name: "generate" for utility models, with the selected utility ID in input.modelId. Discover the models available to your caller with search_tools, then fetch the schema before execution and use its exact fields.

{
  "tool_name": "generate",
  "input": {
    "modelId": "crop_image",
    "image_url": "https://example.com/your-image.png",
    "width_px": 100,
    "height_px": 100
  }
}

Use the same generate/modelId shape for independent calls inside batch_execute. Historical calls with a utility name in tool_name remain supported for compatibility. Utilities retain their existing prices and actual usage settlement; read get_pricing instead of assuming they are free.

Get Started

Guides

Reference

Available Tools

get_balance

get_pricing

list_generation_skills

load_magica_skills

get_generation_playbook

list_media_catalogs

search_media

show_media_selector

search_tools

get_model_schema

execute_tool

get_run_status

upload_file

get_generations

Media utilities