Kalpana Docs

Let an AI agent design and edit Kalpana templates, then hand them to the batch server to fill with data.

The Kalpana designer MCP is the second MCP server on the Kalpana gateway. It gives an agent Kalpana's design tools: the agent creates and edits templates in your workspace, with layers, layout flows, fonts from Kalpana's library, the workspace's own images, a page per size and motion. It checks its work with a layout check and rendered previews, then saves the template.

It does not fill templates with data or render batches. That is the job of the batch server at /mcp. A template's ID is the same on both servers, so an agent connected to both can design a template and then run a batch with it.

https://mcp.kalpana.one/mcp/designer

Designer Tools

The 39 tools for templates, layers, checks, measuring and motion.

Client Guides

Add the designer next to the batch server in your client.

Batch Tools

Fill the finished template with rows and render it.

Which Server Does What

Task	Server
Design a new template from a brief	Designer
Change a template's layout, copy, colours, images or motion	Designer
Add a page at another size, or copy pages into a template	Designer
Name a template and describe what each input may hold	Designer
Find templates	Both (`search_templates`)
Read a template's inputs, validate rows, create and run batches	Batch
Download finished images and videos	Batch

Access and Cost

Plan

The designer needs an active Kalpana subscription for the workspace's organization. Free trial credits and top-up credits alone do not open it. list_workspaces reports whether the connected workspace's designer subscription is active. Without one, design tools answer:

The Kalpana designer needs an active subscription for this workspace's organization. Subscribe at <billing page>.

Credits

Designer calls are paid from the workspace's render credits. One credit buys a block of 20 calls; when a block is used up, the next paid call buys another. Calls left in a block stay with the workspace for later calls, and a call that fails on Kalpana's side is given back.

These tools are free: design_guide, calculate, color_math, measure_text, stagger_times, list_workspaces and search_templates. Every other call is paid, reads and checks included.

When the workspace has no render credits left, paid calls answer:

Designer calls need render credits: one credit pays for 20 calls, and this workspace has none left. Top up at <billing page>.

A design built in a few large calls costs far less than one built in many small ones: build the whole layer tree in one create_layers call and send fixes together in one update_layers call.

Role

The designer asks for templates:create and templates:update as well as read access, so only workspace roles that can create and edit templates (Owner, Manager and Designer) can design. Like the batch server, a connection covers one workspace, chosen on the consent screen; to design in another workspace, reconnect and choose it.

How an Agent Designs

The server's instructions and its design_guide tool teach agents this loop.

Get the brief

The agent reads design_guide, then gathers what the work needs from the conversation, asking only for what is missing: the intent (a casual post, awareness, a conversion ad, an event, a carousel), the platforms and their sizes, and the brand (name, logo, colours, fonts, tone). A quick post needs three answers; a campaign gets the full brief.

Create the page

create_design makes a page at the size the platform needs (1080 × 1080 post, 1080 × 1920 story, 1920 × 1080 or 1200 × 628 banner) and saves it in the workspace at once. It returns a page_id, which every design tool takes, and a template_id.

Build in one call

list_fonts gives the font families the agent may use; find_images finds the workspace's logos and product photos. create_layers then builds the whole layer tree in one call, with layout flows for anything that is a row or a stack, and an id the agent chooses for each layer.

Check the work

check_layout reports text over text, layers cut off, text too small for the size the design is seen at, and weak contrast. render_design returns a preview the agent looks at, zoomed into a layer or region for small text. Fixes go back in one update_layers call.

Plan for every row and size

The agent tests the longest copy it expects, so the layout survives your data. Another size is duplicate with a new width and height; the flows and constraints place the layers again, and the agent adjusts what the size needs.

Save

set_template_info names the template, describes it and describes each input with its length limit ("Headline: up to 2 lines, about 45 characters"). It also saves every change still waiting, so it is the last call.

Every call that changes a design takes an intent: one short sentence of what changes and why, kept in the design's history. Reads take none. undo steps a design back one change.

From Design to Batch

