Skip to main content

Connect AI assistants to OKZest with MCP

OKZest includes an MCP (Model Context Protocol) server so AI assistants and AI-powered tools can work directly with your designs.

Instead of building your own integration, you can connect your OKZest account and ask a tool such as Claude, ChatGPT, or Copilot to:

  • List the designs and projects in your account
  • Check which fields a design supports
  • Generate a live personalised image URL
  • Edit a design's layers and render a one-off image

What you need​

Before you start, make sure you have:

  1. An OKZest account
  2. At least one design in your account
  3. An API key from Settings -> API Keys
  4. An MCP-compatible AI tool or client

The MCP server uses the same API key as the REST API.

MCP server URL​

Your AI tool should connect to:

https://api.okzest.com/mcp

Example configuration​

Many MCP clients let you define servers in a JSON config file.

Add an OKZest server like this:

{
  "servers": {
    "okzest": {
      "url": "https://api.okzest.com/mcp",
      "headers": {
        "x-api-key": "YOUR_OKZEST_API_KEY"
      }
    }
  }
}

Replace YOUR_OKZEST_API_KEY with an API key from Settings -> API Keys in your OKZest dashboard.

caution

Keep your API key private. Do not paste it into public repos, public prompts, or client-side code.

How it works​

The MCP server gives your AI tool 6 OKZest actions.

1. Find your designs​

Technical tool name: list_designs(projectName?, nameContains?, pageSize?, pageNumber?)

This lists every design in your account and returns:

  • Design ID
  • Design name
  • Render URL
  • Project ID and project name
  • Available URL parameters
  • Billing cycle open count
  • Lifetime open count

All parameters are optional:

  • projectName filters the results to designs that belong to a project with that name (case-insensitive, exact match)
  • nameContains filters the results to designs whose name contains the given text (case-insensitive substring match)
  • pageSize and pageNumber page through the results together, for example pageSize: 20, pageNumber: 2 returns the second page of 20 designs

Leave all of them out to list every design in the account.

Use this when you want the AI tool to discover what is available in your account, narrow the search to a specific project or name, or work through a large account a page at a time, for example:

List my OKZest designs in the "Q1 Campaign" project.
Find my OKZest designs with "banner" in the name.

2. List your projects​

Technical tool name: list_projects()

This lists every project in your account and returns:

  • Project ID
  • Project name
  • Design count
  • Billing cycle open count
  • Lifetime open count

Use this when you want the AI tool to discover which projects exist before narrowing a list_designs search, or when you just want an overview of how designs are organised, for example:

What projects do I have in OKZest, and how many designs are in each?

3. Check what a design accepts​

Technical tool name: get_design(id)

This returns the full details for one design, including the available URL parameters for dynamic text and image layers.

Always do this before generating a URL. It tells the AI tool the exact parameter names to use.

For example, a design might support parameters such as:

[
  { "name": "name" },
  { "name": "title" },
  { "name": "company" }
]

4. Generate a live image URL​

Technical tool name: generate_image_url(designId, urlParams?)

This creates a runtime image URL for the design.

urlParams is optional and is passed as a JSON object string, for example:

{"name":"Jane","title":"CEO"}

The returned URL can be dropped straight into an email, web page, workflow, or automation step.

info

OKZest does not pre-render or save the image when this tool runs. It only returns a URL. The image is rendered fresh every time that URL is requested.

5. Inspect editable layers​

Technical tool name: get_design_fields(designId)

This returns the editable layers for a design, including each layer's layer_id, type, and the exact properties that layer supports.

For example, a text layer may support properties such as text, color, font_size, font_family, font_weight, x, y, width, height, opacity, and stroke, border, or shadow settings. An image layer may support properties such as image_url, x, y, width, height, and opacity.

This mirrors the REST endpoint GET /v1/images/{designId}/fields.

Use this when you want the AI tool to edit real layer properties instead of only filling URL parameters.

6. Modify layers and render an image​

Technical tool name: modify_design_layers(designId, layersJson, backgroundJson?, format?, quality?)

