Tools Reference

The Kalpana MCP Server exposes 10 tools grouped into four capability domains: Workspaces, Templates, Assets, and Batches & Rendering.

---

Tool Overview

---

Workspace Tools

list_workspaces

Lists workspaces accessible to the authenticated user along with their role and permission scopes. Always start here if the user's workspace context is ambiguous.

• Annotations: readOnlyHint: true, openWorldHint: false
• Input Parameters: None ({})
• Output Schema:

  {
    items: Array<{
      id: string;             // Workspace ID
      name: string;           // Workspace display name
      slug: string;           // URL slug
      organizationId: string; // Organization UUID
      role: string;           // User's workspace role (e.g., "owner", "admin", "member")
      permissions: Array<     // Scopes allowed for the current MCP connection
        | "templates:read"
        | "assets:read"
        | "assets:create"
        | "batches:read"
        | "batches:create"
        | "renders:read"
        | "creatives:read"
      >;
    }>
  }

---

Template Tools

search_templates

Search for templates by name, campaign topic, or description, or look up a specific template by its exact UUID. Supports filtering by dimensions, animation, and preview availability.

• Annotations: readOnlyHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Default	Description
  query	string	Yes	—	Search term (min 3 chars) or exact UUID.
  workspaceId	string	No	—	Limit search to a specific workspace.
  hasPreview	boolean	No	false	When true, returns only templates with preview URLs.
  width	number	No	—	Filter by exact pixel width.
  height	number	No	—	Filter by exact pixel height.
  isAnimated	boolean	No	—	true for motion templates, false for static.
  page	number	No	1	Page number.
  limit	number	No	10	Results per page (capped at 20).

• Output Schema:

  {
    items: Array<{
      id: string;             // Template UUID
      name: string;           // Display name
      description: string | null;
      workspaceId: string;
      workspaceName: string;
      organizationId: string;
      enabled: boolean;
      visible: boolean;
      hasDefault: boolean;    // Whether omitting this input preserves a template default
      width: number | null;
      height: number | null;
      isAnimated: boolean;
      previewUrl: string | null;
      openUrl: string | null;
      variableCount: number;
    }>;
    total: number;
    page: number;
    limit: number;
  }

---

get_template_inputs

Retrieves all customizable inputs exposed by a template without exposing private layer hierarchies or internal vector scene nodes.

• Annotations: readOnlyHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Default	Description
  templateId	string	Yes	—	UUID of the template.
  includeDisabled	boolean	No	false	Include inputs currently disabled in template settings.
  includeHidden	boolean	No	false	Include inputs marked as hidden in template settings.

• Output Schema:

  {
    id: string;
    name: string;
    description: string | null;
    width: number | null;
    height: number | null;
    isAnimated: boolean;
    inputs: Array<{
      id: string;             // Field identifier used in batch row data
      label: string;          // Human-friendly label
      type: "text" | "image" | "style";
      required: boolean;
      description: string | null;
      defaultValue?: string;
      valueExample: Record<string, unknown>; // Example structure for formatting row values
    }>;
    openUrl: string | null;
  }

---

Asset Tools

search_assets

Searches for approved, ready-to-use PNG, JPEG, and WebP images in the specified workspace.

• Annotations: readOnlyHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Default	Description
  workspaceId	string	Yes	—	Workspace ID to search within.
  query	string	Yes	—	Search term (min 3, max 100 characters).
  page	number	No	1	Page number.
  limit	number	No	8	Items per page (capped at 12).

• Output Schema:

  {
    items: Array<{
      id: string;             // Asset UUID
      filename: string | null;
      contentType: "image/png" | "image/jpeg" | "image/webp";
      sizeBytes: number;      // Size in bytes (under 5 MB)
      createdAt: string;      // ISO 8601 timestamp
      previewUrl: string;     // URL to inspect or preview the asset
    }>;
    total: number;
    page: number;
    limit: number;
  }

---

Batch & Rendering Tools

validate_batch

Validates tagged row inputs against template constraints before creating a batch. Identifies missing required fields, invalid image URLs, or formatting mismatches.

• Annotations: readOnlyHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Description
  templateId	string	Yes	Template UUID.
  rows	Array<BatchRow>	Yes	1 to 500 rows with field key/value mappings.

• Output Schema:

  {
    valid: boolean;
    rowCount: number;
    validRows: number;
    invalidRows: number;
    issues: Array<{
      rowIndex: number;
      field: string;
      message: string;
    }>;
  }

---

create_batch

Creates pending render jobs for a validated batch. Does not spend credits or start rendering.

• Annotations: readOnlyHint: false, destructiveHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Default	Description
  templateId	string	Yes	—	UUID of the target template.
  name	string	Yes	—	Name describing the campaign or batch.
  rows	Array<BatchRow>	Yes	—	1 to 500 formatted rows.
  outputFormat	string	No	"png"	"png", "jpeg", or "webp".

• Output Schema:

  {
    id: string;               // Created Batch UUID
    templateId: string;
    rowCount: number;
    creditCost: number;       // Exact number of credits required to run
  }

---

run_batch

Dispatches rendering jobs for a pending batch. Consumes credits from the workspace.

• Annotations: readOnlyHint: false, destructiveHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Description
  batchId	string	Yes	UUID returned by create_batch.

• Output Schema:

  {
    message: string;
    dispatched: number;       // Number of jobs sent to workers
    failed: number;           // Number of jobs that failed dispatch
  }

---

get_batch

Queries real-time execution status and row processing counts for a batch.

• Annotations: readOnlyHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Description
  batchId	string	Yes	UUID of the batch.

• Output Schema:

  {
    id: string;
    name: string;
    templateId: string;
    createdAt: string;
    total: number;
    completed: number;
    failed: number;
    processing: number;
    status: "pending" | "processing" | "completed" | "failed";
  }

---

list_batches

Returns a paginated list of recent batches for templates accessible to the user.

• Annotations: readOnlyHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Default	Description
  templateId	string	No	—	Optional template filter.
  page	number	No	1	Page number.
  limit	number	No	10	Items per page (capped at 20).

• Output Schema:

  {
    items: Array<{
      id: string;
      name: string;
      templateId: string;
      createdAt: string;
      totalRows: number;
      completedRows: number;
      failedRows: number;
      processingRows: number;
      status: "pending" | "processing" | "completed" | "failed";
    }>;
    total: number;
    page: number;
    limit: number;
  }

---

get_batch_outputs

Fetches download URLs for completed creative renders. Download links are pre-signed and short-lived.

• Annotations: readOnlyHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Default	Description
  batchId	string	Yes	—	UUID of the completed batch.
  page	number	No	1	Page number.
  limit	number	No	10	Items per page (capped at 20).

• Output Schema:

  {
    items: Array<{
      id: string;             // Output file UUID
      status: string;         // "completed", "failed"
      outputKind: string;     // "image", "video"
      outputFormat: string;   // "png", "jpeg", "webp", "mp4"
      contentType: string | null;
      downloadUrl: string | null; // Pre-signed download link
    }>;
    page: number;
    limit: number;
  }