> ## Documentation Index
> Fetch the complete documentation index at: https://magica.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Available Tools

> All 23 MCP tools exposed by the Magica server, organized by category.

The MCP server exposes **23 tools** across five categories. Pick a category below to see what's available.

<Tabs>
  <Tab title="Account">
    Check credits and estimate cost before kicking off expensive jobs.

    <CardGroup cols={2}>
      <Card title="get_balance" icon="wallet">
        Check the user's current Magica credit balance. Returns the raw microcredit value plus a human-readable string.
      </Card>

      <Card title="get_pricing" icon="coins">
        Get the cost structure for a model, or compute the exact credit cost for a sample input. Purely informational — credits are charged automatically by `execute_tool`.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Direct Generation">
    The primary one-shot path for image, video, audio, TTS, lipsync, and transcription. **Use these instead of building a workflow for single-step generation.**

    <CardGroup cols={2}>
      <Card title="search_tools" icon="magnifying-glass">
        Browse the model catalog grouped by category (text-to-image, text-to-video, image-to-video, lipsync, TTS, music, sound effects, transcription, …). Returns model IDs.
      </Card>

      <Card title="get_model_schema" icon="list-tree">
        Get the full input parameter schema for a model — types, defaults, conditional fields, ranges. Required before calling `execute_tool` with an unfamiliar model.
      </Card>

      <Card title="execute_tool" icon="bolt">
        Run a generation or utility tool. Routes via `tool_name`: `generate`, `batch_execute`, `merge_videos`, `extract_audio`, and more. The single one-shot generation tool.
      </Card>

      <Card title="get_run_status" icon="circle-info">
        Long-poll a run by ID. Returns the final result or a still-running response to call again. Replaces the older `get_run` / `get_model_run`.
      </Card>

      <Card title="upload_file" icon="upload">
        Upload an image / video / audio / raw file to permanent Magica storage. Accepts `url`, `data_uri`, or `base64`. Returns a stable URL + metadata.
      </Card>

      <Card title="get_generations" icon="images">
        Browse the user's recent media-library items (generated assets + uploads). Paginated — uses a 'Load more' widget rather than refetching.
      </Card>
    </CardGroup>

    <Tip>
      Typical flow: `search_tools` → `get_model_schema(modelId)` → `execute_tool({ tool_name: "generate", input: { modelId, … } })` → (if needed) `get_run_status(runId)`.
    </Tip>
  </Tab>

  <Tab title="Workflows">
    Manage saved workflows and browse pre-built templates.

    <CardGroup cols={2}>
      <Card title="list_system_workflows" icon="cubes-stacked">
        Browse pre-built workflow templates. Filter by category: image, video, audio, utility, llm.
      </Card>

      <Card title="list_workflows" icon="list">
        List the user's saved workflows with optional search and pagination. Returns id, name, updatedAt.
      </Card>

      <Card title="get_workflow" icon="magnifying-glass">
        Get full details of a workflow including nodes, edges, description, and timestamps.
      </Card>

      <Card title="create_workflow" icon="plus">
        Create a new workflow with Request and Response scaffold nodes. Optionally add request input fields.
      </Card>

      <Card title="update_workflow" icon="pen">
        Rename or update a workflow's metadata. Does not modify nodes or edges.
      </Card>

      <Card title="delete_workflow" icon="trash">
        Permanently delete a workflow by ID. This action cannot be undone.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Workflow Builder">
    Programmatically build and edit workflow graphs.

    <CardGroup cols={2}>
      <Card title="list_node_types" icon="cubes">
        List available node types with their input/output ports, data types, categories, and modes. Use to discover what nodes can be added.
      </Card>

      <Card title="add_node" icon="circle-plus">
        Add a workflow step. Supports column/row positioning and initial input values. Returns the new node ID and its ports.
      </Card>

      <Card title="update_node" icon="pen-to-square">
        Update input values on an existing node without removing it or its edges.
      </Card>

      <Card title="connect_nodes" icon="link">
        Create a validated edge between two nodes. Checks type compatibility, prevents cycles, enforces single-input rules.
      </Card>

      <Card title="disconnect_nodes" icon="link-slash">
        Remove an edge between two nodes by edge ID or source/target pair.
      </Card>

      <Card title="delete_node" icon="circle-minus">
        Remove a node from a workflow. All connected edges are cleaned up automatically. Cannot delete scaffold nodes (Request, Response).
      </Card>
    </CardGroup>

    See [Building Workflows](/mcp-server/building-workflows) for step-by-step examples.
  </Tab>

  <Tab title="Workflow Runs">
    Start, monitor, and cancel workflow runs.

    <CardGroup cols={2}>
      <Card title="start_run" icon="play">
        Start a workflow run by ID or name. Searches user workflows first, falls back to system workflows. Validates Request Node fields automatically.
      </Card>

      <Card title="list_runs" icon="list">
        List workflow runs with optional filters (workflow, status, search) and cursor or page-based pagination.
      </Card>

      <Card title="cancel_run" icon="xmark">
        Cancel a running or queued workflow run. Refunds unused estimated credits.
      </Card>
    </CardGroup>

    <Note>
      To check the **status** or **result** of a workflow run, use `get_run_status` from the Direct Generation tab — it handles both workflow runs and one-shot generations.
    </Note>

    See [Runs & Execution](/mcp-server/runs) for request-node handling, polling patterns, and the run result shape.
  </Tab>
</Tabs>