Kalpana MCP Server
Connect AI agents and LLMs to Kalpana's creative rendering engine via the Model Context Protocol.
The Kalpana MCP Server is the agent-facing gateway for Kalpana. It connects LLM reasoning environments—including ChatGPT, Claude, Cursor, and custom agent systems—directly to Kalpana's visual templating and batch image rendering pipeline using the standard Model Context Protocol (MCP).
Deployed as a hardened Cloudflare Worker at https://mcp.kalpana.one, the gateway provides a compact set of state-aware tools, standards-compliant OAuth 2.0 authentication, and rigorous privacy boundaries.
Quickstart
Connect your first agent to Kalpana MCP in under 5 minutes.
Tools Reference
Explore the 10 tools for workspaces, templates, assets, and batches.
Authentication & OAuth
Learn about PKCE S256, CIMD verification, and scoped access.
Agent Workflows
Follow the safe template-to-batch lifecycle with credit confirmations.
Client Guides
Step-by-step setup for ChatGPT, Claude Desktop, Cursor, and Codex.
Security & Rate Limits
Edge defense, 5-tier rate limiting, token hashing, and payload rules.
Architectural Principles
The Kalpana MCP architecture is deliberately designed around privacy, predictability, and user control:
1. Minimal Surface & Zero Scene Leaks
The gateway does not connect directly to internal databases or expose full Figma/Skia scene graphs. Agents inspect only clean, user-configurable variable inputs (text, image, and style controls). Internal layer positioning, vector nodes, and proprietary layouts remain completely private.
2. Human-in-the-Loop Safeguards
Image generation consumes rendering credits. The MCP tools enforce a two-stage execution model:
create_batchstages render jobs and returns the exact credit cost and row count without initiating rendering or deducting credits.run_batchrequires a distinct user confirmation where the agent clearly presents the confirmed cost before initiating execution.
3. Stateless Streamable HTTP
The server runs over standard Streamable HTTP transport (POST /mcp and POST /). Each request initializes a lightweight MCP server instance, authenticates the incoming bearer token against Kalpana's web backend (/api/agent/v1/*), and terminates cleanly without sticky worker state.
4. Workspace Isolation
All operations are scoped to individual workspaces. An agent cannot query assets from one workspace and apply them to a template in another. Kalpana workspace roles and permissions (templates:read, assets:read, assets:create, batches:read, batches:create, renders:read, creatives:read) are validated on every request.
Gateway Endpoints
The hosted worker at https://mcp.kalpana.one exposes the following endpoints:
| Endpoint | Method | Description |
|---|---|---|
/mcp | POST | Primary Streamable HTTP MCP endpoint for tool invocation and agent queries. |
/.well-known/oauth-protected-resource | GET | RFC 9728 Protected Resource metadata advertising the OAuth server and scopes. |
/.well-known/oauth-authorization-server | GET | RFC 8414 Authorization Server metadata supporting CIMD and PKCE. |
/oauth/authorize | GET | Starts authorization code flow; redirects user to Kalpana login & consent screen. |
/oauth/token | POST | Exchanges one-time authorization code or refresh token for access tokens. |
/oauth/revoke | POST | Revokes active OAuth access or refresh tokens. |
/oauth/register | POST | Dynamic client registration endpoint (RFC 7591) for compatible clients. |
/health | GET | Health check endpoint returning { "status": "ok" }. |
Some MCP clients target the root origin instead of the documented subpath. The Kalpana server accepts GET requests at / and responds with service metadata pointing to https://mcp.kalpana.one/mcp.