This applies one or more layer edits, renders the image server-side, and returns:

  • imageUrl
  • mimeType
  • expiresInSeconds

layersJson is passed as a JSON array string, for example:

[
  {
    "layer_id": "heading",
    "text": "Hello",
    "color": "#ff0000"
  }
]
caution

modify_design_layers returns a temporary URL

generate_image_url and modify_design_layers are not interchangeable.

  • generate_image_url returns a permanent runtime URL. Nothing is stored, so you can reuse that URL indefinitely.
  • modify_design_layers renders once, stores the result temporarily, and returns a blob URL that expires after 30 seconds.

Download, forward, or display the modify_design_layers result immediately. Do not save it as a permanent embed URL.

For best results, ask your AI tool to follow one of these orders:

For discovering what you have​

  1. list_projects
  2. list_designs (optionally filtered by projectName or nameContains)

For URL-parameter personalisation​

  1. list_designs
  2. get_design
  3. generate_image_url

For layer editing​

  1. list_designs
  2. get_design_fields
  3. modify_design_layers

This helps the AI tool choose the right design and use valid parameter names or layer properties.

Worked example​

Here is a simple example using an AI assistant to create a personalised image URL.

Step 1 - ask the assistant to find your design​

List my OKZest designs and find the one for my welcome email banner.

The assistant should use list_designs and return the matching design. If you know which project it lives in, you can narrow the search with list_designs(projectName: "Marketing").

Step 2 - ask it to inspect the design​

Get the details for that design and show me the available parameters.

The assistant should use get_design(id) and identify the parameter names, such as name and title.

Step 3 - ask it to create the URL​

Generate a personalised image URL for Jane, title CEO.

The assistant should use:

generate_image_url(
  designId: "YOUR_DESIGN_ID",
  urlParams: "{\"name\":\"Jane\",\"title\":\"CEO\"}"
)

The result will be a live OKZest image URL that you can paste into an <img> tag, an email platform, or an automation tool.

Worked example: editing design layers​

Here is a simple example using an AI assistant to edit a layer's text and colour before rendering the image.

Step 1 - ask the assistant to find your design​

List my OKZest designs and find the one for my webinar banner.

The assistant should use list_designs and return the matching design.

Step 2 - ask it to inspect the editable layers​

Show me the editable layers for that design and tell me which properties the heading layer supports.

The assistant should use get_design_fields(designId) and identify a layer such as heading with editable properties including text and color.

Step 3 - ask it to render the edited image​

Change the heading text to Hello Jane and make it red.

The assistant should use:

modify_design_layers(
  designId: "YOUR_DESIGN_ID",
  layersJson: "[{\"layer_id\":\"heading\",\"text\":\"Hello Jane\",\"color\":\"#ff0000\"}]"
)

The result will be a temporary image URL that should be consumed immediately before it expires.

Good use cases​

The MCP server is a good fit when you want an AI tool to help with:

  • Email personalisation
  • Sales outreach images
  • Customer onboarding images
  • Zapier or Make workflows
  • A/B testing different personalised image variants
  • Editing a design's layers programmatically via AI
  • Auditing or organising a large design library by project, with search and pagination

If you are already using automation tools, see the Zapier integration page as well.

Authentication​

OKZest authenticates MCP requests with the x-api-key HTTP header.

  • Missing API key: the request is rejected
  • Invalid API key: the request is rejected
  • Valid API key: the AI tool can access designs in that OKZest account

This is the same API key model used by the REST API.

When to use MCP vs REST API​

Use MCP when you want an AI assistant or AI-powered tool to discover designs, generate runtime image URLs, or render one-off layer-edited images for you.

Use the REST API when you want to build a traditional coded integration or request binary image output directly.

Skill file for your AI tool​

If your AI tool supports installable "skills" (for example, Copilot CLI, Claude, or other agent skill directories), you can download a ready-made skill file that teaches it the full OKZest MCP workflow:

Download okzest-image-generation SKILL.md

Save it into your tool's skills folder (e.g. .github/skills/okzest-image-generation/SKILL.md, .claude/skills/, or .agents/skills/) alongside the MCP server configuration above.