Kalpana MCP Documentation

Best practices and human-in-the-loop patterns for building safe template-to-batch automation.

When an AI agent designs, prepares, or executes creative batches with Kalpana, it must follow the Safe Template-to-Batch Lifecycle. This workflow prevents accidental credit expenditure, validates formatting before submitting jobs, and protects workspace boundaries.

The Safe Template-to-Batch Lifecycle

1. Identify Workspace & Permissions

If the user's workspace context is not explicitly provided, call list_workspaces.

Check that the workspace has templates:read and batches:create permissions.
Never assume an ID; ask the user if multiple workspaces exist.

2. Search & Select a Template

Use search_templates with a descriptive query (minimum 3 characters) or an exact UUID:

Apply isAnimated: false for static images or true for motion graphics.
Present preview URLs to the user for visual confirmation before proceeding.

3. Inspect Configurable Inputs

Call get_template_inputs for the selected template:

Review each input's id, label, type (text, image, or style), and valueExample.
Note which fields are required vs optional.
Omitted fields preserve the template default. You do not need to resend values that should remain as designed.

4. Resolve Images Within the Workspace

If the template uses image layers:

Images belong to workspaces, not templates.
Use search_assets with the selected workspaceId.
Never reference assets from a different workspace.

5. Validate Batch Rows

Before creating a batch, call validate_batch:

Check row syntax against the input fields.
If validation errors are returned, fix typos or prompt the user for missing fields.

6. Create the Batch (First Confirmation)

Present the validated batch summary to the user:

Summarize template name, total rows, field overrides, and expected output format (png, jpeg, webp).
Obtain explicit user approval before calling create_batch.
create_batch registers pending jobs and returns the exact credit cost. It does not render yet.

7. Run the Batch (Second Confirmation)

Rendering consumes workspace credits:

Inform the user of the exact credit cost returned by create_batch:

"This batch will render 10 images and consume 10 credits. Shall I proceed?"
Obtain a separate, explicit user confirmation before calling run_batch.

8. Monitor & Retrieve Results

Call get_batch to track processing progress (pending → processing → completed).
Once completed, call get_batch_outputs to retrieve pre-signed download URLs.
Note: Download URLs are temporary; instruct users to download or sync them promptly.

Human-in-the-Loop Safeguards

Rule of Two Confirmations: An agent must never execute create_batch and run_batch in a single unprompted step.

Confirmation 1: Approval to stage the batch configuration (create_batch).
Confirmation 2: Approval of the exact stated credit expenditure (run_batch).

Recommended Agent System Prompt

If you are developing custom agent skills or system prompts, include this guidance:

You are a creative assistant with access to the Kalpana MCP server.
Follow these rules strictly:
1. Always call get_template_inputs before preparing batch data.
2. Respect template defaults: do not pass values for layers that should remain unchanged.
3. Validate all rows using validate_batch prior to creation.
4. Never call create_batch or run_batch without explicit user approval in the chat.
5. In your confirmation message before run_batch, always state the exact credit cost returned by create_batch.
6. Do not ask for or attempt to expose internal scene graphs or raw JSON files.

Agent Workflows & Skills