sequenceDiagram
    participant User
    participant Agent as AI agent
    participant Designer as Designer MCP (/mcp/designer)
    participant Batch as Batch MCP (/mcp)

    User->>Agent: Brief: a festive sale post, square and story
    Agent->>Designer: create_design, create_layers, check_layout, render_design
    Agent->>Designer: duplicate (story size), set_template_info
    Designer-->>Agent: template_id, page_ids
    Agent->>Batch: get_template_inputs, validate_batch, create_batch
    Batch-->>Agent: Draft batch with its credit cost
    User->>Agent: Yes, run it
    Agent->>Batch: run_batch, get_batch_outputs

The designer writes ids as template_id and page_id; the batch tools write the same values as templateId and pageId.
Every text and image layer is an input. Its name is the input's label, so agents name layers by what they hold ("Headline", "Price", "Product photo"). Batch rows key layers by name, or by id when two layers share a name.
Each page has its own inputs, keyed by layer id. The template's data columns merge every page's, and the same id on two pages becomes one column, such as a logo that appears on every page.
An image placed in a design by its image key from find_images is the same image a batch row names by its asset_id or file name.
Text with several styles (one word in an accent colour) takes style tags in batch rows: its distinct styles are s1, s2, … in order of first use, as in <s1>Masala chai, </s1><s2>₹49</s2>.

Images and Fonts

Fonts come only from Kalpana's library for the workspace (the global library and the workspace's uploads), because batches load their fonts from Kalpana. list_fonts lists them, and any other font_family is refused.
Images are the workspace's own (find_images), the user's uploads (upload_images: PNG, JPEG or WebP, up to 5 MB each), or public https links. A linked image is copied into the workspace's assets when it is placed, and the design keeps that copy, so batches never fetch it from outside. The workspace's allowed image domains apply; a refused link is reported.
An image the agent only sees in the chat cannot be sent as data. upload_images without files returns a link where the user drops the images into the workspace.

Motion

A design can move: layers carry keyframes on a timeline. animate adds presets (fade, slide, pop, spring, draw-on and more), and builders such as kinetic_type, make_transition, make_particles, make_cursor, make_list, make_carousel and camera make layers and their motion in one call. Agents check motion as frames with render_contact_sheet and render_timeline.

This server exports no video. A moving template renders as video in the Kalpana app, or through the batch server with create_batch and an mp4 or gif output format. As images, each row shows one moment of the motion: the batch's own still time, else the page's still_time from set_timeline, else the last frame.

Previews

render_design and render_contact_sheet return PNG previews for the agent to judge the work by, not files to use. Previews are at most 800 px on the longest side (contact sheet frames at most 320 px wide) and carry a faint repeating "Kalpana preview" mark. The mark is never in the template, its exports or batch renders, and sample_points read the design's own colours.

Working with the Kalpana App

A template the designer saves is a normal Kalpana template: open it in the template editor (search_templates gives a link) and change anything.

Changes are saved to the template a few seconds after each call, and set_template_info saves anything still waiting.
When someone edits the page in Kalpana, the agent's next call works on that version, and the reply says the page was changed in Kalpana so the agent reads it with get_design first. To change a layer only if it is still as the agent read it, update_layers takes the layer's etag from get_design as if_match.
Calls on one workspace run one at a time.

Errors

Message	What it means
`needs an active subscription`	The workspace's organization has no active plan. Subscribe on the billing page, then try again.
`need render credits`	The workspace has no render credits for the next block of calls. Top up on the billing page.
`was changed in Kalpana`	Someone edited the page in the app since the agent's last call. That call worked on the new version; read it with `get_design` before changing what was edited.
Unknown field	A field the tool does not take. The error lists the valid fields.
`401 Unauthorized`	The token expired or was revoked. The client signs in again.

Limits

Limit	Value
Designer tool calls from one connected assistant	60 per minute
Page size from `create_design`	1 to 8192 px a side
Page size from `duplicate`	1 to 8000 px a side
Preview size	800 px on the longest side
Image upload	PNG, JPEG or WebP, up to 5 MB each, 20 per call
A tool call	1 MB

See Security & Rate Limits for the gateway's other limits.

Designer MCP

Designer Tools

Client Guides

Batch Tools

On this page